跳到主要內容
RouJet 路捷
登入 免費註冊
Docs

RouJet API 文件

一把金鑰呼叫主流對話、圖片、影片與語音模型。格式跟 OpenAI 相容,原本的程式把網址和金鑰換掉就能用。

文件目前只有繁體中文版。

快速開始

  1. 到 會員中心 註冊,完成 Email 驗證。
  2. 在「點數與儲值」儲值點數。
  3. 在「API 金鑰與用量」建立一把金鑰(開頭是 rj_)。金鑰只會完整顯示一次,請馬上存好。
  4. 把請求送到 https://roujet.ai/v1,模型寫 auto,由路由替您挑。
curl https://roujet.ai/v1/chat/completions \
  -H "Authorization: Bearer $ROUJET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "用三句話介紹台灣的夜市"}]
  }'

用 OpenAI 的 SDK

from openai import OpenAI

client = OpenAI(base_url="https://roujet.ai/v1", api_key="rj_...")
r = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "幫我把這段話改得更正式"}],
)
print(r.choices[0].message.content)
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://roujet.ai/v1", apiKey: process.env.ROUJET_API_KEY });
const r = await client.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "幫我把這段話改得更正式" }],
});
console.log(r.choices[0].message.content);

API 金鑰

每個請求都在標頭帶 Authorization: Bearer rj_…。金鑰代表您的帳號,用掉的點數從您的帳號扣。

  • 每個帳號最多 10 把金鑰;每把可以設定每月點數上限、到期日,也可以停用(停用後不能恢復)。
  • 金鑰只能呼叫 AI 接口:/v1/chat/completions、/v1/models、/v1/ai/*、/v1/gen/*、/v1/route/*、/v1/messages、/v1/responses、/v1/wallet。改密碼、儲值、管理金鑰都要登入會員中心。
  • 每把金鑰的用量在會員中心「API 金鑰與用量」看得到;到了每月上限會回 429 API_KEY_MONTHLY_CAP。
  • 金鑰不要放在網頁或手機程式裡給使用者下載,請放在您自己的伺服器上。

對話:POST /v1/chat/completions

請求與回應都是 OpenAI Chat Completions 的格式;同樣的功能也可以用 POST /v1/ai/chat。

欄位說明
modelauto(智能路由)、auto:fast/auto:standard/auto:advanced(指定檔位),或模型清單裡的 id;只寫模型名稱也可以。
messages對話內容。圖片用 image_url 帶 data URL;PDF、Word、Excel、PowerPoint、純文字可以用 {"type":"file","file":{"filename","file_data":"data:…;base64,…"}} 直接放進訊息。
streamtrue 時逐字回傳(SSE),格式同 OpenAI。最後一段帶 usage 與 billing,然後是 data: [DONE]。
tools、tool_choice工具呼叫,格式同 OpenAI。
response_formatjson_object 或 json_schema。格式不對時會自動重試或改走備援;需要保證格式時不要同時開 stream。
max_tokens、temperature同 OpenAI。n 只支援 1。

RouJet 另外支援的欄位

欄位說明
purpose這次的用途,例如 writing、code、query、vision、research。路由會照這類工作的評測分數挑。
prefercheapest、fastest、fast_start(第一個字最快)、best、balanced。
excludeRegions不要送去某些資料地區的模型,例如 ["CN"]。
no_trainingtrue 時只用不拿資料訓練的模型。
output_script回覆轉繁體或簡體:zh-Hant、zh-Hans、auto、none。
context_overflowtrim:對話太長時從最舊的訊息拿掉,直到放得下。
session_id同一段對話帶同一個值,路由會盡量沿用同一個模型,提高快取命中、降低費用。
metadata.pintrue 或自訂的鍵:第一次挑到的模型記下來,之後都用它,口吻一致。

回應

標準的 OpenAI 回應之外,多一個 billing:

"billing": {
  "model": "實際用的模型 id",
  "pointsFrozen": 12,
  "pointsCharged": 7,
  "balance": 9993,
  "callId": "回饋時用的編號",
  "auto": { "tier": "standard", "reasons": ["…"], "considered": ["…"] },
  "routedFrom": "主要模型出錯時,原本要用的模型"
}

網路斷了想重送,請帶同一個 Idempotency-Key 標頭(8~128 字),10 分鐘內重送會拿到同一個結果,不會重複扣點。

智能路由 auto

模型寫 auto 時,RouJet 依序做四件事:

  1. 讀懂任務:判斷這次要快速、標準還是進階的能力;帶了 purpose 就照用途。
  2. 對照評測:參考每週更新的評測分數,分數不夠的模型不選。
  3. 比較價格與速度:在合格的模型裡挑最划算的。
  4. 備援待命:供應商逾時、限流、出錯時自動改走下一個;備援比較貴,差價由我們吸收。

回應的 billing.auto 會寫選了哪個檔位、為什麼、比較過哪些模型。想先看會選誰、不扣點,可以用 POST /v1/ai/recommend(請求內容跟對話一樣)。

模型清單:GET /v1/models

OpenAI 格式的模型清單,第一個是 auto。每個模型帶 context_length、max_output_tokens、tools、vision。更完整的資料(評測分數、資料地區、單價)用 GET /v1/ai/models,單價要帶金鑰才看得到。

推薦清單:POST /v1/route/recommend

不扣點。給一個生成任務,回排好順序的模型、預估點數和一句理由,排序跟 auto 用同一套。適合放在「讓使用者自己選模型」的畫面。

POST /v1/route/recommend
{ "task": "image", "tier": "balanced", "params": { "refCount": 1 } }

tier 可以是 economy、balanced、quality。結果建議快取 1 小時。

回饋

您的使用者採用、丟掉或重做了結果,回報給我們,路由會越用越準。

  • 對話:POST /v1/ai/calls/{callId}/feedback,帶 verdict(up 或 down)與 reasons。
  • 生成任務:POST /v1/gen/jobs/{id}/feedback。
  • 一次回報很多筆:POST /v1/ai/calls/feedback/batch、POST /v1/gen/feedback/batch,每次最多 100 筆。

我們不保存對話內容。只有在您的使用者同意後,才在回饋裡附上 sample(對話內容),我們會遮掉個資後拿來改進模型選擇。

圖片、影片、語音:/v1/gen

生成任務是非同步的:送出後拿到任務編號,再查進度、下載結果。

方法路徑說明
GET/v1/gen/capabilities每種任務能用的模型與能力(解析度、秒數、參考圖…)
POST/v1/gen/quote先估這次要多少點,不扣點
POST/v1/gen/inputs上傳參考圖、音檔或影片(保留 7 天)
POST/v1/gen/jobs送出任務(請帶 idempotencyKey)
GET/v1/gen/jobs/{id}查進度與結果
GET/v1/gen/jobs/{id}/files/{name}下載結果檔
POST/v1/gen/jobs/{id}/cancel取消並退點

任務種類:image、video、tts(配音)、stt(聽寫)、music、sfx、upscale 等,以 /v1/gen/capabilities 列出的為準。模型一樣可以寫 auto。失敗的任務全額退點,回應的 errorHelp 會說明發生什麼事、下一步怎麼做。

其他 SDK 格式

已經用 Claude 或 OpenAI 新版 SDK 寫好的程式,換網址就能接;路由、計費、備援都一樣,回應另外帶 billing。

格式路徑SDK 設定
Anthropic MessagesPOST /v1/messagesbaseURL: "https://roujet.ai",apiKey 填 RouJet 金鑰
OpenAI ResponsesPOST /v1/responsesbaseURL: "https://roujet.ai/v1"

我們不保存對話,所以 Responses 的 previous_response_id、conversation、background 不支援,請把之前的對話放在 input 一起送。伺服器端工具(例如 web_search)也不支援。

點數餘額:GET /v1/wallet

回您目前可用的點數;每次對話的 billing.balance 也會帶扣完後的餘額。

計費

  • 送出時先凍結這次最多可能用到的點數,完成後照實際用量結算,多凍的退回。
  • 對話照 token 計價,輸入與輸出分開;用量很小時累計到滿 1 點才扣,billing.pointsExact 是精確的數字。
  • 失敗的請求全額退點;供應商出錯改走備援時,比較貴的差價由我們吸收。
  • 送出前想知道要多少點:對話用 POST /v1/ai/quote,生成任務用 POST /v1/gen/quote。

計費規則也整理在 計費方式。

錯誤處理

錯誤的回應格式:

{ "ok": false, "error": { "code": "INSUFFICIENT_CREDITS", "message": "…", "requestId": "…",
  "help": { "who": "you", "action": "top_up", "advice": "…" } } }

程式請看 code(不會改);message 給人看。help.action 告訴您下一步:retry、retry_later(等 retryAfterSec 秒)、change_input、switch_model、sign_in、top_up、contact、none。

代碼意思
UNAUTHENTICATED、INVALID_TOKEN沒帶金鑰,或金鑰不對、已停用、已到期
API_KEY_SCOPE金鑰不能呼叫這個接口(要登入會員中心做)
API_KEY_MONTHLY_CAP這把金鑰到了每月點數上限
INSUFFICIENT_CREDITS點數不夠,請儲值
RATE_LIMITED送太快了,照 retryAfter 秒後再送
VALIDATION_ERROR欄位不對,照訊息修改
MODEL_UNAVAILABLE、MODEL_NOT_IN_MARKET這個模型現在不能用,或您所在的地區不能用;改用 auto 或別的模型
CONTEXT_TOO_LONG對話太長;可以帶 context_overflow: "trim"
PROVIDER_ERROR供應商出錯且備援也不行;有 retryable: true 的可以重送
MAINTENANCE維護中,照訊息的時間再試

速率限制

對話:每個帳號同時 4 個請求、每分鐘 120 次。超過會回 429 並帶 retryAfter(秒)。需要更高的額度,請 與業務聯絡。

資料與隱私

  • 我們不保存對話內容與圖片。
  • 送給模型之前,Email、電話、身分證字號、卡號、統一編號、台灣地址會換成代號,回覆時再換回原值;供應商看不到這些資料。
  • 您所在的地區決定能用哪些模型;也可以用 excludeRegions 指定不要送去哪些地區。