跳到主要内容

Anthropic Messages 接口

Claude 原生的 /v1/messages 协议，在图灵平台以完全兼容的形式透传给 Vertex AI 上的 Claude 模型。相比 Chat Completions，这条通道能直接使用 Claude 专有能力：cache_control 精细缓存、adaptive thinking、web_search_20250305 等 server-side tool，以及原生的 content block 结构。

完整 schema 与 Try-It

本页讲概念、差异与典型用法。完整请求 / 响应字段、交互式 Try-It 与多语言代码样例在 API 参考 → Create a message 以及 Count tokens。

什么时候选这个接口​

  • 需要 cache_control 精细控制缓存：Chat Completions 协议没有这个能力
  • 需要 Claude 原生的 thinking / server_tool_use block 结构：比如要在响应里直接拿到带签名的思考块透传
  • 已经用 Anthropic Python / Node SDK：直接换 base_url 即可接入

其它选择：

概览​

项目说明
端点POST /api/v1/messages
协议兼容Anthropic Messages API ↗
主要用途Claude 原生对话 / 工具调用 / extended thinking / web search / prompt caching
支持模型以 模型价格清单 → Claude 为准
Authorization header

图灵平台使用 Authorization: Bearer $API_KEY，不是 Anthropic 官方的 x-api-key。SDK 已经做了转换；直接用 cURL 时留意。

能力集成​

System prompt + 缓存控制​

Claude 的缓存是调用方主动声明：

curl $TURING_BASE_URL/messages \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "turing/claude-sonnet-5",
    "max_tokens": 1024,
    "system": [{
      "type": "text",
      "text": "<LARGE_INSTRUCTION>",
      "cache_control": {"type": "ephemeral"}
    }],
    "messages": [{"role": "user", "content": "..."}]
  }'

首次请求 usage.cache_creation_input_tokens 非零（按缓存写单价计费）；后续请求 usage.cache_read_input_tokens 非零（按缓存读单价，约 10% 基础价）。4.6+ 支持 cache_control: {"type": "ephemeral", "ttl": "1h"} 开启 1 小时缓存。

完整用法见 Prompt 缓存 (Claude)。

Extended thinking​

curl $TURING_BASE_URL/messages \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "turing/claude-opus-4.8",
    "max_tokens": 16000,
    "thinking": {"type": "adaptive", "display": "summarized"},
    "messages": [{"role": "user", "content": "Explain why the sum of two even numbers is always even."}]
  }'
  • Sonnet 5：adaptive 默认开启；不支持 enabled，可用 disabled 关闭
  • Opus 4.7 / 4.8：只支持 type: "adaptive"，默认关闭，需显式传入；传 enabled 会 400
  • Opus 4.6 / Sonnet 4.6：两种都支持，官方建议 adaptive
  • 4.5 及更早：只支持 type: "enabled" + budget_tokens

详见 思考模型配置。

Web search（server-side tool）​

curl $TURING_BASE_URL/messages \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "turing/claude-sonnet-5",
    "max_tokens": 4096,
    "messages": [{"role": "user", "content": "今日上证指数收盘价？"}],
    "tools": [{
      "type": "web_search_20250305",
      "name": "web_search",
      "max_uses": 3
    }]
  }'

响应里会依次出现 server_tool_use → web_search_tool_result → 带 citations 的 text block。计费计数器 usage.server_tool_use.web_search_requests 按 $10/1K 计。

详见 模型内置 Web Search。

工具使用（client-side tool）​

curl $TURING_BASE_URL/messages \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "turing/claude-sonnet-5",
    "max_tokens": 512,
    "messages": [{"role": "user", "content": "上海今天天气？"}],
    "tools": [{
      "name": "get_weather",
      "description": "查询指定城市当前天气",
      "input_schema": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }],
    "tool_choice": {"type": "auto"}
  }'

模型命中时返回 content: [{"type": "tool_use", "id": "...", "name": "...", "input": {...}}]；执行工具后以 {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "...", "content": "..."}]} 回传续写。

与 Chat Completions 的关键差异​

  • input_tokens 只计非缓存输入：Anthropic usage.input_tokens 不包含 cache_read_input_tokens；OpenAI prompt_tokens 是总输入。平台账单按全量计。
  • content 是 block 数组：text / thinking / tool_use / server_tool_use / web_search_tool_result 等多种类型。和 OpenAI 的 message.content 单一字符串语义不同。
  • max_tokens 必填：开启 thinking 时还必须 > thinking.budget_tokens。
  • 流式事件类型更细：message_start / content_block_start / content_block_delta（text_delta 或 thinking_delta 或 input_json_delta）/ content_block_stop / message_delta / message_stop。

字段到账单单价的映射见 计费与用量。

turing_options​

图灵平台扩展的 turing_options 字段（请求体顶层），用于配置超时、重试、fallback 等平台行为。字段定义与取值见 超时、重试与 Fallback。

See also​