Anthropic Message Threads

生产接入：国内网关使用 https://api.modelgo.com，国际网关使用 https://api.modelgo.ai；请使用对应环境的 API Key。下方示例使用国内生产网关。

Message Threads 是 Anthropic Messages 的可选扩展，仍调用 POST /v1/messages。ModelGo 网关保存短期线程，在鉴权后重建完整对话，再向供应商发送普通无状态请求；供应商不会收到 thread 或该功能的 beta 标记。它不依赖供应商原生线程。

客户端每轮上传的数据会减少，供应商仍接收完整历史，输入 token 仍按完整上下文及实际缓存用量计算。这不是自动提示词缓存，也不保证降低模型调用费用或首 token 延迟。

官方 SDK

以下用法已验证于 Python anthropic==2.4.0（Python 3.10+）和 TypeScript @anthropic-ai/sdk@1.4.0。SDK 自动添加 anthropic-beta: message-threads-2026-08-12。

示例中的模型名仅作演示；请替换为当前环境中 API Key 已获授权、且已配置有效价格 的模型。示例不表示每个 API Key 都可使用该 Claude 型号。

python

import os
import anthropic

client = anthropic.Anthropic(
    api_key=os.environ["MODELGO_API_KEY"],
    base_url="https://api.modelgo.com",  # 不带 /v1
)
thread = client.beta.messages.thread(
    model="claude-haiku-4.5",  # API Key 须有该模型权限
    max_tokens=256,
    system="回答简洁，并记住用户给出的标记。",
)
thread.send({"role": "user", "content": "记住标记 ALPHA。"})
reply = thread.send({"role": "user", "content": "刚才的标记是什么？"})
print(reply.content)

with thread.stream({"role": "user", "content": "再重复一次。"}) as stream:
    final = stream.get_final_message()

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env.MODELGO_API_KEY,
  baseURL: 'https://api.modelgo.com',
});
const thread = client.beta.messages.thread({
  model: 'claude-haiku-4.5', max_tokens: 256,
  system: 'Keep replies short and remember the user marker.',
});
await thread.send({ role: 'user', content: 'Remember ALPHA.' });
const reply = await thread.send({ role: 'user', content: 'What was the marker?' });
const final = await thread.stream({ role: 'user', content: 'Repeat it.' }).finalMessage();

创建 helper 不发送请求。第一次 send() 创建线程，后续 send() / stream() 只上传新增消息；helper 在本地保留完整历史。

手动发送与约束

每次请求都带上述 beta 头，鉴权沿用 x-api-key。首次发送完整对话、system、tools 并增加 "thread":{"type":"create"}；后续用上次响应的 id：

json

{
  "model": "claude-haiku-4.5",
  "max_tokens": 256,
  "thread": {"type": "continue", "previous_message_id": "msg_previous"},
  "messages": [{"role": "user", "content": "下一轮问题"}]
}

continuation 不得重复 system / tools，也不要再上传旧消息或上一轮 assistant 回复。tool_result 放在新增的 user 消息中；pause_turn 则用空 messages 继续。
同一响应 id 只能继续一次；顺序使用最新响应。流式请求收到 message_stop 后再继续。编辑历史或分支对话时，携带完整历史重新 create。
model、thinking、tool_choice、output_config、顶层 cache_control 和 beta 集合等固定字段须保持一致；SDK helper 会管理这些字段。更改它们时重新 create。
不支持与 Idempotency-Key 或 /v1/messages/count_tokens 组合使用；计数时发送完整上下文。压缩与修改历史的 context-management 组合目前不支持。

有效期与恢复

线程是尽力保留的短期上下文，每个成功保存的响应最多可继续 5 分钟，也可能因容量、存储异常等原因提前不可用。它不是持久对话库；应用必须保留完整历史，进程重启后也要能自行恢复。线程正文在共享存储中加密，但这不是零数据留存（ZDR）功能。

thread_not_found 时，重新 create 并上传完整历史；官方 SDK helper 会自动重放。helper 默认在 thread_unsupported_request 时抛错；可选 Python unsupported_request_behavior="continue_unthreaded" 或 TypeScript unsupportedRequestBehavior: 'continue_unthreaded'，让该轮及之后各轮改为上传完整历史、不带 thread。恢复为无线程请求后，网关不再为这些请求保留线程。

线程错误

线程错误使用 Anthropic 嵌套结构，恢复码位于 error.details.error_code：

json

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "thread_not_found",
    "details": {"error_code": "thread_not_found"}
  }
}

HTTP	恢复码	含义
404	`thread_not_found`	不存在、已过期或不属于当前身份；使用完整历史重新 create
400	`thread_fingerprint_mismatch`	固定字段变化；修正字段或重新 create
400	`thread_already_continued`	该响应已被继续；使用最新响应或完整历史重新 create
400	`thread_continue_in_flight`	该响应正在执行，或派发结果尚不确定；不要盲目重复提交
400	`thread_unsupported_request`	功能未启用、不支持的字段组合、容量或存储不可用；可选择无线程的完整历史请求

SDK 还会在 continuation 遇到 thread_already_continued / thread_continue_in_flight 时重新 create；应用需理解这会产生新请求，不能用它替代对不确定执行结果的核对。

参考：Anthropic 官方 Message Threads 文档。ModelGo 的供应商请求和计费边界以上述网关说明为准。