Messages (Anthropic)

/v1/messages 实现 Anthropic 官方 Messages 协议，是 Claude 系列模型与 Claude Code CLI 的默认通道。


POST https://api.ttttt.ai/v1/messages
x-api-key: owo-...
anthropic-version: 2023-06-01
Content-Type: application/json

协议字段对齐 Anthropic 官方 Messages API 。本页只列差异点。

Header 要求

Header	是否必填	说明
`x-api-key`	必填（或用 `Authorization: Bearer`）	ttttt.ai 平台密钥
`anthropic-version`	必填	Anthropic 官方版本号；目前推荐 `2023-06-01`
`Content-Type`	必填	`application/json`

Authorization: Bearer owo-... 也接受——见鉴权。

最小请求


curl https://api.ttttt.ai/v1/messages \
  -H "x-api-key: owo-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "用一句话解释黑洞。"}
    ]
  }'

关键字段

字段	类型	说明
`model`	string	必填。例如 `claude-sonnet-4-6`、`claude-opus-4-7`
`max_tokens`	integer	必填。最大输出 token 数；Anthropic 协议要求显式给
`messages`	array	必填。多轮对话；只接受 `user` / `assistant`
`system`	string	顶层系统提示词；不放在 `messages` 里
`temperature`	number	`0–1`（注意比 OpenAI 范围窄）
`stream`	boolean	SSE 流式
`tools`	array	tool use 定义
`stop_sequences`	array	自定义停止字符串
`metadata`	object	`{user_id: "..."}` 透传
`cache_control`	object（在 message / system / tool 内）	Prompt cache 标记

响应


{
  "id": "msg_018ff3a2",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-6",
  "content": [
    { "type": "text", "text": "黑洞是引力强到连光也逃不掉的天体。" }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 24,
    "output_tokens": 17,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

Prompt Cache

Anthropic 的 prompt cache 在长 system / tools / 多轮历史场景能省 90% 的 input cost。在希望被缓存的 block 上加 cache_control：


{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "<很长的 system 提示词，几千 token>",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [
    { "role": "user", "content": "请求 1" }
  ]
}

第一次调用会写缓存（按 cacheWritePer1M 计价），随后 5 分钟内同样 prefix 的请求命中缓存（按 cacheReadPer1M 计价，通常 < 10% 输入价）。

ttttt.ai 平台原样透传 cache_control 字段，并把上游响应的 cache_creation_input_tokens / cache_read_input_tokens 写进用量记录。详见计费模型 → 缓存计费。

Tool Use


{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "tools": [
    {
      "name": "get_weather",
      "description": "Get current temperature",
      "input_schema": {
        "type": "object",
        "properties": { "city": { "type": "string" } },
        "required": ["city"]
      }
    }
  ],
  "messages": [
    { "role": "user", "content": "上海多少度？" }
  ]
}

响应里：


{
  "content": [
    { "type": "tool_use", "id": "toolu_01", "name": "get_weather",
      "input": { "city": "Shanghai" } }
  ],
  "stop_reason": "tool_use"
}

按官方协议 follow-up：把 tool 结果以 tool_result 形式塞进下一轮 messages。

视觉输入


{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "image",
          "source": { "type": "base64",
                      "media_type": "image/png",
                      "data": "..." } },
        { "type": "text", "text": "这张图里是什么？" }
      ]
    }
  ]
}

流式


{ "stream": true, ... }

事件流（节选）：


event: message_start
data: {"message": {...}}

event: content_block_start
data: {"index": 0, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"index": 0, "delta": {"type": "text_delta", "text": "黑"}}

event: content_block_delta
data: {"index": 0, "delta": {"type": "text_delta", "text": "洞"}}

event: message_delta
data: {"usage": {"output_tokens": 17}}

event: message_stop
data: {}

完整 SSE 解析见流式响应。

计费字段

平台从响应里读取下面 4 个字段入账：

上游字段	入账项
`usage.input_tokens`	input_tokens（不含缓存命中）
`usage.output_tokens`	output_tokens
`usage.cache_creation_input_tokens`	cache_write_tokens
`usage.cache_read_input_tokens`	cache_read_tokens

测试期注意

当前 ttttt.ai 处于测试阶段，公开模型仅 gpt-5.5 / gpt-5.4（走 OpenAI 协议）。 Claude 系列协议层已完成兼容测试，将随测试期结束陆续开放——详见模型清单。

常见问题

Q: 我同时设置了 Authorization 和 x-api-key，会冲突吗？ A: 不会。网关按出现顺序取第一个有效值。

Q: 必须传 anthropic-version 吗？ A: 必须。这是 Anthropic 官方协议要求；不传时上游会拒。2023-06-01 是当前主流值。

Q: Claude 的 streaming 和 OpenAI 的 streaming 解析能复用吗？ A: 不能。两者事件结构完全不同（见流式响应），但主流 SDK 都已经封装好，你不必手写解析。