--- title: Beta 標頭 url: https://platform.claude.com/docs/zh-TW/api/beta-headers description: 透過 `anthropic-beta` 標頭或 SDK 的 `betas` 參數，在實驗性功能成為標準 API 的一部分之前搶先存取。 --- 「Beta headers」（Beta 標頭）讓您能夠在實驗性功能與新的模型能力成為標準 API 的一部分之前搶先使用。 [用戶端 SDK](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/overview) 提供了 `client.beta` (csharp, go: `client.Beta`; java: `client.beta()`; php: `$client->beta`) 命名空間，用於在啟用 beta 功能的情況下呼叫 API。 ## 如何使用 beta 標頭 若要使用 beta 功能，請在您的 API 請求中加入 `anthropic-beta` 標頭： ```http 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 概覽](https://platform.claude.com/docs/zh-TW/api/overview)列出了目前處於 beta 階段的 API。 以下範例以 [context editing](https://platform.claude.com/docs/zh-TW/build-with-claude/context-editing)（上下文編輯）beta 為例，分別使用 cURL、`ant` CLI 和 SDK 展示相同的請求。SDK 透過 `betas` (csharp, go: `Betas`; java: `.addBeta()`) 接收 beta 名稱，並為您傳送 `anthropic-beta` 標頭： ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: context-management-2025-06-27" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 1024, "messages": [ {"role": "user", "content": "Hello, Claude"} ] }' ``` ```bash CLI ant beta:messages create \ --beta context-management-2025-06-27 \ --model claude-opus-5-5 \ --max-tokens 1024 \ --message '{role: user, content: "Hello, Claude"}' ``` ```python Python 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) ``` ```typescript TypeScript const client = new Anthropic(); const msg = await client.beta.messages.create({ model: "claude-opus-5-5", max_tokens: 1024, messages: [{ role: "user", content: "Hello, Claude" }], betas: ["context-management-2025-06-27"] }); console.log(msg.content); ``` ```csharp C# var client = new AnthropicClient(); var message = await client.Beta.Messages.Create( new MessageCreateParams { Model = Model.ClaudeOpus5_5, MaxTokens = 1024, Messages = [new() { Role = Role.User, Content = "Hello, Claude" }], Betas = ["context-management-2025-06-27"], } ); Console.WriteLine(string.Join("\n", message.Content)); ``` ```go Go client := anthropic.NewClient() message, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 1024, Messages: []anthropic.BetaMessageParam{ anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude")), }, Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaContextManagement2025_06_27}, }) if err != nil { panic(err) } fmt.Printf("%+v\n", message.Content) ``` ```java Java AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(1024) .addUserMessage("Hello, Claude") .addBeta(AnthropicBeta.CONTEXT_MANAGEMENT_2025_06_27) .build(); BetaMessage message = client.beta().messages().create(params); System.out.println(message.content()); ``` ```php PHP $client = new Client(); $message = $client->beta->messages->create( maxTokens: 1024, messages: [['role' => 'user', 'content' => 'Hello, Claude']], model: 'claude-opus-5-5', betas: ['context-management-2025-06-27'], ); echo $message; ``` ```ruby Ruby client = Anthropic::Client.new message = client.beta.messages.create( model: "claude-opus-5-5", max_tokens: 1024, messages: [{role: "user", content: "Hello, Claude"}], betas: ["context-management-2025-06-27"] ) puts(message.content) ``` Beta 功能屬於實驗性質，可能會： * 在事先通知的情況下發生破壞性變更 * 被棄用或移除 * 具有不同的速率限制或定價 * 並非在所有地區皆可使用 ### 多項 beta 功能 若要在單一請求中使用多項 beta 功能，請在標頭中加入所有功能名稱，並以逗號分隔： ```http anthropic-beta: feature1,feature2,feature3 ``` 您也可以在同一個請求中多次傳送 `anthropic-beta` 標頭。Claude API 會讀取每一個 `anthropic-beta` 標頭，因此以下內容與前一個範例等效： ```http anthropic-beta: feature1 anthropic-beta: feature2 anthropic-beta: feature3 ``` 使用 SDK 時，請列出每項功能（例如 `betas=["feature1", "feature2"]` (typescript, ruby: `betas: ["feature1", "feature2"]`; php: `betas: ['feature1', 'feature2']`; csharp: `Betas = ["feature1", "feature2"]`; go: `Betas: []anthropic.AnthropicBeta{"feature1", "feature2"}`; java: `.addBeta("feature1").addBeta("feature2")`)）。使用 CLI 時，請傳入單一 `--beta` 旗標，並以逗號分隔功能名稱（例如 `--beta feature1,feature2`）。您也可以重複使用該旗標（例如 `--beta feature1 --beta feature2`）。 ### 其他平台上的 beta 功能 在所有接受 beta 名稱的平台上，beta 名稱都相同，但並非每個平台都接受每一個 beta。[Claude Platform on AWS](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-platform-on-aws)、[Microsoft Foundry](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-in-microsoft-foundry) 和 [Google Cloud](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-on-vertex-ai) 與 Claude API 一樣，透過 `anthropic-beta` 標頭接收 beta 名稱。若要傳送多個 beta，請將它們的名稱放在同一個標頭中，並以逗號分隔：Google Cloud 只會讀取一個 `anthropic-beta` 標頭並忽略其餘標頭，因此其他標頭中的 beta 不會生效。 在 Amazon Bedrock 上，beta 名稱的放置位置取決於您呼叫的 API： * [Claude in Amazon Bedrock](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-in-amazon-bedrock)（`bedrock-mantle` 端點）透過 `anthropic-beta` 標頭接收它們。 * [InvokeModel API](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-on-amazon-bedrock-legacy) 從請求主體而非標頭中讀取它們。請將它們列在主體的 `anthropic_beta` 陣列中，每個元素一個名稱，例如 `"anthropic_beta": ["feature1", "feature2"]`。 ### 端點專屬標頭 部分 beta API 的範圍限定於特定端點，且每次請求都需要附上該功能專屬的 beta 標頭： | 端點 | Beta 標頭 | | ---------------------------------------------- | --------------------------- | | `/v1/agents`、`/v1/sessions`、`/v1/environments` | `managed-agents-2026-04-01` | | `/v1/tunnels` | `mcp-tunnels-2026-06-22` | | `/v1/memory_stores` 及其子資源 | `agent-memory-2026-07-22` | SDK 的 `client.beta` (csharp, go: `client.Beta`; java: `client.beta()`; php: `$client->beta`) 命名空間會自動加入這些標頭。只有在發出原始 HTTP 請求時，才需要自行加入。詳情請參閱 [Managed Agents 概覽](https://platform.claude.com/docs/zh-TW/managed-agents/overview)、[使用代理記憶](https://platform.claude.com/docs/zh-TW/managed-agents/memory)以及 [MCP 通道參考](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-tunnels/reference#tunnels-api)。 適用於同一端點的端點專屬標頭不一定能夠合併使用。在記憶儲存庫端點上，`agent-memory-2026-07-22` 會取代 `managed-agents-2026-04-01`：在同一個請求中同時傳送兩者會傳回 `400` 錯誤。SDK 會自動為每個端點傳送正確的標頭。 ### 版本命名慣例 Beta 功能名稱通常遵循 `feature-name-YYYY-MM-DD` 的格式，其中日期表示該 beta 的發布時間。請務必使用文件中記載的確切 beta 功能名稱。 ## 錯誤處理 如果您使用了無效的 beta 名稱，或是您的組織無權存取的 beta，您將收到 `400` 錯誤回應： ```json 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 功能的更新資訊，請參閱[版本說明](https://platform.claude.com/docs/zh-TW/release-notes/overview)。如需正式環境問題的協助，請聯繫[支援團隊](https://support.claude.com/)。 ## 後續步驟 了解 Claude API 傳回的 HTTP 狀態碼、錯誤回應結構和請求 ID，並使用 SDK 的型別化例外處理錯誤。 探索 Claude API 的功能，包括目前處於 beta 階段的 API。