使用这份指南把应用接入 YouRouter，完成第一条请求，并确认响应结构是否符合预期。YouRouter 提供 OpenAI 兼容接口 https://api.yourouter.ai/v1，所以大多数已有的 OpenAI SDK 集成只需要替换 base_url 和 API key。
接入基础信息
| 项目 | 值 |
|---|
| Base URL | https://api.yourouter.ai/v1 |
| 鉴权请求头 | Authorization: Bearer <YOUR_YOUROUTER_API_KEY> |
| 内容类型 | Content-Type: application/json |
| 模型字段 | 通过 model 指定目标模型 |
| 多模态输入 | 在 messages[].content 中传入文本和图片块 |
| 默认路由 | 省略 vendor，或发送 vendor: auto |
| 指定上游 | 发送 vendor: openai、vendor: anthropic、vendor: google 等 |
1. 设置 API Key
在运行下面的示例前，先把 API Key 存到环境变量中。
export YOUROUTER_API_KEY="your-api-key-here"
set YOUROUTER_API_KEY=your-api-key-here
YOUROUTER_API_KEY=your-api-key-here
不要把 API Key 暴露到浏览器端代码、移动端应用、公开仓库或客户端日志里。
2. 发起第一条测试请求
最快的接入验证方式，是直接请求 Chat Completions 接口。请求成功后，可以从 choices[0].message.content 读取模型输出。
cURL
Python requests
Node.js fetch
curl https://api.yourouter.ai/v1/chat/completions \
-H "Authorization: Bearer $YOUROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"messages": [
{
"role": "user",
"content": "Reply with exactly: connected"
}
]
}'
import os
import requests
response = requests.post(
"https://api.yourouter.ai/v1/chat/completions",
headers={
"Authorization": f"Bearer {os.environ['YOUROUTER_API_KEY']}",
"Content-Type": "application/json",
},
json={
"model": "gpt-4o",
"messages": [
{
"role": "user",
"content": "Reply with exactly: connected",
}
],
},
)
print(response.json()["choices"][0]["message"]["content"])
const response = await fetch('https://api.yourouter.ai/v1/chat/completions', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.YOUROUTER_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'gpt-4o',
messages: [
{
role: 'user',
content: 'Reply with exactly: connected',
},
],
}),
});
const data = await response.json();
console.log(data.choices[0].message.content);
3. 迁移现有 OpenAI SDK 代码
如果你的应用已经在使用 OpenAI SDK，通常可以保留原有请求体结构，只替换两个字段：api_key 和 base_url。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["YOUROUTER_API_KEY"],
base_url="https://api.yourouter.ai/v1",
)
completion = client.chat.completions.create(
model="gpt-4o",
messages=[
{
"role": "user",
"content": "Reply with exactly: connected",
}
],
)
print(completion.choices[0].message.content)
import OpenAI from 'openai';
const openai = new OpenAI({
apiKey: process.env.YOUROUTER_API_KEY,
baseURL: 'https://api.yourouter.ai/v1',
});
const completion = await openai.chat.completions.create({
model: 'gpt-4o',
messages: [
{
role: 'user',
content: 'Reply with exactly: connected',
},
],
});
console.log(completion.choices[0].message.content);
4. 选择模型与路由方式
通过 model 字段选择模型。你可以用同一种 API 形式调用多种模型家族，例如 OpenAI GPT、Claude、Gemini、DeepSeek、Grok、Doubao 和 Kimi。需要图像等多模态输入时，参考 多模态指南。
默认情况下，YouRouter 会自动路由。省略 vendor 请求头，或者设置 vendor: auto，即可让 YouRouter 选择当前最合适的可用上游。
只有当你的集成明确依赖某个上游的行为、模型变体、账号隔离或合规要求时，才建议固定 vendor。
cURL
Python SDK
Node.js SDK
curl https://api.yourouter.ai/v1/chat/completions \
-H "Authorization: Bearer $YOUROUTER_API_KEY" \
-H "Content-Type: application/json" \
-H "vendor: openai" \
-d '{
"model": "gpt-4o",
"messages": [{"role": "user", "content": "Hello from a pinned provider."}]
}'
completion = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Hello from a pinned provider."}],
extra_headers={"vendor": "openai"},
)
const completion = await openai.chat.completions.create({
model: 'gpt-4o',
messages: [{ role: 'user', content: 'Hello from a pinned provider.' }],
}, {
headers: { vendor: 'openai' },
});
5. 处理响应与错误
对于 OpenAI 兼容接口，成功响应遵循 OpenAI 风格格式。生成文本通常位于 choices[0].message.content。
{
"choices": [
{
"message": {
"role": "assistant",
"content": "connected"
}
}
]
}
| 状态码 | 含义 | 建议处理方式 |
|---|
200 | 请求成功 | 解析响应体 |
401 | API Key 缺失或无效 | 检查 Authorization 请求头 |
429 | 上游限流 | 做退避重试，或调整路由 |
500 | 网关或上游错误 | 安全重试，并记录请求 ID |
6. 流式输出
如果你在做聊天 UI 或 agent，可以设置 stream: true，让模型边生成边返回分片。
stream = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Explain automatic routing in two sentences."}],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="")
下一步
模型说明
查看模型 ID、模型家族以及 vendor 的使用方式。
API Reference
查看接口、参数与响应格式。
