Send your first XiuRouter API request

Create a scoped XiuRouter API key, list available models, and test Chat Completions, Responses, Messages, or Gemini GenerateContent.

This quickstart creates a scoped API key, reads the models available to that key, and sends one small text request through the direct XiuRouter API domain.

Prerequisites

You can sign in to XiuRouter.
The account has available credit.
You have curl.
You have selected a model from the current models and pricing page.

Create a scoped API key

Open API Keys in the XiuRouter console.
Create a key with a name that identifies this application.
Select the service group or automatic group order you intend to use.
Limit the key to the required models when the application does not need the full catalogue.
Set a quota and expiration date when appropriate.
Open the key row and copy the complete key value.

A key with model restrictions enabled and an empty model list cannot call any model. Do not solve a configuration problem by switching to an unlimited shared key.

Set a temporary environment variable

The examples below keep the key in the current shell:

export XIUROUTER_API_KEY="YOUR_XIUROUTER_API_KEY"

Do not write the real key into a repository or shell script.

List available models

curl https://router-api.xiu.ai/v1/models \
  -H "Authorization: Bearer $XIUROUTER_API_KEY"

A successful response returns HTTP 200 and the models visible to this key. Copy an exact model ID from the response or the console. Do not guess aliases from a vendor name.

Send a text request

Use the example that matches your client protocol.

Chat Completions

curl https://router-api.xiu.ai/v1/chat/completions \
  -H "Authorization: Bearer $XIUROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "Reply only with: XiuRouter connected"
      }
    ]
  }'

Responses

curl https://router-api.xiu.ai/v1/responses \
  -H "Authorization: Bearer $XIUROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "input": "Reply only with: XiuRouter connected"
}'

Omit service_tier from the first Responses request and verify the default processing mode. When the selected model’s pricing row lists Fast or Flex, these examples use service_tier: "priority" for Fast and service_tier: "flex" for Flex. The mode changes the current request’s token rates; confirm the final rule and charge in Usage.

Anthropic Messages

curl https://router-api.xiu.ai/v1/messages \
  -H "x-api-key: $XIUROUTER_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "max_tokens": 64,
    "messages": [
      {
        "role": "user",
        "content": "Reply only with: XiuRouter connected"
      }
    ]
  }'

Gemini GenerateContent

curl https://router-api.xiu.ai/v1beta/models/YOUR_MODEL_ID:generateContent \
  -H "x-goog-api-key: $XIUROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Reply only with: XiuRouter connected"
          }
        ]
      }
    ]
  }'

A successful request returns HTTP 200 and protocol-specific text output. Open Usage or the request verification panel in XiuRouter and confirm the same key, model, endpoint, service group, and successful status. For dynamically priced models, also check the matched context tier, the applied service_tier rule, and any separate tool surcharge.

Common failures

Symptom	Check	Action
`401` or `Invalid token`	Missing, incomplete, disabled, or expired key	Read the environment variable again and rotate the key only if it is invalid
`403`	Account credit, key quota, model scope, group scope, expiration, or IP restriction	Fix the narrow restriction that rejected the request
Model not found	Exact model ID and current service group	Copy the current ID from `/v1/models` or the pricing page
Insufficient balance or quota	Account credit and the key’s own quota	Add credit or raise only the application key’s quota
Streaming request stops	Base URL and duplicated `/v1` path	Use `router-api.xiu.ai`; OpenAI clients use `/v1`, while Messages and Gemini clients use the API root
`5xx` or upstream error	Request ID, timestamp, model, group, and original error	Retry once, then retain those fields for diagnosis

Remove the temporary key

unset XIUROUTER_API_KEY

For a long-lived application, create one dedicated key per environment and keep its model, quota, expiration, and IP scope as narrow as the deployment allows.

Sources and review date

The processing-mode examples were reviewed against the current public pricing rules on September 13, 2026. The console, key controls, API status, model catalogue, and short billable Responses request were checked on September 5, 2026. The examples keep credentials as placeholders.