Claude Message Threads API 指南（2026 年 11 月）

Claude message threads API 让长对话只上传一次。之后每轮只发新消息（Anthropic 的 Message threads 页面，2026 年 11 月 4 日核对）。第一次的 Messages 请求里加 "thread": {"type": "create"} 和 message-threads-2026-08-12 beta 头，API 就把这段对话留在内存里，下一次请求要传的内容少很多。

所有模型上它都是 beta，17 个模型 ID 可以用。下面代码调用的 Claude Opus 5.5 就在其中。beta 头要加在线程的每个请求上。

一条线程省掉什么

没有线程时，每一轮都要带上整段记录：系统提示词、工具定义、之前每条消息和每个工具结果。线程把这段对话，包括 Claude 的回复，存在响应的 id 下面。continue 请求只发之后新增的内容（Message threads 页面，2026 年 11 月 4 日核对）。每轮要传的东西就少了。

提示缓存从另一个方向帮同一段对话。缓存命中让重复的输入更便宜。Anthropic 价格页（2026 年 11 月 4 日核对）的数字：Opus 5.5 每百万 token 0.20 美元，新输入 4 美元。请求里仍然要带这份输入。线程减少的是上传量，缓存降低的是重复部分的单价。长会话两样都要。上下文这一侧，看减少 Claude Code token 消耗。

线程不改价格，也不改速率限制（Message threads 页面，2026 年 11 月 4 日核对）。现行价格看价格页。

缓存要自己加。每个请求都在顶层发 cache_control，API 就把它用到这个请求 messages 里最后一个可缓存的块上。4 个断点是平台级的提示缓存规则。自动缓存占掉其中一个（Anthropic 提示缓存页面，2026 年 11 月 4 日核对）。可以这样分配：

顶层 cache_control，线程的每个请求占一个；
一个放在 system 上，随 create 请求发；
一个放在 tools 上，也是 create 时；
一个放在最新的消息上。

更早的已存消息上的断点不算在这 4 个里，因为 continue 请求只发新消息。断点发出去就留在原处。重放对话时，把早先消息上的断点去掉。最后一个块上留一个（Message threads 页面，2026 年 11 月 4 日核对）。

先建第一轮，再续传

三步：

把 Anthropic key 放进 ANTHROPIC_API_KEY。
发完整对话，用 system 和 tools 就一起带上，再加 "thread": {"type": "create"}。
只发上次响应之后的新消息，加 "thread": {"type": "continue", "previous_message_id": "<previous id>"}，system 和 tools 都不要带。

每个请求都带 beta 头和 anthropic-version: 2026-10-21。这是当前版本（Anthropic 的 API 版本说明，2026 年 11 月 4 日核对）。

bash

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: message-threads-2026-08-12" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "system": "You are a careful backend reviewer.",
    "messages": [
      {"role": "user", "content": "Read this design and list the risks."}
    ],
    "thread": {"type": "create"}
  }'

把响应里的 id 存下来。下一个请求只发新消息：

bash

PREVIOUS_ID="<id from the previous response>"

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: message-threads-2026-08-12" \
  -H "content-type: application/json" \
  -d @- <<JSON
{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "Turn those risks into a checklist."}
  ],
  "thread": {"type": "continue", "previous_message_id": "$PREVIOUS_ID"}
}
JSON

每次回复都把最新的 id 留着。线程只追加，每个响应的 id 只能续传一次，下一个请求要用最新的那个（Message threads 页面，2026 年 11 月 4 日核对）。

需要另一种拿 API key 的方式，OmniaKey 提供同样模型 ID 的 Claude API 接入，请求体不用改。OmniaKey 支持支付宝和微信支付，人民币充值。线程在 Anthropic 那边是 beta，正式依赖之前，先确认你用的中转把 thread 字段原样传下去。

Python SDK 会替你记 id。用 client.beta.messages.thread(...) 建一个 helper，它只准备调用，每轮用 thread.send() 发出。这个 helper 加上 beta 头，第一轮做 create，之后只带新消息续传（Message threads 页面，2026 年 11 月 4 日核对）。continue 返回 thread_not_found、thread_already_continued 或 thread_continue_in_flight 时，它用一个新的 create 请求把整段对话重放一次。

python

import anthropic

client = anthropic.Anthropic()  # 读取 ANTHROPIC_API_KEY

# helper 此时还没发出请求，它保存每轮都要复用的字段。
thread = client.beta.messages.thread(
    model="claude-opus-5-5",
    max_tokens=1024,
    system="You are a careful backend reviewer.",
)

first = thread.send({"role": "user", "content": "Read this design and list the risks."})
print(first.id, first.stop_reason)

second = thread.send({"role": "user", "content": "Turn those risks into a checklist."})
print(second.id)  # 下次从这个 id 续传

我们没有拿这些请求跑过 Anthropic 的 API。写法来自 Anthropic 的 Message threads 页面。要做流式，thread.stream(...) 加 stream.get_final_message() 是同一套流程；想自己记 id，thread.previous_message_id 会返回当前值。

哪些字段要重发，哪些不要

固定字段每个请求都发同样的值，system 和 tools 只在 create 请求里发，自由字段每轮都可以变。

分组	字段	规则
仅 create	`system`、`tools`	只在 create 请求里发；在 continue 请求里带上其中任何一个，哪怕是 `null`，都返回 400。
固定	`model`、`tool_choice`、`thinking`、除各服务器授权 token 之外的 `mcp_servers`、`context_management`、`output_config`、`container` 里的 `skills`、顶层 `cache_control`，以及 `anthropic-beta` 的取值集合	每次同值。值不同就返回 400，并指出是哪个字段不一样。
自由	`max_tokens`、`stop_sequences`、`stream`、`metadata`、`service_tier`，以及没有列名的字段	随时可以改。

改了固定字段的 400 会带 thread_fingerprint_mismatch，消息里列出不一样的字段。要改其中某个值，就用完整对话和新值开一条新线程。

漏掉 previous_message_id，continue 返回 400，body 里有 message，没有 error_code；带上 system 或 tools 也一样。continue 只该携带上次响应之后的消息。

mcp_servers 是固定字段，但服务器 URL 和授权 token 只存在你的请求里。用 MCP 的每个请求都要发这个列表，token 可能在两次请求之间变化。容器 id 也只存在你的请求里，所以每次都要发 container（Message threads 页面，2026 年 11 月 4 日核对）。

服务端 fallback 在 create 时就定下来：fallbacks 要么在线程的每个请求里都发，要么都不发。值可以每轮变，加上或去掉这个字段会返回 thread_fingerprint_mismatch。

过期、重放和 404

线程在最后一次请求后 5 分钟过期，API 在最后一次使用后最多 1 小时删除它。每个存储的响应都会重新开始算这 5 分钟。线程不适用零数据保留。对话、系统提示词和工具在内存里加密保存，从不写进持久存储（Message threads 页面，2026 年 11 月 4 日核对）。

响应里没有字段说明这一轮是否存下，create 和 continue 都一样。要到下一次 continue 才知道。所以应用自己存好每条消息，以自己为准（Message threads 页面，2026 年 11 月 4 日核对）。

continue 返回 404 thread_not_found 时，用完整对话发一个新的 create 请求，再从那个响应的 id 续传。下面这些情况，API 都给同样的 404：

线程过期了；
上一轮已经处理过又被丢弃，比如被 max_tokens 截断的工具调用；
上一轮的响应由 fallback 模型写出；
上一条响应还在生成；
请求来自另一个组织、工作区、用户或工作区密钥；
新消息带来了已存对话里没有的内容，比如一段对话里的第一张图片。

重放完整对话总是安全的，上面每种情况都能修好。

流式多一条规则：等 message_stop 之后再用响应的 id 续传，早发的 continue 可能返回 404。continue 的流在 message_stop 之前断了，就再发同一个 continue 请求；返回 thread_already_continued 或 thread_continue_in_flight 就重放。流断掉时，SDK helper 把重试留给你。

另外三种情况各有各的处理：

pause_turn：用那个响应的 id 续传，"messages": []。如果 404，就带上暂停的响应重放。
stop_reason: "refusal"：去掉引起它的那一轮，开新线程；API 可能已经保存了被拒的那一轮。
usage.iterations 里或流里最后的 message_delta 里出现 fallback_message 条目，就是 fallback 回答：重放。

错误

5 个线程错误都在模型运行前返回：请求不消耗 token，线程的过期时间也不变。400 的 error.type 是 invalid_request_error，404 是 not_found_error（Message threads 页面，2026 年 11 月 4 日核对）。

404，thread_not_found：API 无法继续这个线程。用完整对话发一个新的 create 请求。
400，thread_fingerprint_mismatch：固定字段和创建时存下的值不一致。保持一致，或者开新线程。
400，thread_already_continued：这个响应 id 已经用过一次。用最新的 id 续传，没拿到就重放。
400，thread_continue_in_flight：同一个 id 上还有 continue 在跑，通常是你自己前一次尝试。等它结束，或者重放。
400，thread_unsupported_request：请求用到线程不支持的功能或组织设置。error.details.unsupported 会指出 context_management、cache_control、fallbacks、hipaa、inference_hooks 中的一个。这个列表会增加；遇到不认识的值，就不带 thread 发完整对话。

Message Batches 不接受 thread 字段，带它的批次项会以 invalid_request_error 失败。token 计数和压缩返回 400；除 clear_thinking_20251015 配 keep: "all" 之外的上下文编辑也返回 400。HIPAA 就绪的组织和开了 Inference hooks 的组织同样被排除。列表、读取、删除线程，这些 API 都没有。

常见问题

什么是 Claude message threads API？

它是 Messages API 的一个 beta 功能，把对话存在 Anthropic 一侧，之后每轮只发新消息。beta 头是 message-threads-2026-08-12，每个请求加一个 thread 对象，type 设为 create 或 continue。

message threads 能和提示缓存一起用吗？

能。线程不替你缓存提示词：每个请求在顶层发 cache_control，断点不超过 4 个。已存消息上的断点不占这 4 个名额，顶层那个和 system、tools 上的要算。

线程中途能换模型吗？

换模型要开新线程。model 是固定字段，换个值就返回 400 thread_fingerprint_mismatch；用完整对话和新模型开一条新线程。

为什么 continue 返回 400 却没有 error_code？

continue 少了 previous_message_id，或者带了 system、tools，哪怕是 null。这类 400 有 message、没有 error_code，看文本就知道。

线程能存多久，过期后会怎样？

线程在最后一次请求后 5 分钟过期，最后一次使用后最多 1 小时被删除。之后 continue 返回 404 thread_not_found；用完整对话发新的 create 请求，再从它的 id 续传。

核对的来源

创建 OmniaKey API key 查看 Claude Opus 5.5 价格

Claude Message Threads API 指南

一条线程省掉什么

先建第一轮，再续传

哪些字段要重发，哪些不要

过期、重放和 404

错误

常见问题

什么是 Claude message threads API？

message threads 能和提示缓存一起用吗？

线程中途能换模型吗？

为什么 continue 返回 400 却没有 error_code？

线程能存多久，过期后会怎样？

核对的来源

文中提到的模型

相关文章

降低 Claude Code Token 消耗

Opus 5.5 与 Sonnet 5.5

Claude 价格 2026：每个套餐多少钱、用量多少、能用哪些模型

最新文章

热门指南

资源

开发者工具

AI 创作工具

公司