接入文件｜RelayHub

本頁目錄

01快速開始

前往控制台註冊帳號，新帳戶會自動獲得一筆試用額度。
在「API Key」頁面建立一把 Key（格式為 sk- 開頭），妥善保存。
把你的 SDK 或工具的 Base URL 改成下方位址，再換上這把 Key。

用 curl 確認一切正常：

bash


export RELAYHUB_API_KEY="sk-..."

curl {{ORIGIN}}/v1/chat/completions \
  -H "Authorization: Bearer $RELAYHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "你好"}]}'

可用的模型名稱請見模型廣場，或呼叫 GET /v1/models 取得目前上架的清單。

02Base URL

依你使用的 SDK 選擇對應的位址：

OpenAI 相容/v1

Anthropic/

Anthropic SDK 會自行在後面加上 /v1/messages，因此 Base URL 不需要帶 /v1。

接口一覽

方法	路徑	說明
`POST`	`/v1/chat/completions`	OpenAI 相容對話接口
`POST`	`/v1/completions`	OpenAI 相容文字補全
`POST`	`/v1/embeddings`	向量嵌入
`POST`	`/v1/messages`	Anthropic Messages 接口
`GET`	`/v1/models`	列出目前可用的模型

03驗證方式

所有 /v1 請求都需要 API Key，以下兩種請求標頭擇一即可，兩種接口皆通用：

標頭	格式	常見來源
`Authorization`	`Bearer sk-...`	OpenAI SDK 與多數工具
`x-api-key`	`sk-...`	Anthropic SDK

API Key 等同於你的帳戶餘額，請勿寫在前端程式碼或公開的版本庫中。外洩時可在控制台重設 Key，舊 Key 會立即失效。

04串流輸出

在請求中加入 "stream": true，回應會以 Server-Sent Events 逐段傳回，格式與官方接口相同。串流結束時平台會依上游回報的用量計費。


stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "寫一首關於路由的短詩"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)


const stream = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "寫一首關於路由的短詩" }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}


curl -N {{ORIGIN}}/v1/chat/completions \
  -H "Authorization: Bearer $RELAYHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "stream": true,
       "messages": [{"role": "user", "content": "你好"}]}'

串流一旦開始輸出內容，平台就不會再切換上游，以免回應重複或錯亂；在此之前發生的錯誤仍會自動重試其他渠道。

05OpenAI SDK

安裝官方 SDK（pip install openai 或 npm install openai），設定 base_url 即可。同一個 client 可以呼叫平台上任何 OpenAI 相容的模型。


import os
from openai import OpenAI

client = OpenAI(
    base_url="{{ORIGIN}}/v1",
    api_key=os.environ["RELAYHUB_API_KEY"],
)

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "用一句話介紹你自己"}],
)
print(resp.choices[0].message.content)


import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "{{ORIGIN}}/v1",
  apiKey: process.env.RELAYHUB_API_KEY,
});

const resp = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "用一句話介紹你自己" }],
});
console.log(resp.choices[0].message.content);

也可以只設定環境變數，不改程式碼：OPENAI_BASE_URL 與 OPENAI_API_KEY。

06Anthropic SDK

安裝官方 SDK（pip install anthropic 或 npm install @anthropic-ai/sdk），將 base_url 指向平台根位址。SDK 會以 x-api-key 傳送 Key。


import os
import anthropic

client = anthropic.Anthropic(
    base_url="{{ORIGIN}}",
    api_key=os.environ["RELAYHUB_API_KEY"],
)

msg = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好，Claude"}],
)
print(msg.content[0].text)


import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "{{ORIGIN}}",
  apiKey: process.env.RELAYHUB_API_KEY,
});

const msg = await client.messages.create({
  model: "claude-sonnet-4-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "你好，Claude" }],
});
console.log(msg.content[0].text);


curl {{ORIGIN}}/v1/messages \
  -H "x-api-key: $RELAYHUB_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-5", "max_tokens": 1024,
       "messages": [{"role": "user", "content": "你好，Claude"}]}'

範例中的模型名稱僅供示意，請以模型廣場列出的名稱為準。

07錯誤碼

錯誤回應沿用所呼叫接口的格式：OpenAI 相容接口回傳 {"error": {...}}，Anthropic 接口回傳 {"type": "error", "error": {...}}。可依 HTTP 狀態碼與 type 欄位判斷原因。

狀態碼	type	說明與處理方式
401	`authentication_error`	缺少 API Key 或 Key 無效。確認標頭格式與 Key 是否正確。
402	`insufficient_balance`	帳戶餘額不足。請至控制台儲值後再試。
403	`permission_error`	Key 已停用或過期、帳號已停用，或此 Key 未被允許使用該模型。
429	`rate_limit_error` `insufficient_quota`	超過該 Key 每分鐘請求數上限，或 Key 的額度已用完。限流請稍後重試；額度用完請調整 Key 的額度上限。
503	`no_channel`	目前沒有可服務此模型的渠道，可能是模型名稱有誤或上游暫時全部不可用。請確認模型名稱，稍後重試。

回應範例 · 402


{
  "error": {
    "type": "insufficient_balance",
    "code": "insufficient_balance",
    "message": "帳戶餘額不足，請儲值"
  }
}

上游逾時、5xx 與限流等錯誤，平台會先自動換渠道重試；只有在所有可用渠道都失敗時，錯誤才會回到你的應用。建議客戶端對 429 與 5xx 採用指數退避重試。

08在常用工具中使用

支援自訂 OpenAI Base URL 或 Anthropic Base URL 的工具，都可以直接接入 RelayHub。以下是幾個常見範例：

Cursor

開啟 Settings → Models。
在 OpenAI API Key 填入你的 Key。
開啟「Override OpenAI Base URL」，填入 /v1。
新增要使用的模型名稱並驗證。

Claude Code

在終端機設定環境變數後啟動：

ANTHROPIC_BASE_URL = /
ANTHROPIC_AUTH_TOKEN = 你的 Key

Cline / Roo Code

API Provider 選擇「OpenAI Compatible」。
Base URL 填入 /v1。
填入 API Key 與模型 ID。

Open WebUI、LobeChat 等

在設定中新增 OpenAI 相容連線。
API 位址填入 /v1。
填入 Key，模型清單會自動從 /v1/models 讀取。

Claude Code · bash


export ANTHROPIC_BASE_URL="{{ORIGIN}}"
export ANTHROPIC_AUTH_TOKEN="sk-..."
claude

各工具的設定介面可能隨版本調整，名稱略有不同時，請尋找「Base URL」、「API Endpoint」或「自訂接口」等欄位。

09下一步

準備好了嗎？建立你的第一把 Key，或先估算一下成本。

免費註冊價格計算機瀏覽模型