Anthropic Messages

POST /v1/messages  compatible  语义操作 generate  契约修订 1

状态语义：stateless; portable is default; native pins one exact Anthropic-wire provider profile and disables cross-provider fallback

已声明的偏差

逐条来自契约，不是补充说明：

• only anthropic-version 2023-06-01 is accepted
• anthropic-beta is forwarded only in native mode and only for tokens the selected connection has been configured to accept; portable mode rejects it because the request is re-authored through the canonical model and a beta token describes the request as written
• tools are classified by execution site: Anthropic-defined client-executed tools are accepted at any dated version suffix, while provider-executed tools require the selected connection to declare provider_executed_tools, because the upstream would make network calls outside SafeTransport’s host allowlist
• family matching is anchored to <family><YYYYMMDD>, so a longer name that merely begins with a known family (bash_code_execution*) is classified on its own terms rather than as the client-executed tool it resembles
• portable mode rejects members of tools[], output_config, and message content blocks that the canonical model cannot carry, because that path re-authors the body and would otherwise drop them silently; native mode forwards them verbatim
• mcp_servers, container, and fallbacks are rejected as deliberate boundaries rather than unmodelled fields: the first two delegate egress or code execution to the upstream, and the third moves model selection outside Halro’s routing and cost attribution
• in native mode tool and content-block bodies are forwarded verbatim, so cache_control and per-tool configuration reach the provider unchanged; portable mode refuses them rather than re-authoring the body without them
• Gateway Keys are accepted through x-api-key for official SDK compatibility and are never forwarded upstream
• native mode is selected with Halro-Route-Mode and requires either the direct Anthropic or Bedrock Mantle Anthropic profile

Anthropic 兼容层。注意 base URL 不带 /v1 —— Anthropic SDK 自己会补上， 这与 OpenAI SDK 相反，接错的表现是 404。认证可用 x-api-key 或 Authorization， 但两个头同时出现且值不一致会直接判失败。

请求示例

curl

curl https://halro.example.com/v1/messages \
  -H "x-api-key: $HALRO_GATEWAY_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{ "model": "claude", "max_tokens": 256,
        "messages": [{"role": "user", "content": "你好"}] }'

Python

import os
from anthropic import Anthropic

# base_url 不带 /v1，SDK 会自己补
client = Anthropic(base_url="https://halro.example.com", api_key=os.environ["HALRO_GATEWAY_KEY"],
                   timeout=60.0, max_retries=0)
message = client.messages.create(
    model="claude", max_tokens=256,
    messages=[{"role": "user", "content": "你好"}],
)
print(message.content[0].text)

Node.js

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

// baseURL 不带 /v1，SDK 会自己补
const client = new Anthropic({
  baseURL: "https://halro.example.com", apiKey: process.env.HALRO_GATEWAY_KEY,
  timeout: 60_000, maxRetries: 0,
});
const message = await client.messages.create({
  model: "claude", max_tokens: 256,
  messages: [{ role: "user", content: "你好" }],
});
console.log(message.content[0].text);

SDK 默认会自动重试

官方 SDK 默认会重试 2 次。Halro 在发出上游请求之前就把预算预留落盘，因此客户端的 静默重试会产生多次独立的预留与结算。示例把它关掉，由你自己决定重试策略 —— 见重试、超时与幂等。

请求头

• x-api-key or Authorization
• anthropic-version
• anthropic-beta
• Halro-Route-Mode
• Content-Type

请求字段

怎么读这张表

第 2 列沉默不等于支持 —— 契约只记录已声明的限制，没列出的 Profile 是「未声明限制」， 不是「已验证支持」。第 3 列是组合级限制：某些拒绝规则在字段粒度上表达不出来 （例如某个 Profile 拒绝「带工具的流式请求」，而 tools 与 stream 单看都支持）。 字段的类型、是否必填与语义说明当前不在契约里，见页脚说明。

字段	不支持该字段的 Provider Profile	组合级限制
model	—	—
max_tokens	—	—
messages	—	—
messages[].role	—	—
messages[].content	—	—
messages[].content[].type=document	—	—
messages[].content[].type=search_result	—	—
system	—	—
stream	—	1 见脚注 1
stop_sequences	bedrock.mantle.openai.responses.v1	—
temperature	—	—
top_p	—	—
top_k	openai.chat-embeddings.v1、azure-openai.chat-embeddings.v1、deepseek.chat.v1、openai-compatible.chat-embeddings.v1、gemini.generate-content.text.v1beta、bedrock.runtime.converse.text.v1、bedrock.mantle.openai.chat.v1、bedrock.mantle.openai.responses.v1	—
tools	gemini.generate-content.text.v1beta、bedrock.runtime.converse.text.v1	2 见脚注 2
tools[].type=custom	—	3 见脚注 3
tools[].type=bash_*	—	4 见脚注 4
tools[].type=text_editor_*	—	5 见脚注 5
tools[].type=memory_*	—	6 见脚注 6
tools[].type=computer_*	—	7 见脚注 7
tool_choice	gemini.generate-content.text.v1beta、bedrock.runtime.converse.text.v1	—
thinking	openai.chat-embeddings.v1、azure-openai.chat-embeddings.v1、deepseek.chat.v1、openai-compatible.chat-embeddings.v1、gemini.generate-content.text.v1beta、bedrock.runtime.converse.text.v1、bedrock.mantle.openai.chat.v1、bedrock.mantle.openai.responses.v1	—
metadata	openai.chat-embeddings.v1、azure-openai.chat-embeddings.v1、deepseek.chat.v1、openai-compatible.chat-embeddings.v1、gemini.generate-content.text.v1beta、bedrock.runtime.converse.text.v1、bedrock.mantle.openai.chat.v1、bedrock.mantle.openai.responses.v1	—
service_tier	openai.chat-embeddings.v1、azure-openai.chat-embeddings.v1、deepseek.chat.v1、openai-compatible.chat-embeddings.v1、gemini.generate-content.text.v1beta、bedrock.runtime.converse.text.v1、bedrock.mantle.openai.chat.v1、bedrock.mantle.openai.responses.v1	—
output_config	—	8 见脚注 8
output_config.effort	deepseek.chat.v1、gemini.generate-content.text.v1beta、bedrock.runtime.converse.text.v1、bedrock.mantle.openai.responses.v1、bedrock.mantle.anthropic.messages.v1	9 见脚注 9
output_config.format	deepseek.chat.v1、gemini.generate-content.text.v1beta、bedrock.runtime.converse.text.v1、bedrock.mantle.anthropic.messages.v1	10 见脚注 10

门面层直接拒绝的字段

这些字段在到达任何 Provider 之前就会被拒。照搬 OpenAI 文档最容易撞上的就是它们：

• provider-executed tools (web_search_*, web_fetch_*, code_execution_*, advisor_*, tool_search_*) unless the selected connection declares provider_executed_tools
• mcp_servers
• container
• fallbacks
• Anthropic-defined tools in portable mode
• strict tools in portable mode
• signed thinking in portable mode
• unknown top-level fields
• unknown members of tools[] and output_config in portable mode

响应字段

id type role content model stop_reason stop_sequence usage

流事件

message_start content_block_start content_block_delta content_block_stop message_delta message_stop ping error

可路由的 Provider Profile 及各自成熟度

端点成熟度不提升单个 Profile

顶部的 compatible 徽章说的是端点，不是下面每一行。每行的成熟度取自该 Profile 自己的覆盖记录。

Provider Profile	成熟度	不支持的请求字段
openai.chat-embeddings.v1	compatible	top_k、thinking、metadata、service_tier
anthropic.messages.2023-06-01	compatible	未声明
azure-openai.chat-embeddings.v1	compatible	top_k、thinking、metadata、service_tier
deepseek.chat.v1	compatible	top_k、thinking、metadata、service_tier、output_config.effort、output_config.format
openai-compatible.chat-embeddings.v1	compatible	top_k、thinking、metadata、service_tier
gemini.generate-content.text.v1beta	compatible	top_k、tools、tool_choice、thinking、metadata、service_tier、output_config.effort、output_config.format
bedrock.runtime.converse.text.v1	compatible	top_k、tools、tool_choice、thinking、metadata、service_tier、output_config.effort、output_config.format
bedrock.mantle.openai.chat.v1	compatible	top_k、thinking、metadata、service_tier
bedrock.mantle.openai.responses.v1	compatible	stop_sequences、top_k、thinking、metadata、service_tier、output_config.effort
bedrock.mantle.anthropic.messages.v1	compatible	output_config.effort、output_config.format

已声明的变换

openai.chat-embeddings.v1

• portable Messages content is mapped through OpenAI Chat Completions

anthropic.messages.2023-06-01

• native mode preserves validated Anthropic content blocks and events

azure-openai.chat-embeddings.v1

• portable Messages content is mapped through Azure Chat Completions

deepseek.chat.v1

• portable Messages content is mapped through DeepSeek Chat Completions
• output_config.effort and output_config.format are declared unsupported at field granularity because support is value-dependent: none, low and high reach DeepSeek’s thinking switch while minimal, medium and xhigh have no rung, and DeepSeek has json_object but no schema mode
• thinking stays unsupported for the same reason it is on every other portable profile — it is the Anthropic-native block config, which only native mode forwards; DeepSeek’s own thinking switch is reached through output_config.effort

openai-compatible.chat-embeddings.v1

• portable Messages content is mapped through an OpenAI-compatible primitive

gemini.generate-content.text.v1beta

• portable text Messages content is mapped through Gemini generateContent
• output_config.effort and output_config.format are this endpoint’s spelling of reasoning_effort and response_format, which this profile declares unsupported at every value, so a request carrying either is routed away before provider I/O

bedrock.runtime.converse.text.v1

• portable text Messages content is mapped through Bedrock Converse
• output_config.effort and output_config.format are this endpoint’s spelling of reasoning_effort and response_format, which this profile declares unsupported at every value, so a request carrying either is routed away before provider I/O

bedrock.mantle.openai.chat.v1

• portable Messages content is mapped through Bedrock Mantle Chat Completions

bedrock.mantle.openai.responses.v1

• portable Messages content is mapped through stateless Bedrock Mantle Responses
• streaming requests with tools are rejected before provider I/O
• output_config.effort is this endpoint’s spelling of reasoning_effort, which the stateless Responses primitive does not carry, so a request carrying it is routed away before provider I/O

bedrock.mantle.anthropic.messages.v1

• native mode preserves validated Anthropic content blocks, thinking signatures, and events
• output_config is unsupported in portable mode only: this profile shares the Anthropic wire form and could carry the member, but its Mantle Beta capability ceiling is fixed by the build and widening it is a separate contract review, so a portable request carrying effort or format is routed away before provider I/O while native mode forwards the member verbatim

证据

已验证的证据：gateway_contract、provider_transport_fixture、sdk_blackbox

SDK 黑盒协议桩矩阵

anthropic-go、anthropic-typescript、anthropic-python

警告

该矩阵只证明这些 SDK 版本能序列化请求、并消费 Halro 声明的响应与流形状。它跑的是协议桩， 不经过真实 Runtime 路由、Gateway Key 认证、路由选择、能力过滤、脱敏与预算核算， 不能被引为端到端网关或真实 Provider 的证据。

---

本页的字段表、覆盖矩阵与偏差列表由 Halro 7117fdc38491 的兼容性契约生成 （scripts/generate-api-pages.mjs，契约摘要 9f8a5c57f76ae870…）。 字段的类型、是否必填与语义说明尚未进入契约，因此本页只列字段名。

Footnotes

1. stream —— bedrock.mantle.openai.responses.v1：streaming requests with tools are rejected before provider I/O ↩

2. tools —— bedrock.mantle.openai.responses.v1：streaming requests with tools are rejected before provider I/O ↩

3. tools[].type=custom —— bedrock.mantle.openai.responses.v1：streaming requests with tools are rejected before provider I/O ↩

4. tools[].type=bash_* —— bedrock.mantle.openai.responses.v1：streaming requests with tools are rejected before provider I/O ↩

5. tools[].type=text_editor_* —— bedrock.mantle.openai.responses.v1：streaming requests with tools are rejected before provider I/O ↩

6. tools[].type=memory_* —— bedrock.mantle.openai.responses.v1：streaming requests with tools are rejected before provider I/O ↩

7. tools[].type=computer_* —— bedrock.mantle.openai.responses.v1：streaming requests with tools are rejected before provider I/O ↩

8. output_config —— gemini.generate-content.text.v1beta：output_config.effort and output_config.format are this endpoint’s spelling of reasoning_effort and response_format, which this profile declares unsupported at every value, so a request carrying either is routed away before provider I/O；bedrock.runtime.converse.text.v1：output_config.effort and output_config.format are this endpoint’s spelling of reasoning_effort and response_format, which this profile declares unsupported at every value, so a request carrying either is routed away before provider I/O；bedrock.mantle.openai.responses.v1：output_config.effort is this endpoint’s spelling of reasoning_effort, which the stateless Responses primitive does not carry, so a request carrying it is routed away before provider I/O；bedrock.mantle.anthropic.messages.v1：output_config is unsupported in portable mode only: this profile shares the Anthropic wire form and could carry the member, but its Mantle Beta capability ceiling is fixed by the build and widening it is a separate contract review, so a portable request carrying effort or format is routed away before provider I/O while native mode forwards the member verbatim ↩

9. output_config.effort —— gemini.generate-content.text.v1beta：output_config.effort and output_config.format are this endpoint’s spelling of reasoning_effort and response_format, which this profile declares unsupported at every value, so a request carrying either is routed away before provider I/O；bedrock.runtime.converse.text.v1：output_config.effort and output_config.format are this endpoint’s spelling of reasoning_effort and response_format, which this profile declares unsupported at every value, so a request carrying either is routed away before provider I/O；bedrock.mantle.openai.responses.v1：output_config.effort is this endpoint’s spelling of reasoning_effort, which the stateless Responses primitive does not carry, so a request carrying it is routed away before provider I/O ↩

10. output_config.format —— gemini.generate-content.text.v1beta：output_config.effort and output_config.format are this endpoint’s spelling of reasoning_effort and response_format, which this profile declares unsupported at every value, so a request carrying either is routed away before provider I/O；bedrock.runtime.converse.text.v1：output_config.effort and output_config.format are this endpoint’s spelling of reasoning_effort and response_format, which this profile declares unsupported at every value, so a request carrying either is routed away before provider I/O ↩