使用这份指南把应用接入 YouRouter,完成第一条请求,并确认响应结构是否符合预期。YouRouter 提供 OpenAI 兼容接口 https://api.yourouter.ai/v1,所以大多数已有的 OpenAI SDK 集成只需要替换 base_url 和 API key。
接入基础信息
| 项目 | 值 |
|---|
| Base URL | https://api.yourouter.ai/v1 |
| 鉴权请求头 | Authorization: Bearer <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 或任意标准 HTTP 客户端;下面的示例覆盖 Python、Node.js、Go、Java、PHP 和 Rust。
cURL
Python requests
Node.js 18+ fetch
Go
Java 11+
PHP
Rust
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",
}
],
},
)
response.raise_for_status()
print(response.json()["choices"][0]["message"]["content"])
// 保存为 quickstart.mjs,并使用 Node.js 18+ 运行。
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',
},
],
}),
});
if (!response.ok) {
throw new Error(await response.text());
}
const data = await response.json();
console.log(data.choices[0].message.content);
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
"os"
)
func main() {
payload, _ := json.Marshal(map[string]any{
"model": "gpt-4o",
"messages": []map[string]string{
{"role": "user", "content": "Reply with exactly: connected"},
},
})
req, err := http.NewRequest(
"POST",
"https://api.yourouter.ai/v1/chat/completions",
bytes.NewReader(payload),
)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("YOUROUTER_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
if res.StatusCode >= 400 {
body, _ := io.ReadAll(res.Body)
panic(fmt.Sprintf("request failed: %s\n%s", res.Status, body))
}
var result struct {
Choices []struct {
Message struct {
Content string `json:"content"`
} `json:"message"`
} `json:"choices"`
}
if err := json.NewDecoder(res.Body).Decode(&result); err != nil {
panic(err)
}
fmt.Println(result.Choices[0].Message.Content)
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Quickstart {
public static void main(String[] args) throws Exception {
String body = String.join("\n",
"{",
" \"model\": \"gpt-4o\",",
" \"messages\": [",
" {",
" \"role\": \"user\",",
" \"content\": \"Reply with exactly: connected\"",
" }",
" ]",
"}"
);
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.yourouter.ai/v1/chat/completions"))
.header("Authorization", "Bearer " + System.getenv("YOUROUTER_API_KEY"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(
request,
HttpResponse.BodyHandlers.ofString()
);
if (response.statusCode() >= 400) {
throw new RuntimeException(response.body());
}
System.out.println(response.body());
}
}
<?php
$apiKey = getenv('YOUROUTER_API_KEY');
$payload = json_encode([
'model' => 'gpt-4o',
'messages' => [
[
'role' => 'user',
'content' => 'Reply with exactly: connected',
],
],
]);
$ch = curl_init('https://api.yourouter.ai/v1/chat/completions');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $payload,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
curl_close($ch);
if ($status >= 400) {
throw new RuntimeException($response);
}
$data = json_decode($response, true);
echo $data['choices'][0]['message']['content'] . PHP_EOL;
cargo add reqwest --features blocking,json
cargo add serde_json
use reqwest::blocking::Client;
use serde_json::json;
use std::env;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let api_key = env::var("YOUROUTER_API_KEY")?;
let response: serde_json::Value = Client::new()
.post("https://api.yourouter.ai/v1/chat/completions")
.bearer_auth(api_key)
.json(&json!({
"model": "gpt-4o",
"messages": [
{
"role": "user",
"content": "Reply with exactly: connected"
}
]
}))
.send()?
.error_for_status()?
.json()?;
if let Some(content) = response["choices"][0]["message"]["content"].as_str() {
println!("{content}");
}
Ok(())
}
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);
Go、Java、PHP 和 Rust 也使用同样的自定义 Base URL 思路:如果你使用的 OpenAI 兼容 SDK 支持设置 base URL,就指向 https://api.yourouter.ai/v1;如果 SDK 不支持,就直接用上面的 HTTP 示例请求 /v1/chat/completions。
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' },
});
更多模型 API 示例可参考 模型说明;上游提供商 ID、自动故障切换行为和生产建议可参考 路由指南。
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="")
完整请求格式可以查看 Create Chat Completion。
下一步
API Reference
查看接口、参数与响应格式。
模型说明
了解如何传入模型 ID,并通过 API 切换模型。
多模态
发送图片输入,并调用提供商原生多模态 API。
Chat Completions
构建对话、流式 UI、工具调用和多模态流程。