Beta 标头

Beta 标头允许您在实验性功能和新模型能力成为标准 API 的一部分之前访问它们。



如何使用 beta 标头

要访问 beta 功能，请在您的 API 请求中包含 anthropic-beta 标头：

POST /v1/messages
x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01
anthropic-beta: BETA_FEATURE_NAME
content-type: application/json

每个功能的文档都会说明需要发送的确切 beta 名称。API 概述列出了当前处于 beta 阶段的 API。

以下示例展示了使用 cURL、ant CLI 和 SDK 发送的相同请求。SDK 通过 betas 参数接收 beta 名称，并为您发送 anthropic-beta 标头：

client = Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    betas=["files-api-2025-04-14"],
)

print(response.content)



多个 beta 功能

要在单个请求中使用多个 beta 功能，请在标头中包含所有功能名称，并用逗号分隔：

anthropic-beta: feature1,feature2,feature3

使用 SDK 时，请在 betas 参数中列出每个功能（例如，betas=["feature1", "feature2"]）。使用 CLI 时，请传递单个 --beta 标志，并用逗号分隔功能名称（例如，--beta feature1,feature2）。避免重复使用该标志：目前只有第一个标志的值会生效。



特定端点的标头

某些 beta API 仅限于特定端点，并且每个请求都需要特定功能的 beta 标头：

SDK 的 beta 命名空间会自动添加这些标头。只有在发送原始 HTTP 请求时才需要自行添加。详情请参阅 Managed Agents 概述、使用代理记忆以及 MCP 隧道参考。

适用于同一端点的特定端点标头并不总是可以组合使用。在记忆存储端点上，agent-memory-2026-07-22 会替代 managed-agents-2026-04-01：在同一请求中同时发送两者会返回 400 错误。客户端 SDK 会自动为每个端点发送正确的标头。



版本命名约定

Beta 功能名称通常遵循 feature-name-YYYY-MM-DD 的模式，其中日期表示该 beta 版本的发布时间。请始终使用文档中记录的确切 beta 功能名称。



错误处理

如果您使用了无效的 beta 名称，或者您的组织无权访问某个 beta 功能，您将收到 400 错误响应：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Unexpected value(s) `invalid-beta-name` for the `anthropic-beta` header. Please consult our documentation at platform.claude.com/docs or try again without the header."
  },
  "request_id": "req_011CcnGfC9fELffo2EALu4Wd"
}



获取帮助

有关 beta 功能的更新，请参阅发布说明。如需生产环境问题的帮助，请联系支持团队。



后续步骤