跳到正文
土土金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日 01:33。

共 49 个模型支持此接口,上表列出其中一部分。 在模型广场查看全部

没找到答案?加客服微信 JsnonoChat,发送报错信息里的 request id,我们帮你排查。