跳到正文
土土金API

API 參考

Claude Messages 原生介面

POST /v1/messages 的請求頭、參數、請求與響應示例、SSE 流式事件和提示快取寫法。格式與 Anthropic Messages API 一致,官方 SDK 改 base_url 即可使用,已在本站實測。

POST /v1/messages 是 Anthropic 的原生介面格式。已經用 Anthropic 官方 SDK 寫好的程式碼,把 base URL 改成 https://www.tutujin.com、Key 換成本站的 Key 就能執行,thinking、工具呼叫、cache_control 這些原生參數都按原樣傳給模型。本介面已在本站實測。

POSThttps://www.tutujin.com/v1/messages

請求頭

請求頭必填說明
x-api-key二選一控制台建立的 API Key(sk-...)。Anthropic SDK 預設用這個請求頭
Authorization二選一Bearer sk-...,和 x-api-key 任選一種
anthropic-version是介面版本,填 2023-06-01
content-type是application/json
anthropic-beta否開啟 Anthropic 的測試功能,按原樣轉發,是否生效取決於模型

請求參數

參數類型必填說明
modelstring是模型名,例如 claude-sonnet-5-5
max_tokensinteger是本次最多生成多少 tokens。這個參數必填,漏傳會返回 400
messagesarray是對話訊息。role 只能是 user 或 assistant,第一條必須是 user
systemstring 或 array否系統提示詞,放在頂層,不放進 messages
temperaturenumber否0 到 1,預設 1。數值越低迴答越穩定
top_pnumber否核取樣,和 temperature 一般只調一個
top_kinteger否只從機率最高的 K 個 token 裡取樣
stop_sequencesarray否遇到這些字串時停止生成
streamboolean否設為 true 時按 SSE 事件流返回
toolsarray否工具定義,每個工具包含 name、description 和 input_schema(JSON Schema)
tool_choiceobject否{"type": "auto"}、{"type": "any"},或用 {"type": "tool", "name": "get_weather"} 指定工具
thinkingobject否擴展思考,例如 {"type": "enabled", "budget_tokens": 2048},budget_tokens 要小於 max_tokens。各模型支援的寫法以 Anthropic 的說明為準
metadataobject否例如 {"user_id": "u_123"},填你這邊的終端使用者標識,便於排查濫用

messages 結構

content 可以是字串,也可以是內容塊陣列。數組裡常見的塊類型有 text、image、tool_use(模型發起的工具呼叫)和 tool_result(你回傳的執行結果)。圖文輸入的寫法:

JSON
{
  "role": "user",
  "content": [
    {
      "type": "image",
      "source": { "type": "base64", "media_type": "image/png", "data": "iVBORw0KGgo..." }
    },
    { "type": "text", "text": "这张图里的表格一共有几行?" }
  ]
}

請求示例

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-sonnet-5-5",
    "max_tokens": 1024,
    "system": "你是严谨的法务助理,回答时注明依据的合同条款编号。",
    "messages": [
      {"role": "user", "content": "违约金按合同总额 30% 计算,这个约定有什么风险?"}
    ]
  }'

Anthropic SDK 會自動帶上 x-api-key 和 anthropic-version,並在 base URL 後面拼接 /v1/messages,所以 base URL 只填站點根地址。

響應示例

JSON
{
  "id": "msg_...",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5-5",
  "content": [
    { "type": "text", "text": "30% 的比例明显偏高,在诉讼中可能被认定为过高……" }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 52,
    "output_tokens": 210,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}
欄位說明
content內容塊陣列,可能包含 text、thinking(開啟擴展思考時)和 tool_use
stop_reasonend_turn 正常結束;max_tokens 達到生成上限被截斷;stop_sequence 遇到停止詞;tool_use 需要你執行工具
usage.input_tokens未命中快取的輸入 tokens,按輸入單價計費
usage.output_tokens輸出 tokens,含思考內容,按輸出單價計費
usage.cache_creation_input_tokens本次寫入快取的輸入 tokens,按快取寫入價計費
usage.cache_read_input_tokens命中快取的輸入 tokens,按快取讀取價計費

流式輸出

設定 "stream": true 後,服務端按 Anthropic 的 SSE 事件格式返回。文本增量在 content_block_delta 事件的 delta.text 裡,message_delta 事件帶有結束原因和最終的輸出 tokens:

Text
event: message_start
data: {"type":"message_start","message":{"id":"msg_...","type":"message","role":"assistant","content":[],"usage":{"input_tokens":52,"output_tokens":1}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"30% 的比例"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":210}}

event: message_stop
data: {"type":"message_stop"}

SDK 封裝了這些事件,直接讀文本流即可:

with client.messages.stream(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "写一段 100 字的产品介绍"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    print("\n", stream.get_final_message().usage)

提示快取

系統提示詞、產品手冊這類每次都要傳送的長字首,可以在內容塊上加 cache_control 標記,讓模型快取起來。後續請求命中快取時,這部分按快取讀取價計費:

JSON
{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "system": [
    { "type": "text", "text": "你是售后客服,只依据下面的退换货政策回答。" },
    { "type": "text", "text": "(这里放很长的退换货政策全文)", "cache_control": { "type": "ephemeral" } }
  ],
  "messages": [{ "role": "user", "content": "拆封后还能退吗?" }]
}

cache_control 按原格式轉發給模型。快取寫入和快取讀取各自按價目表中的價格計費,是否命中看響應 usage 裡的 cache_read_input_tokens。快取的原理和適用場景見上下文快取是什麼、怎麼省錢。

注意事項

  • max_tokens 必填。系統提示詞放在頂層的 system,不要作為一條訊息放進 messages。
  • messages 必須以 user 開頭,user 和 assistant 交替出現。
  • 擴展思考的內容計入輸出 tokens,budget_tokens 設得越大,單次費用上限越高。
  • 不同 Claude 分組的線路來源和價格不同,見選擇分組。
  • 需要在多家模型之間切換時,可以改用 Chat Completions,目錄中標註支援該介面的 Claude 模型同樣可以呼叫。擴展思考、提示快取這類原生能力,用本介面寫法更直接。

支援此介面的模型

模型廠商最低價分組輸入 ¥/百萬輸出 ¥/百萬按次 ¥/次
Claude Haiku 5.5AnthropicClaude 優質¥0.4¥2—
Claude Sonnet 5.5AnthropicClaude 經濟¥3.2¥16—
Claude Opus 5.5AnthropicClaude 經濟¥8¥40—
claude-3-5-sonnet-allAnthropic經濟按量——¥0.128
Claude Haiku 5.5AnthropicClaude 優質¥0.4¥2—
claude-haiku-4-5-20251001AnthropicClaude 經濟¥1.6¥8—
claude-haiku-4-5-20251001-thinkingAnthropicClaude 經濟¥1.6¥8—
claude-3-haiku-20240307AnthropicClaude 官方¥1.88¥9.38—

價格為人民幣,取各模型最低價分組;價格更新於 2026年11月13日 下午6:08。

共 49 個模型支援此介面,上表列出其中一部分。 在模型廣場檢視全部

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