---
title: "Send your first XiuRouter API request"
description: "Create a scoped XiuRouter API key, list available models, and test Chat Completions, Responses, Messages, or Gemini GenerateContent."
image: "https://docs.xiu.ai/og.png"
---

> XiuAI 文档索引
> 完整文档索引：https://docs.xiu.ai/llms.txt
> 阅读前先通过索引确认当前可用页面。

# Send your first XiuRouter API request

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.

> **The model request is billable**
>
> Check the current model, service group, and price before sending the test. The final request uses your account balance and the API key's own quota.

## Prerequisites

- You can sign in to [XiuRouter](https://router.xiu.ai/en/).
- The account has available credit.
- You have `curl`.
- You have selected a model from the current [models and pricing page](https://router.xiu.ai/en/pricing).

## Create a scoped API key

1. Open **API Keys** in the XiuRouter console.
2. Create a key with a name that identifies this application.
3. Select the service group or automatic group order you intend to use.
4. Limit the key to the required models when the application does not need the full catalogue.
5. Set a quota and expiration date when appropriate.
6. 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:

```bash
export XIUROUTER_API_KEY="YOUR_XIUROUTER_API_KEY"
```

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

## List available models

```bash
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

```bash
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

```bash
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"
  }'
```

### Anthropic Messages

```bash
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

```bash
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.

## 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

```bash
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

This page was checked against the current XiuRouter console, key controls, public API status, and model catalogue on August 22, 2026. The examples use placeholders and no real billable key was used during this review.

源文件：https://docs.xiu.ai/en/router/quickstart/index.mdx