XiuAI 可以通过 OpenAI 兼容 SDK 调用。把 SDK 的 Base URL 改为 https://router-api.xiu.ai/v1,再使用专用 XiuAI 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,先移除非必要参数,再按模型逐项加回。
Gemini 思考档位
价格页把同一 Gemini 模型家族的兼容后缀合并展示。Gemini 3.x SDK 请求优先使用基础模型 ID,并传 reasoning_effort;-low、-medium、-high 仍可作为兼容模型 ID。Gemini 3.8 Flash 的原生 thinkingLevel 可以选择档位;Antigravity Argon 要保证 low、medium 或 high 时使用对应的精确模型 ID,基础 Argon 名称可能按上游映射回退到 high。
切换档位后启动一次新的请求,再在使用记录中核对最终模型、协议、服务分组和费用。不要把价格页的家族展示名直接当成请求 ID,也不要把一次普通文本回复当成工具调用已经通过。
Gemini 原生 SDK
需要原生思考、图片尺寸、图片编辑或 Gemini 工具调用时,使用 Gemini GenerateContent,Base URL 为 https://router-api.xiu.ai,认证头为 x-goog-api-key。图片尺寸必须写入 generationConfig.imageConfig;OpenAI 的 size 或 quality 不会自动转换。验收时读取返回图片像素和使用记录。
from google import genai
client = genai.Client(
api_key=os.environ["XIUROUTER_API_KEY"],
http_options={"base_url": "https://router-api.xiu.ai", "api_version": "v1beta"},
)
response = client.models.generate_content(
model="gemini-3.1-flash-image",
contents="生成一张 1:1 的蓝色机器人图标,不要文字。",
config={
"response_modalities": ["TEXT", "IMAGE"],
"image_config": {"aspect_ratio": "1:1", "image_size": "2K"},
},
)验证
- 确认程序收到完整文本,而不是只通过鉴权检查。
- 打开 XiuAI“使用记录”,核对模型、服务分组、Token、费用和请求状态。
- 记录响应头中的
x-oneapi-request-id,用于定位本次请求。
常见失败
| 现象 | 处理 |
|---|---|
| SDK 请求仍发往官方地址 | 检查 Python 的 base_url 或 JavaScript 的 baseURL |
401 Invalid token |
确认运行进程能读取 XIUROUTER_API_KEY |
| 模型不可用 | 重新读取 GET /v1/models,并检查 Key 的分组和模型范围 |
| 参数不被接受 | 保留 model 和最小 messages,移除高级参数后重试 |
| 普通文本成功,工具或 JSON 失败 | 按工具、结构化输出与流式响应单独验证 |
来源与核对日期
本文于 2026-11-07 按 XiuAI 当前 Chat Completions、Gemini GenerateContent 路由,以及 OpenAI 和 Gemini SDK 的自定义 Base URL 配置核对。模型参数和图片尺寸仍以实际请求结果为准。