開始
認證與 Base URL
所有介面都用控制台建立的 sk- 開頭的 Key 認證。OpenAI 格式用 Authorization 請求頭,Claude 原生也認 x-api-key,Gemini 原生也認 x-goog-api-key;OpenAI 相容 Base URL 是 https://www.tutujin.com/v1。
所有介面都用同一把 API Key 認證,Key 在控制台建立,以 sk- 開頭。OpenAI 格式的請求把 Key 放在 Authorization: Bearer 請求頭裡;Claude 原生和 Gemini 原生介面還認各自官方 SDK 預設使用的請求頭,所以用官方 SDK 時只要改 base URL 和 Key。
三種請求頭寫法
| 介面格式 | 請求頭 | 生效範圍 |
|---|---|---|
| OpenAI 相容(Chat Completions、Responses、Embeddings、影像、語音、Rerank) | Authorization: Bearer sk-... | 所有介面 |
| Claude 原生 Messages | x-api-key: sk-...,同時帶 anthropic-version: 2023-06-01 | /v1/messages 和模型列表介面 |
| Gemini 原生 generateContent | x-goog-api-key: sk-... | /v1beta/models/... 和模型列表介面 |
Authorization: Bearer 在任何介面上都能用,包括 Claude 和 Gemini 的原生路徑。另外兩種寫法是為了相容官方 SDK,不需要自己改請求頭。Gemini 原生路徑也接受 URL 參數 ?key=,但 URL 容易被日誌和代理記錄下來,建議用請求頭。
curl https://www.tutujin.com/v1/chat/completions \
-H "Authorization: Bearer $TUTUJIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.4-mini",
"messages": [{"role": "user", "content": "你好"}]
}'curl https://www.tutujin.com/v1/messages \
-H "x-api-key: $TUTUJIN_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-haiku-5-5",
"max_tokens": 256,
"messages": [{"role": "user", "content": "你好"}]
}'curl "https://www.tutujin.com/v1beta/models/gemini-3.8-flash:generateContent" \
-H "x-goog-api-key: $TUTUJIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{"role": "user", "parts": [{"text": "你好"}]}]
}'Base URL 怎麼填
OpenAI SDK 的 base URL 要帶 /v1;Anthropic 和 Google 的 SDK 會自己在後面拼介面路徑,所以只填站點根地址。
| 你在用的 SDK 或方式 | 參數 | 填寫的值 |
|---|---|---|
| OpenAI SDK(Python / Node.js) | base_url / baseURL,或環境變數 OPENAI_BASE_URL | https://www.tutujin.com/v1 |
| Anthropic SDK | base_url / baseURL | https://www.tutujin.com |
| Google Gen AI SDK | http_options 裡的 base_url | https://www.tutujin.com |
| 直接發 HTTP 請求 | 完整地址 | 例如 https://www.tutujin.com/v1/chat/completions、https://www.tutujin.com/v1/messages |
import os
from openai import OpenAI
client = OpenAI(
base_url="https://www.tutujin.com/v1",
api_key=os.environ["TUTUJIN_API_KEY"],
)import os
import anthropic
client = anthropic.Anthropic(
base_url="https://www.tutujin.com",
api_key=os.environ["TUTUJIN_API_KEY"],
)import os
from google import genai
from google.genai import types
client = genai.Client(
api_key=os.environ["TUTUJIN_API_KEY"],
http_options=types.HttpOptions(base_url="https://www.tutujin.com"),
)各個 SDK 的完整用法見 OpenAI SDK、Anthropic SDK 兩篇整合指南。
Key 的權限設定
在控制台新建或編輯 Key 時,可以給每把 Key 單獨限定:
| 設定 | 不滿足時的結果 |
|---|---|
| 分組 | 決定這把 Key 走哪條線路、按哪檔價格計費,見選擇分組 |
| 額度上限 | 這把 Key 花完上限後返回 401,其他 Key 不受影響 |
| 過期時間 | 過期後返回 401 |
| 模型白名單 | 呼叫白名單以外的模型返回 403 |
| IP 白名單 | 來自其他 IP 的請求返回 403 |
控制台預設只顯示 Key 的掩碼。建議一個專案、一個環境各用一把 Key,生產環境的 Key 設上模型白名單和 IP 白名單,洩露後能把損失限制在一把 Key 內。更多做法見 API Key 安全最佳實踐。
Key 只能放在伺服器端,用環境變數或金鑰管理服務儲存。不要寫進網頁、App、小程式的前端程式碼,也不要提交到程式碼倉庫。
認證相關的報錯
| 狀態碼 | 常見原因 | 怎麼處理 |
|---|---|---|
| 401 | Key 填錯、已刪除、已停用、已過期,或這把 Key 的額度上限用完了 | 檢查請求頭裡的 Key 是否完整,在控制台確認 Key 的狀態 |
| 403 | 帳戶餘額不足、IP 不在白名單、模型不在白名單、Key 的分組不可用 | 按報錯資訊調整設定或充值,不要自動重試 |
完整的狀態碼說明和重試建議見錯誤碼與重試。
沒找到答案?加客服微信 JsnonoChat,傳送報錯資訊裡的 request id,我們幫你排查。