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請求已到達模型供應方但未能完成。可以重試。