Quickstart
三个步骤。如果你已经接入过 OpenAI，那么只有第二步与你相关。
- 1
安装官方 SDK
没有私有客户端。使用你已经熟悉的 openai 或 anthropic 包即可。 - 2
把它指向 RealRelay.ai
将 base_url 设为 https://www.realrelay.ai/v1，并使用你的 RealRelay.ai 密钥。 - 3
选择一个模型
把 model 设为目录中的某个 ID。你代码里的其他部分都不用改。
1pip install openai1npm install openai1from openai import OpenAI23client = OpenAI(4 base_url="https://www.realrelay.ai/v1",5 api_key="sk-***",6)78response = client.chat.completions.create(9 model="jd/glm-5.2",10 messages=[{"role": "user", "content": "Hello"}],11)1213print(response.choices[0].message.content)1import OpenAI from "openai";23const client = new OpenAI({4 baseURL: "https://www.realrelay.ai/v1",5 apiKey: process.env.REALRELAY_API_KEY,6});78const response = await client.chat.completions.create({9 model: "jd/glm-5.2",10 messages: [{ role: "user", content: "Hello" }],11});1213console.log(response.choices[0].message.content);1curl https://www.realrelay.ai/v1/chat/completions \2 -H "Authorization: Bearer $REALRELAY_API_KEY" \3 -H "Content-Type: application/json" \4 -d '{5 "model": "jd/glm-5.2",6 "messages": [{ "role": "user", "content": "Hello" }]7 }'Authentication
在控制台中创建一个密钥。默认方式是在
Authorization 头中使用 bearer 认证。为了让厂商 SDK 无需改动即可工作，另外还接受两种方式：
在 /v1/messages 上使用
x-api-key；在
/v1beta 上使用
x-goog-api-key，或使用
?key= 查询参数。它们是等价的，你的
SDK 发哪种就用哪种。
1Authorization: Bearer sk-***2Content-Type: application/json切勿把密钥放进前端代码，也不要提交到代码仓库。浏览器端的功能应当调用你自己的后端，由后端持有密钥并转发请求。
Model IDs
模型 ID 有两种形式，两者都是可以直接发送的真实地址。像
glm-5.2 这样的裸规范名会被路由到当前正在提供该模型的任意渠道。加上渠道前缀，例如
jd/glm-5.2，则会把请求固定到那一个渠道上。
1# Routed: any channel serving this model2model="glm-5.2"34# Pinned: exactly this channel5model="jd/glm-5.2"目录中列出的是带前缀的形式，因为只有它对应唯一的价格。要获取你的密钥所接受的确切 ID 集合，请调用
GET /v1/models。
Channel routing
当你发送裸规范名时，由路由策略挑选渠道。共有三种策略，在控制台中按账户逐一选择：
lowest_price—— 提供该模型的最便宜的渠道。未设置任何策略时，这是默认值。lowest_latency—— 近期响应时间最优的渠道。default—— 平台顺序：先按渠道优先级，再按权重。
带前缀的模型 ID 不会查询策略。固定一个渠道和请求最便宜的渠道是两种不同的请求，而前缀优先。
Endpoints
基础地址是 https://www.realrelay.ai。不同模型支持哪些端点各不相同；目录会按模型逐一列出。其中一个端点是异步的 —— 请参见其所在行的轮询步骤。
/v1/chat/completionsChat Completions。兼容 OpenAI，也是多数集成的默认入口。/v1/responsesResponses 接口，用于工具调用与结构化输出。/v1/messagesAnthropic 请求形状，Anthropic SDK 无需改动即可使用。/v1beta/models/{model}:generateContentGemini 原生请求形状，经协议兼容层提供。/v1/images/generations图像生成与编辑。/v1/video/generationsGET /v1/video/generations/{task_id}视频生成。异步：先提交，再轮询任务标识直到结束。/v1/models列出你的密钥可以调用的模型。Errors
错误使用标准 HTTP 状态码，并附带 JSON 主体。请根据状态码以及
error.code 来分支处理：
error.type 表示失败来自何处 ——
平台失败时为 new_api_error，而当失败源自模型提供方时则为提供方自己的类型 —— 因此它太粗略，不适合用来做分支判断。
1{2"error": {3 "message": "...",4 "type": "new_api_error",5 "code": "insufficient_user_quota"6}7}bad_request_body请求体格式有误，或缺少必填字段。—API 密钥缺失、格式错误、已禁用或不存在。这类失败不带错误码。access_denied密钥存在但不允许发起该请求——例如调用方不在其 IP 允许列表内。insufficient_user_quota账户余额或订阅额度已用尽。—当前窗口内请求过多。请以指数退避重试；平台不返回 Retry-After 头。model_not_found当前没有已启用的渠道提供该模型 ID。do_request_failed请求已到达模型供应方但未能完成。可以重试。