---
title: "使用 SDK 调用 XiuRouter"
description: "配置 OpenAI Python 或 JavaScript SDK，并理解 Chat Completions 的常用请求参数与兼容边界。"
image: "https://docs.xiu.ai/og.png"
---

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

# 使用 SDK 调用 XiuRouter

XiuRouter 可以通过 OpenAI 兼容 SDK 调用。把 SDK 的 Base URL 改为 `https://router-api.xiu.ai/v1`，再使用专用 XiuRouter API Key 和当前目录中的精确模型 ID。

## 前置条件

- 已按[快速开始](/router/quickstart)创建专用 API Key。
- 已从[模型与价格](https://router.xiu.ai/pricing)复制模型 ID。
- 已安装当前项目使用的 OpenAI SDK。

不要把 API Key 写进源码、锁文件、前端包或 Git 仓库。下面示例从环境变量读取：

```bash
export XIUROUTER_API_KEY="YOUR_XIUROUTER_API_KEY"
export XIUROUTER_MODEL="YOUR_MODEL_ID"
```

## Python

```python
import os
from openai import OpenAI

client = OpenAI(
api_key=os.environ["XIUROUTER_API_KEY"],
base_url="https://router-api.xiu.ai/v1",
)

response = client.chat.completions.create(
model=os.environ["XIUROUTER_MODEL"],
messages=[
    {"role": "user", "content": "请只回复：Python SDK 已连接"}
],
)

print(response.choices[0].message.content)
```

## JavaScript

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XIUROUTER_API_KEY,
  baseURL: "https://router-api.xiu.ai/v1",
});

const response = await client.chat.completions.create({
  model: process.env.XIUROUTER_MODEL,
  messages: [
{ role: "user", content: "请只回复：JavaScript SDK 已连接" },
  ],
});

console.log(response.choices[0].message.content);
```

## 常用请求参数

| 参数 | 用途 | 使用边界 |
| --- | --- | --- |
| `model` | 选择模型 | 必填；从模型列表或价格页复制精确 ID |
| `messages` | 提供对话消息 | Chat Completions 使用；角色和多模态内容仍受模型限制 |
| `max_completion_tokens` | 限制输出 Token | 新模型优先使用；部分上游只接受 `max_tokens` |
| `temperature`、`top_p` | 控制采样 | 推理模型可能忽略或拒绝部分采样参数 |
| `stop` | 设置停止序列 | 支持情况取决于目标模型 |
| `tools`、`tool_choice` | 声明工具 | 需要模型和上游同时支持工具调用 |
| `response_format` | 请求 JSON 或 JSON Schema 输出 | 需要目标模型支持结构化输出 |
| `stream` | 启用流式响应 | 使用直接 API 域名，并按 SSE 读取 |
| `stream_options.include_usage` | 在流结束前返回用量 | 只有兼容上游会返回 |
| `reasoning_effort` | 设置推理强度 | 只用于接受该字段的推理模型 |

网关能解析这些字段，不代表每个模型都会接受。收到参数错误时，保留原始错误和请求 ID，先移除非必要参数，再按模型逐项加回。

## 验证

1. 确认程序收到完整文本，而不是只通过鉴权检查。
2. 打开 XiuRouter“使用记录”，核对模型、服务分组、Token、费用和请求状态。
3. 记录响应头中的 `x-oneapi-request-id`，用于定位本次请求。

## 常见失败

| 现象 | 处理 |
| --- | --- |
| SDK 请求仍发往官方地址 | 检查 Python 的 `base_url` 或 JavaScript 的 `baseURL` |
| `401 Invalid token` | 确认运行进程能读取 `XIUROUTER_API_KEY` |
| 模型不可用 | 重新读取 `GET /v1/models`，并检查 Key 的分组和模型范围 |
| 参数不被接受 | 保留 `model` 和最小 `messages`，移除高级参数后重试 |
| 普通文本成功，工具或 JSON 失败 | 按[工具、结构化输出与流式响应](/router/tools-streaming)单独验证 |

## 来源与核对日期

本文按 XiuRouter 当前 Chat Completions 路由、请求 DTO，以及 OpenAI Python 和 JavaScript SDK 的自定义 Base URL 配置核对，日期为 2026-08-19。模型参数支持范围仍以实际请求结果为准。

源文件：https://docs.xiu.ai/router/sdk-and-requests/index.mdx