OAIRoute 快速上手

OAIRoute 是一个 OpenAI 兼容的 API 网关：一个端点接入 GPT、Claude、Gemini 等主流模型，文本、语音、图像、视频共用同一套接口格式。

现有代码只需改一处：把地址指向 OAIRoute，其余照旧，三分钟就能跑通第一次调用。

→立即开始用一段 cURL 完成第一次对话调用

接入地址

地址承载的模型
api.oairoute.comGPT、Claude、Gemini 等前沿模型，以及大部分图像与视频接口direct.oairoute.com 为直连备用
ark.oairoute.comSeedance 系列与 Seedream 系列：视频、图像
绝大多数接口用 api.oairoute.com 就够了，Key 与控制台都在那里创建。只有 Seedance 系列与 Seedream 系列走 ark.oairoute.com，这部分需要到 ark 站 单独获取 Key，与 api 站的 Key 不通用。其余图像与视频接口仍然使用 api 站的 Key。

第一次调用

从注册到跑通第一次请求，一共六步。前三步准备账号，后三步接入代码。下面的代码可以直接复制，把占位符换掉就能跑。

  1. 1
    注册账号

    打开 注册页，填邮箱和密码完成注册。也可以用已支持的第三方账号登录。注册后邮箱会收到验证邮件，没收到就去垃圾箱找一下。

  2. 2
    登录控制台

    打开 登录页，进入 控制台。控制台里能看到余额、用量、令牌列表和调用记录，后面的操作都在这里完成。

  3. 3
    准备额度

    没有额度，Key 建好了也用不了，调用会直接返回 402 payment_required。在控制台的充值入口（钱包 / 充值页）充入金额后即可使用。额度是整个账户共用的，不是按 Key 分开的。

  4. 4
    创建 API Key

    在控制台左侧「令牌」页面点新建，复制那串 sk- 开头的字符。它相当于账号密码，不要发给别人。可以为不同项目建不同的 Key，方便分开统计用量和随时吊销某一个。

  5. 5
    把地址指向 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 换成真实模型名，到模型广场找到你要用的模型复制
    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)
    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": "你好"}]
  }'
  6. 6
    看返回结果

    收到包含 choices 字段的 JSON，且 content 里有文字，就说明接通了。返回结构见下一节。如果返回 401，检查 Key 是否复制完整、Bearer 后是否有一个空格；返回 402，回到第三步确认额度。

如果只是想先看看有哪些模型、价格多少，不注册也能直接看模型广场。那个页面的数据来自公开接口，不需要登录。

返回结构

不同接口的返回形式不一样，对照着看就知道调用是否正常。

对话接口（最常用）返回 choices，回答在 message.content 里：

{
  "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，不会立刻给结果：

{
  "code": 200,
  "data": [
    { "status": "submitted", "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K" }
  ]
}

拿到 task_id 后查 /v1/tasks/{task_id}，完成时返回文件地址：

{
  "code": 200,
  "data": [
    {
      "status": "completed",
      "result": { "images": ["https://.../result.png"] }
    }
  ]
}

出错时所有接口都返回统一的错误体，code 说明原因：

{
  "error": {
    "code": 401,
    "message": "身份验证失败，请检查您的API密钥",
    "type": "authentication_error"
  }
}

完整的状态码含义、重试建议与处理方式，见错误码与限流。

接口一览

💬通用对话接口与 OpenAI Chat Completions 完全兼容✳Claude 消息接口原生 Messages 格式，支持工具调用🖼图像生成GPT-Image、Seedream、Nano Banana 等🎬视频生成Seedance、Sora 等，异步任务返回 task_id🎧语音与转录TTS 文字转语音、Whisper 音频转录⏱任务状态轮询异步任务进度与结果🗄上下文缓存复用长上下文，降低重复计费

平台优势

  • 换地址即可迁移：请求体与返回结构沿用 OpenAI 标准，现有 SDK 和代码不用改
  • 多供应商路由：同一模型可在多家上游之间调度，单家抖动时自动切换
  • 服务可用性：多线路冗余与自动故障转移，面向企业提供明确的可用性指标与故障响应时限
  • 全球 CDN 加速：边缘节点就近接入，降低跨境链路的首包延迟
  • 实时状态监控：线路与模型可用性实时监测，异常可到 状态页 查看
  • 计价透明：模型列表接口直接返回输入、输出与按次计费单价，调用前就能核算成本
  • 异步可追踪：图像视频提交后返回任务 ID，可轮询，也可配 Webhook 回调

SDK 与代码示例

官方 SDK 不用换，直接用 OpenAI、Anthropic、Google 各自的库，只改初始化时的地址和 Key。下面只保留初始化部分，请求调用照原样写即可。

Python

通过 pip install openai 安装。设置 Base URL 并使用现有 OpenAI 代码，无需修改。

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 端点，保留现有集成。

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 后缀。

from anthropic import Anthropic

client = Anthropic(
    api_key="YOUR_OAIRoute_KEY",
    base_url="https://api.oairoute.com",
)

Java

通过 Maven 引入 OpenAI 官方 Java 客户端。设置 baseUrl 并使用现有代码，无需修改。

<!-- pom.xml -->
<dependency>
  <groupId>com.openai</groupId>
  <artifactId>openai-java</artifactId>
  <version>2.6.0</version>
</dependency>
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 十四种，点页面右上角的下拉即可切换。

常见问题

常见问题的完整解答集中在帮助支持，按主题分页：

❓常见问题地址带不带 /v1、模型名怎么填、报错怎么排查、用量在哪看⚠错误码与限流每个状态码的含义、该不该重试、429 怎么处理