> ## Documentation Index > Fetch the complete documentation index at: https://docs.yourouter.ai/llms.txt > Use this file to discover all available pages before exploring further. # API 快速开始 > 几分钟内完成 YouRouter API 的基础接入。 使用这份指南把应用接入 YouRouter，完成第一条请求，并确认响应结构是否符合预期。YouRouter 提供 OpenAI 兼容接口 `https://api.yourouter.ai/v1`，所以大多数已有的 OpenAI SDK 集成只需要替换 `base_url` 和 API key。 需要 API Key？请前往 [YouRouter Dashboard](https://platform.yourouter.ai/dashboard) 创建。 ## 接入基础信息 | 项目 | 值 | | -------- | ---------------------------------------------------------- | | Base URL | `https://api.yourouter.ai/v1` | | 鉴权请求头 | `Authorization: Bearer ` | | 内容类型 | `Content-Type: application/json` | | 模型字段 | 通过 `model` 指定目标模型 | | 多模态输入 | 在 `messages[].content` 中传入文本和图片块 | | 默认路由 | 省略 `vendor`，或发送 `vendor: auto` | | 指定上游 | 发送 `vendor: openai`、`vendor: anthropic`、`vendor: google` 等 | ## 1. 设置 API Key 在运行下面的示例前，先把 API Key 存到环境变量中。 ```bash theme={null} export YOUROUTER_API_KEY="your-api-key-here" ``` ```cmd theme={null} set YOUROUTER_API_KEY=your-api-key-here ``` ```bash theme={null} 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。 ```bash theme={null} 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" } ] }' ``` ```bash theme={null} pip install requests ``` ```python theme={null} 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"]) ``` ```javascript theme={null} // 保存为 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); ``` ```go theme={null} 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) } ``` ```java theme={null} 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 response = HttpClient.newHttpClient().send( request, HttpResponse.BodyHandlers.ofString() ); if (response.statusCode() >= 400) { throw new RuntimeException(response.body()); } System.out.println(response.body()); } } ``` ```php theme={null} '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; ``` ```bash theme={null} cargo add reqwest --features blocking,json cargo add serde_json ``` ```rust theme={null} use reqwest::blocking::Client; use serde_json::json; use std::env; fn main() -> Result<(), Box> { 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`。 ```bash theme={null} pip install openai ``` ```python theme={null} 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) ``` ```bash theme={null} npm install openai ``` ```javascript theme={null} 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。需要图像等多模态输入时，参考 [多模态指南](/zh/guides/multimodal)。 如果示例中的模型尚未在你的账号中启用，请替换为 [YouRouter Dashboard](https://platform.yourouter.ai/dashboard) 中显示的任意可用模型 ID。 默认情况下，YouRouter 会自动路由。省略 `vendor` 请求头，或者设置 `vendor: auto`，即可让 YouRouter 选择当前最合适的可用上游。 只有当你的集成明确依赖某个上游的行为、模型变体、账号隔离或合规要求时，才建议固定 `vendor`。 ```bash theme={null} 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."}] }' ``` ```python theme={null} completion = client.chat.completions.create( model="gpt-4o", messages=[{"role": "user", "content": "Hello from a pinned provider."}], extra_headers={"vendor": "openai"}, ) ``` ```javascript theme={null} const completion = await openai.chat.completions.create({ model: 'gpt-4o', messages: [{ role: 'user', content: 'Hello from a pinned provider.' }], }, { headers: { vendor: 'openai' }, }); ``` 更多模型 API 示例可参考 [模型说明](/zh/model)；上游提供商 ID、自动故障切换行为和生产建议可参考 [路由指南](/zh/guides/router)。 ## 5. 处理响应与错误 对于 OpenAI 兼容接口，成功响应遵循 OpenAI 风格格式。生成文本通常位于 `choices[0].message.content`。 ```json theme={null} { "choices": [ { "message": { "role": "assistant", "content": "connected" } } ] } ``` 常见状态码： | 状态码 | 含义 | 建议处理方式 | | ----- | ------------- | ---------------------- | | `200` | 请求成功 | 解析响应体 | | `401` | API Key 缺失或无效 | 检查 `Authorization` 请求头 | | `429` | 上游限流 | 做退避重试，或调整路由 | | `500` | 网关或上游错误 | 安全重试，并记录请求 ID | ## 6. 流式输出 如果你在做聊天 UI 或 agent，可以设置 `stream: true`，让模型边生成边返回分片。 ```python theme={null} 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](/zh/api-reference/chat/create#streaming)。 ## 下一步 查看接口、参数与响应格式。 了解如何传入模型 ID，并通过 API 切换模型。 发送图片输入，并调用提供商原生多模态 API。 了解自动路由和指定上游的适用场景。 构建对话、流式 UI、工具调用和多模态流程。