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 這些原生參數都按原樣傳給模型。本介面已在本站實測。
https://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 的測試功能,按原樣轉發,是否生效取決於模型 |
請求參數
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
model | string | 是 | 模型名,例如 claude-sonnet-5-5 |
max_tokens | integer | 是 | 本次最多生成多少 tokens。這個參數必填,漏傳會返回 400 |
messages | array | 是 | 對話訊息。role 只能是 user 或 assistant,第一條必須是 user |
system | string 或 array | 否 | 系統提示詞,放在頂層,不放進 messages |
temperature | number | 否 | 0 到 1,預設 1。數值越低迴答越穩定 |
top_p | number | 否 | 核取樣,和 temperature 一般只調一個 |
top_k | integer | 否 | 只從機率最高的 K 個 token 裡取樣 |
stop_sequences | array | 否 | 遇到這些字串時停止生成 |
stream | boolean | 否 | 設為 true 時按 SSE 事件流返回 |
tools | array | 否 | 工具定義,每個工具包含 name、description 和 input_schema(JSON Schema) |
tool_choice | object | 否 | {"type": "auto"}、{"type": "any"},或用 {"type": "tool", "name": "get_weather"} 指定工具 |
thinking | object | 否 | 擴展思考,例如 {"type": "enabled", "budget_tokens": 2048},budget_tokens 要小於 max_tokens。各模型支援的寫法以 Anthropic 的說明為準 |
metadata | object | 否 | 例如 {"user_id": "u_123"},填你這邊的終端使用者標識,便於排查濫用 |
messages 結構
content 可以是字串,也可以是內容塊陣列。數組裡常見的塊類型有 text、image、tool_use(模型發起的工具呼叫)和 tool_result(你回傳的執行結果)。圖文輸入的寫法:
{
"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% 计算,这个约定有什么风险?"}
]
}'import os
import anthropic
client = anthropic.Anthropic(
base_url="https://www.tutujin.com",
api_key=os.environ["TUTUJIN_API_KEY"],
)
message = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=1024,
system="你是严谨的法务助理,回答时注明依据的合同条款编号。",
messages=[{"role": "user", "content": "违约金按合同总额 30% 计算,这个约定有什么风险?"}],
)
print(message.content[0].text)
print(message.usage)import Anthropic from '@anthropic-ai/sdk'
const client = new Anthropic({ baseURL: 'https://www.tutujin.com', apiKey: process.env.TUTUJIN_API_KEY })
const message = await client.messages.create({
model: 'claude-sonnet-5-5',
max_tokens: 1024,
system: '你是严谨的法务助理,回答时注明依据的合同条款编号。',
messages: [{ role: 'user', content: '违约金按合同总额 30% 计算,这个约定有什么风险?' }],
})
console.log(message.content[0].text)
console.log(message.usage)Anthropic SDK 會自動帶上 x-api-key 和 anthropic-version,並在 base URL 後面拼接 /v1/messages,所以 base URL 只填站點根地址。
響應示例
{
"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_reason | end_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:
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)const stream = client.messages.stream({
model: 'claude-sonnet-5-5',
max_tokens: 1024,
messages: [{ role: 'user', content: '写一段 100 字的产品介绍' }],
})
stream.on('text', (text) => process.stdout.write(text))
const final = await stream.finalMessage()
console.log('\n', final.usage)提示快取
系統提示詞、產品手冊這類每次都要傳送的長字首,可以在內容塊上加 cache_control 標記,讓模型快取起來。後續請求命中快取時,這部分按快取讀取價計費:
{
"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.5 | Anthropic | Claude 優質 | ¥0.4 | ¥2 | — |
| Claude Sonnet 5.5 | Anthropic | Claude 經濟 | ¥3.2 | ¥16 | — |
| Claude Opus 5.5 | Anthropic | Claude 經濟 | ¥8 | ¥40 | — |
| claude-3-5-sonnet-all | Anthropic | 經濟按量 | — | — | ¥0.128 |
| Claude Haiku 5.5 | Anthropic | Claude 優質 | ¥0.4 | ¥2 | — |
| claude-haiku-4-5-20251001 | Anthropic | Claude 經濟 | ¥1.6 | ¥8 | — |
| claude-haiku-4-5-20251001-thinking | Anthropic | Claude 經濟 | ¥1.6 | ¥8 | — |
| claude-3-haiku-20240307 | Anthropic | Claude 官方 | ¥1.88 | ¥9.38 | — |
價格為人民幣,取各模型最低價分組;價格更新於 2026年11月13日 下午6:08。
共 49 個模型支援此介面,上表列出其中一部分。 在模型廣場檢視全部
沒找到答案?加客服微信 JsnonoChat,傳送報錯資訊裡的 request id,我們幫你排查。