快速開始
- 到 會員中心 註冊,完成 Email 驗證。
- 在「點數與儲值」儲值點數。
- 在「API 金鑰與用量」建立一把金鑰(開頭是
rj_)。金鑰只會完整顯示一次,請馬上存好。 - 把請求送到
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。
| 欄位 | 說明 |
|---|---|
model | auto(智能路由)、auto:fast/auto:standard/auto:advanced(指定檔位),或模型清單裡的 id;只寫模型名稱也可以。 |
messages | 對話內容。圖片用 image_url 帶 data URL;PDF、Word、Excel、PowerPoint、純文字可以用 {"type":"file","file":{"filename","file_data":"data:…;base64,…"}} 直接放進訊息。 |
stream | true 時逐字回傳(SSE),格式同 OpenAI。最後一段帶 usage 與 billing,然後是 data: [DONE]。 |
tools、tool_choice | 工具呼叫,格式同 OpenAI。 |
response_format | json_object 或 json_schema。格式不對時會自動重試或改走備援;需要保證格式時不要同時開 stream。 |
max_tokens、temperature | 同 OpenAI。n 只支援 1。 |
RouJet 另外支援的欄位
| 欄位 | 說明 |
|---|---|
purpose | 這次的用途,例如 writing、code、query、vision、research。路由會照這類工作的評測分數挑。 |
prefer | cheapest、fastest、fast_start(第一個字最快)、best、balanced。 |
excludeRegions | 不要送去某些資料地區的模型,例如 ["CN"]。 |
no_training | true 時只用不拿資料訓練的模型。 |
output_script | 回覆轉繁體或簡體:zh-Hant、zh-Hans、auto、none。 |
context_overflow | trim:對話太長時從最舊的訊息拿掉,直到放得下。 |
session_id | 同一段對話帶同一個值,路由會盡量沿用同一個模型,提高快取命中、降低費用。 |
metadata.pin | true 或自訂的鍵:第一次挑到的模型記下來,之後都用它,口吻一致。 |
回應
標準的 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 依序做四件事:
- 讀懂任務:判斷這次要快速、標準還是進階的能力;帶了
purpose就照用途。 - 對照評測:參考每週更新的評測分數,分數不夠的模型不選。
- 比較價格與速度:在合格的模型裡挑最划算的。
- 備援待命:供應商逾時、限流、出錯時自動改走下一個;備援比較貴,差價由我們吸收。
回應的 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 Messages | POST /v1/messages | baseURL: "https://roujet.ai",apiKey 填 RouJet 金鑰 |
| OpenAI Responses | POST /v1/responses | baseURL: "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指定不要送去哪些地區。