XiuRouter 可以通过 OpenAI 兼容 SDK 调用。把 SDK 的 Base URL 改为 https://router-api.xiu.ai/v1,再使用专用 XiuRouter API Key 和当前目录中的精确模型 ID。
前置条件
不要把 API Key 写进源码、锁文件、前端包或 Git 仓库。下面示例从环境变量读取:
export XIUROUTER_API_KEY="YOUR_XIUROUTER_API_KEY"
export XIUROUTER_MODEL="YOUR_MODEL_ID"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
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,先移除非必要参数,再按模型逐项加回。
验证
- 确认程序收到完整文本,而不是只通过鉴权检查。
- 打开 XiuRouter“使用记录”,核对模型、服务分组、Token、费用和请求状态。
- 记录响应头中的
x-oneapi-request-id,用于定位本次请求。
常见失败
| 现象 | 处理 |
|---|---|
| SDK 请求仍发往官方地址 | 检查 Python 的 base_url 或 JavaScript 的 baseURL |
401 Invalid token |
确认运行进程能读取 XIUROUTER_API_KEY |
| 模型不可用 | 重新读取 GET /v1/models,并检查 Key 的分组和模型范围 |
| 参数不被接受 | 保留 model 和最小 messages,移除高级参数后重试 |
| 普通文本成功,工具或 JSON 失败 | 按工具、结构化输出与流式响应单独验证 |
来源与核对日期
本文按 XiuRouter 当前 Chat Completions 路由、请求 DTO,以及 OpenAI Python 和 JavaScript SDK 的自定义 Base URL 配置核对,日期为 2026-08-19。模型参数支持范围仍以实际请求结果为准。