# OAIRoute 快速上手
OAIRoute 是一个 OpenAI 兼容的 API 网关：一个端点接入 GPT、Claude、Gemini 等主流模型，文本、语音、图像、视频共用同一套接口格式。
现有代码只需改一处：把地址指向 OAIRoute，其余照旧，三分钟就能跑通第一次调用。
:::cards
立即开始 | 用一段 cURL 完成第一次对话调用 | text/chat-completions.html | →
## 接入地址
| 地址 | 承载的模型 |
|---|---|
| `api.oairoute.com` | GPT、Claude、Gemini 等前沿模型，以及大部分图像与视频接口 || `direct.oairoute.com` 为直连备用 |
| `ark.oairoute.com` | Seedance 系列与 Seedream 系列：视频、图像 |
> **Note:** 绝大多数接口用 `api.oairoute.com` 就够了，Key 与控制台都在那里创建。只有 Seedance 系列与 Seedream 系列走 `ark.oairoute.com`，这部分需要到 [ark 站](https://ark.oairoute.com/) 单独获取 Key，与 api 站的 Key 不通用。其余图像与视频接口仍然使用 api 站的 Key。
## 第一次调用
从注册到跑通第一次请求，一共六步。前三步准备账号，后三步接入代码。下面的代码可以直接复制，把占位符换掉就能跑。
:::steps
@注册账号 | 打开 [注册页](https://api.oairoute.com/register)，填邮箱和密码完成注册。也可以用已支持的第三方账号登录。注册后邮箱会收到验证邮件，没收到就去垃圾箱找一下。
@登录控制台 | 打开 [登录页](https://api.oairoute.com/login)，进入 [控制台](https://api.oairoute.com)。控制台里能看到余额、用量、令牌列表和调用记录，后面的操作都在这里完成。
@准备额度 | **没有额度，Key 建好了也用不了**，调用会直接返回 402 `payment_required`。在控制台的充值入口（钱包 / 充值页）充入金额后即可使用。额度是整个账户共用的，不是按 Key 分开的。
@创建 API Key | 在控制台左侧「令牌」页面点新建，复制那串 `sk-` 开头的字符。它相当于账号密码，不要发给别人。可以为不同项目建不同的 Key，方便分开统计用量和随时吊销某一个。
@把地址指向 OAIRoute | 在 SDK 或客户端里把「API 地址」设为 `https://api.oairoute.com/v1`，其余配置不动。
- 用 OpenAI 官方 SDK（Python / Node.js 等）：填 `base_url` / `baseURL` 参数
- 用 curl、Postman 或自己写 HTTP 请求：把 URL 里的 `api.openai.com` 换成 `api.oairoute.com`
- 用第三方客户端（ChatBox、Cherry Studio 等）：在设置里找到「API 地址 / Base URL」，填 `https://api.oairoute.com/v1`
- 代码里的 `YOUR_MODEL_ID` 换成真实模型名，到[模型广场](https://api.oairoute.com/pricing)找到你要用的模型复制
```python
from openai import OpenAI
client = OpenAI(
    api_key="YOUR_OAIRoute_KEY",
    base_url="https://api.oairoute.com/v1",
)
res = client.chat.completions.create(
    model="YOUR_MODEL_ID",
    messages=[{"role": "user", "content": "你好"}],
)
print(res.choices[0].message.content)
```
```bash
curl https://api.oairoute.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_OAIRoute_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{"role": "user", "content": "你好"}]
  }'
```
@看返回结果 | 收到包含 `choices` 字段的 JSON，且 `content` 里有文字，就说明接通了。返回结构见下一节。如果返回 401，检查 Key 是否复制完整、Bearer 后是否有一个空格；返回 402，回到第三步确认额度。
> **Note:** 如果只是想先看看有哪些模型、价格多少，不注册也能直接看[模型广场](https://api.oairoute.com/pricing)。那个页面的数据来自公开接口，不需要登录。
## 返回结构
不同接口的返回形式不一样，对照着看就知道调用是否正常。
对话接口（最常用）返回 `choices`，回答在 `message.content` 里：
```json
{
  "id": "chatcmpl-01KA040M0HP1GJWBJYZMKX1XS1",
  "object": "chat.completion",
  "created": 1763088289,
  "model": "<你的模型 ID>",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "你好！有什么可以帮你的？" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 9, "completion_tokens": 12, "total_tokens": 21 }
}
```
图像与视频接口是异步的，提交后先返回任务 ID，不会立刻给结果：
```json
{
  "code": 200,
  "data": [
    { "status": "submitted", "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K" }
  ]
}
```
拿到 `task_id` 后查 `/v1/tasks/{task_id}`，完成时返回文件地址：
```json
{
  "code": 200,
  "data": [
    {
      "status": "completed",
      "result": { "images": ["https://.../result.png"] }
    }
  ]
}
```
出错时所有接口都返回统一的错误体，`code` 说明原因：
```json
{
  "error": {
    "code": 401,
    "message": "身份验证失败，请检查您的API密钥",
    "type": "authentication_error"
  }
}
```
完整的状态码含义、重试建议与处理方式，见[错误码与限流](../support/errors.html)。
## 接口一览
:::cards
通用对话接口 | 与 OpenAI Chat Completions 完全兼容 | text/chat-completions.html | 💬
Claude 消息接口 | 原生 Messages 格式，支持工具调用 | text/claude-messages.html | ✳
图像生成 | GPT-Image、Seedream、Nano Banana 等 | image/seedream/openai.html | 🖼
视频生成 | Seedance、Sora 等，异步任务返回 task_id | video/openai.html | 🎬
语音与转录 | TTS 文字转语音、Whisper 音频转录 | audio/tts.html | 🎧
任务状态 | 轮询异步任务进度与结果 | tasks/status.html | ⏱
上下文缓存 | 复用长上下文，降低重复计费 | text/cache-openai.html | 🗄
## 平台优势
- **换地址即可迁移**：请求体与返回结构沿用 OpenAI 标准，现有 SDK 和代码不用改
- **多供应商路由**：同一模型可在多家上游之间调度，单家抖动时自动切换
- **服务可用性**：多线路冗余与自动故障转移，面向企业提供明确的可用性指标与故障响应时限
- **全球 CDN 加速**：边缘节点就近接入，降低跨境链路的首包延迟
- **实时状态监控**：线路与模型可用性实时监测，异常可到 [状态页](https://status.oairoute.com) 查看
- **计价透明**：模型列表接口直接返回输入、输出与按次计费单价，调用前就能核算成本
- **异步可追踪**：图像视频提交后返回任务 ID，可轮询，也可配 Webhook 回调
## SDK 与代码示例
官方 SDK 不用换，直接用 OpenAI、Anthropic、Google 各自的库，只改初始化时的地址和 Key。下面只保留初始化部分，请求调用照原样写即可。
**Python**
通过 `pip install openai` 安装。设置 Base URL 并使用现有 OpenAI 代码，无需修改。
```python
from openai import OpenAI
client = OpenAI(
    api_key="YOUR_OAIRoute_KEY",
    base_url="https://api.oairoute.com/v1",
)
```
**Node.js**
通过 `npm install openai` 安装。配置 baseURL 参数为 OAIRoute 端点，保留现有集成。
```javascript
import OpenAI from "openai";
const client = new OpenAI({
  apiKey: "YOUR_OAIRoute_KEY",
  baseURL: "https://api.oairoute.com/v1",
});
```
**Claude（Anthropic SDK）**
通过 `pip install anthropic` 安装。注意 Claude 原生接口的地址不带 `/v1` 后缀。
```python
from anthropic import Anthropic
client = Anthropic(
    api_key="YOUR_OAIRoute_KEY",
    base_url="https://api.oairoute.com",
)
```
**Java**
通过 Maven 引入 OpenAI 官方 Java 客户端。设置 baseUrl 并使用现有代码，无需修改。
```xml
<!-- pom.xml -->
<dependency>
  <groupId>com.openai</groupId>
  <artifactId>openai-java</artifactId>
  <version>2.6.0</version>
</dependency>
```
```java
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
OpenAIClient client = OpenAIOkHttpClient.builder()
    .apiKey("YOUR_OAIRoute_KEY")
    .baseUrl("https://api.oairoute.com/v1")
    .build();
```
**其他语言**
文档的每个接口页右侧都有对应语言的完整示例，覆盖 cURL、Python、JavaScript、Go、Java、PHP、Ruby、Swift、C#、C、Objective-C、OCaml、Dart、R 十四种，点页面右上角的下拉即可切换。
## 常见问题
常见问题的完整解答集中在帮助支持，按主题分页：
:::cards
常见问题 | 地址带不带 /v1、模型名怎么填、报错怎么排查、用量在哪看 | ../support/faq.html | ❓
错误码与限流 | 每个状态码的含义、该不该重试、429 怎么处理 | ../support/errors.html | ⚠