---
title: "发起第一次 XiuRouter API 请求"
description: "登录 XiuRouter、创建受限 API Key，并用 Chat Completions、Responses、Messages 或 Gemini GenerateContent 完成第一次调用。"
image: "https://docs.xiu.ai/og.png"
---

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

# 发起第一次 XiuRouter API 请求

完成本篇后，你会拿到一把有明确范围的 API Key，能通过 `router-api.xiu.ai` 读取模型列表并收到一次文本回复。

> **这会产生真实调用**
>
> 最后的模型请求会按当前模型、服务分组和实际 Token
> 用量计费。先在价格页确认模型与服务档位，再发送小请求。

## 已在使用其他 API 服务

如果当前客户端使用 Chat Completions、Responses、Anthropic Messages 或 Gemini GenerateContent，通常不需要重新配置整个应用。先按协议替换连接信息：

| 协议 | Base URL | 认证 |
| --- | --- | --- |
| OpenAI Chat Completions | `https://router-api.xiu.ai/v1` | `Authorization: Bearer` |
| OpenAI Responses | `https://router-api.xiu.ai/v1` | `Authorization: Bearer` |
| Anthropic Messages | `https://router-api.xiu.ai` | `x-api-key`；部分客户端使用 Bearer Token |
| Gemini GenerateContent | `https://router-api.xiu.ai` | `x-goog-api-key` 或 `key` 查询参数 |

把认证值换成你的 XiuRouter API Key。目标模型 ID 在 XiuRouter 中相同时，其他请求配置可以先保持不变；目录中没有相同 ID 时，再替换模型 ID。Anthropic 客户端通常会自行追加 `/v1/messages`，Gemini 客户端会追加 `/v1beta/models/{model}:generateContent`，因此这两类客户端的 Base URL 都不要加 `/v1`。使用专有接口时，先查看[API 兼容范围](/router/api-compatibility)，不要只替换地址。

`router-api.xiu.ai` 让模型请求直连服务节点，不经过控制台的边缘转发。对中国大陆网络通常链路更短，也更适合长流式响应；实际速度仍取决于当前网络。

## 前置条件

- 可以登录 [XiuRouter](https://router.xiu.ai/) 的 XiuAI 账号。
- 账号有可用调用额度；需要从钱包补充时，钱包有可用余额。
- 已在[模型与价格](https://router.xiu.ai/pricing)找到准备调用的模型 ID。
- 本机有 `curl`，并能访问 `https://router-api.xiu.ai`。

## 创建 API Key

1. 登录 XiuRouter，打开“API Key”。
2. 新建 API Key，填写便于识别的名称。
3. 选择服务分组。需要限制用途时，只开放本次要用的模型。
4. 按需要设置剩余额度和有效期。
5. 创建后回到列表，点击该行的“密钥”，再复制完整值。

模型限制打开后不能留空；空列表表示这把 Key 不能调用任何模型。完整密钥可以按需重新读取，不是只显示一次；每次查看后都应关闭窗口，不要把它留在截图或剪贴板历史中。

## 临时设置环境变量

下面的示例只让当前终端会话读取密钥。把示例值换成你自己的 XiuRouter API Key，不要把真实值写入仓库：

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

## 读取可用模型

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

成功时返回 `200` 和模型列表。复制你准备调用的精确模型 ID；不要根据厂商名猜别名。

## 发送第一次请求

先从模型与价格页复制模型 ID，再运行与你的客户端协议一致的示例。公共目录的 `supported_endpoint_types` 可以帮助识别部分协议，但当前 Responses 和 Gemini 的模型级声明不完整；字段缺失不能直接判定不支持，最终以目标模型和服务分组的小请求结果为准。

### 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": "请只回复：XiuRouter 已连接"
  }
]
  }'
```

### 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": "请只回复：XiuRouter 已连接"
  }'
```

### 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": "请只回复：XiuRouter 已连接"
  }
]
  }'
```

### 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": "请只回复：XiuRouter 已连接"
      }
    ]
  }
]
  }'
```

成功时返回 `200` 和对应协议的文本结果。回到 XiuRouter“使用记录”，确认模型、分组、请求状态和费用。某条路由存在或公共目录缺少声明，都不能替代真实请求；客户端使用哪种协议，就验证哪种协议。

## 常见失败

| 现象 | 先检查 | 处理 |
| --- | --- | --- |
| `401` 或 `Invalid token` | Key 是否缺失、粘贴不完整或已失效 | 重新读取环境变量；必要时轮换 Key |
| `403` | 账号、分组、模型或额度是否受限 | 检查 Key 的分组、模型列表、有效期和剩余额度 |
| `403` 且提示 IP 不在允许列表 | 这把 Key 已存在 IP 限制 | 新建一把专用 Key，验证后撤销旧 Key |
| 模型不可用 | 模型 ID、分组和当前目录是否匹配 | 从价格页或模型列表复制精确 ID，换到可用分组 |
| 余额或额度不足 | 账号调用额度、钱包余额和 Key 自身额度 | 充值或调整 Key 额度后重新发起小请求 |
| 流式请求中断 | 是否误用了控制台域名，或为 Messages/Gemini 多加了 `/v1` | 按本文协议表核对 Base URL：OpenAI 使用 `/v1`，Messages/Gemini 使用 API 根地址 |
| `5xx` 或上游错误 | 使用记录中的请求 ID 和原始提示 | 稍后重试一次；持续失败时保留请求 ID 与时间 |

## 用完后

临时测试结束后清除当前终端中的变量：

```bash
unset XIUROUTER_API_KEY
```

长期接入时，为每个应用单独创建 Key，并限制模型、额度、有效期和必要的出口 IP。不要让多个项目共用一把无法追踪的 Key。

## 来源与核对日期

本文按 XiuRouter 当前控制台、公开 API 状态、模型目录和 API Key 表单核对，日期为 2026-08-19。本轮没有使用真实 Key 发起计费请求；成功标准以你的 `200` 响应和使用记录为准。

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