claude-code-api-conversation

name	claude-code-api-conversation
description	Use when implementing server-side message and content-block compatibility for a Claude Code Anthropic gateway, including messages arrays, system blocks, tool_result pairing, image/document/thinking blocks, cache_control, and tolerant validation.

Claude Code 网关消息协议

目标

根据本 skill，实现 /v1/messages 服务端对 messages、system 和 content blocks 的兼容解析。你要校验并转发 Anthropic 消息结构，不要实现 Claude Code 本地 transcript 存储。

详细字段见 references/message-wire-format.md。

Message 结构

请求中的 message 只有两类：

{ "role": "user", "content": "hello" }
{ "role": "assistant", "content": [{ "type": "text", "text": "hi" }] }

Claude Code 通常发送 content block array。网关应同时接受字符串和数组。

必须支持的 content blocks

Block	方向	处理
text	user/assistant	普通文本
tool_use	assistant history	模型曾请求工具
tool_result	user	工具执行结果
image	user	base64 图片
document	user	base64 PDF
thinking	assistant history	保留或忽略
redacted_thinking	assistant history	保留或忽略
server_tool_use	assistant history	保留或忽略
cache_edits	user	不支持缓存时忽略

System prompt

system 可能是字符串，也可能是：

[
  { "type": "text", "text": "...", "cache_control": { "type": "ephemeral", "scope": "org" } }
]

不支持 prompt cache 时忽略 cache_control，但保留 text。

Tool pairing

如果历史中有 assistant tool_use，下一条或后续 user message 通常包含同 id 的 tool_result。服务端应尽量保留这条链路给上游模型。

最低要求：

• 孤立 tool_result 不要导致 500；可以忽略或转成文本提示。
• 缺失 tool_result 的 tool_use 不要阻断整个请求；可以按历史内容保留。
• tool_result.tool_use_id 与 tool_use.id 匹配时，应作为工具结果传给上游。

媒体与附件

• image.source 是 base64，media_type 常见 image/png、image/jpeg、image/gif、image/webp。
• document.source.media_type 常见 application/pdf。
• 如果上游不支持媒体，返回明确 400，或把媒体替换为文本占位；不要静默丢掉用户文本。

宽松兼容

Claude Code 请求里可能携带 cache、tool search、advisor、caller 等扩展字段。外部网关不需要实现这些内部能力，但应尽量忽略未知字段，只在真正无法转换时返回 400。