Claude Platform Docs
API 参考使用 API

Beta 标头

通过 anthropic-beta 标头或 SDK 的 betas 参数，在实验性功能成为标准 API 的一部分之前访问这些功能。

Beta 标头（beta headers）允许您在实验性功能和新模型能力成为标准 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 发送的同一请求，并以 context editing（上下文编辑）beta 作为示例。SDK 通过 betas 参数接收 beta 名称，并为您发送 anthropic-beta 标头：

client = Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    betas=["context-management-2025-06-27"],
)

print(response.content)

多个 beta 功能

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

anthropic-beta: feature1,feature2,feature3

您也可以在同一请求中多次发送 anthropic-beta 标头。Claude API 会读取每个 anthropic-beta 标头，因此以下示例与上一个示例等效：

anthropic-beta: feature1
anthropic-beta: feature2
anthropic-beta: feature3

使用 SDK 时，请在 betas 参数中列出每个功能（例如 betas=["feature1", "feature2"]）。使用 CLI 时，请传递单个 --beta 标志，并用逗号分隔功能名称（例如 --beta feature1,feature2）。您也可以重复使用该标志（例如 --beta feature1 --beta feature2）。

特定端点的标头

某些 beta API 的作用范围限定于特定端点，并且要求在每个请求中都包含特定功能的 beta 标头：

端点Beta 标头
/v1/agents、/v1/sessions、/v1/environmentsmanaged-agents-2026-04-01
/v1/tunnelsmcp-tunnels-2026-06-22
/v1/memory_stores 及其子资源agent-memory-2026-07-22

SDK 的 beta 命名空间会自动添加这些标头。仅在发送原始 HTTP 请求时才需要您自行添加。详情请参阅 Managed Agents 概览、使用 agent memory以及 MCP tunnels 参考。

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

版本命名约定

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

错误处理

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

Output
{
  "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 功能的更新，请参阅发布说明。如需生产问题方面的帮助，请联系支持团队。

后续步骤

错误

了解 Claude API 返回的 HTTP 状态码、错误响应结构和请求 ID，并使用 SDK 的类型化异常处理错误。

API 概览

探索 Claude API 的功能，包括当前处于 beta 阶段的 API。

Was this page helpful?