跳到正文
土土金API

開始

認證與 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 原生 Messagesx-api-key: sk-...,同時帶 anthropic-version: 2023-06-01/v1/messages 和模型列表介面
Gemini 原生 generateContentx-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": "你好"}]
  }'

Base URL 怎麼填

OpenAI SDK 的 base URL 要帶 /v1;Anthropic 和 Google 的 SDK 會自己在後面拼介面路徑,所以只填站點根地址。

你在用的 SDK 或方式參數填寫的值
OpenAI SDK(Python / Node.js)base_url / baseURL,或環境變數 OPENAI_BASE_URLhttps://www.tutujin.com/v1
Anthropic SDKbase_url / baseURLhttps://www.tutujin.com
Google Gen AI SDKhttp_options 裡的 base_urlhttps://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"],
)

各個 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、小程式的前端程式碼,也不要提交到程式碼倉庫。

認證相關的報錯

狀態碼常見原因怎麼處理
401Key 填錯、已刪除、已停用、已過期,或這把 Key 的額度上限用完了檢查請求頭裡的 Key 是否完整,在控制台確認 Key 的狀態
403帳戶餘額不足、IP 不在白名單、模型不在白名單、Key 的分組不可用按報錯資訊調整設定或充值,不要自動重試

完整的狀態碼說明和重試建議見錯誤碼與重試。

沒找到答案?加客服微信 JsnonoChat,傳送報錯資訊裡的 request id,我們幫你排查。