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 tunnels 參考文件。

適用於同一端點的特定端點標頭並非總是可以組合使用。在記憶體儲存端點上，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 功能的更新，請參閱版本資訊。如需生產環境問題的協助，請聯絡支援團隊。



後續步驟