--- title: 베타 헤더 url: https://platform.claude.com/docs/ko/api/beta-headers description: "`anthropic-beta` 헤더 또는 SDK의 `betas` 매개변수를 사용하여 표준 API에 포함되기 전에 실험적 기능에 액세스하세요." --- 베타 헤더를 사용하면 실험적 기능과 새로운 모델 기능이 표준 API의 일부가 되기 전에 액세스할 수 있습니다. [클라이언트 SDK](https://platform.claude.com/docs/ko/cli-sdks-libraries/overview)는 베타 기능이 활성화된 상태로 API를 호출하기 위한 `client.beta` (csharp, go: `client.Beta`; java: `client.beta()`; php: `$client->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 ``` 각 기능의 문서에는 전송해야 할 정확한 베타 이름이 명시되어 있습니다. [API 개요](https://platform.claude.com/docs/ko/api/overview)에는 현재 베타 상태인 API 목록이 나와 있습니다. 다음 예제는 [컨텍스트 편집](https://platform.claude.com/docs/ko/build-with-claude/context-editing) 베타를 예로 들어 cURL, `ant` CLI, SDK로 동일한 요청을 보내는 방법을 보여줍니다. SDK는 `betas` (csharp, go: `Betas`; java: `.addBeta()`)를 통해 베타 이름을 받아 `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) ``` 베타 기능은 실험적이며 다음과 같을 수 있습니다: * 사전 공지와 함께 호환성이 깨지는 변경이 있을 수 있음 * 지원 중단되거나 제거될 수 있음 * 속도 제한 또는 가격이 다를 수 있음 * 모든 리전에서 사용 가능하지 않을 수 있음 ### 여러 베타 기능 사용 단일 요청에서 여러 베타 기능을 사용하려면 모든 기능 이름을 쉼표로 구분하여 헤더에 포함하세요: ```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`). ### 다른 플랫폼의 베타 기능 베타 이름은 이를 허용하는 모든 플랫폼에서 동일하지만, 모든 플랫폼이 모든 베타를 허용하는 것은 아닙니다. [Claude Platform on AWS](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws), [Microsoft Foundry](https://platform.claude.com/docs/ko/build-with-claude/claude-in-microsoft-foundry), [Google Cloud](https://platform.claude.com/docs/ko/build-with-claude/claude-on-vertex-ai)는 Claude API와 마찬가지로 `anthropic-beta` 헤더로 베타 이름을 받습니다. 여러 베타를 보내려면 이름을 쉼표로 구분하여 하나의 헤더에 넣으세요. Google Cloud는 `anthropic-beta` 헤더를 하나만 읽고 나머지는 무시하므로, 다른 헤더에 있는 베타는 적용되지 않습니다. Amazon Bedrock에서는 호출하는 API에 따라 베타 이름을 넣는 위치가 달라집니다: * [Claude in Amazon Bedrock](https://platform.claude.com/docs/ko/build-with-claude/claude-in-amazon-bedrock)(`bedrock-mantle` 엔드포인트)은 `anthropic-beta` 헤더로 베타 이름을 받습니다. * [InvokeModel API](https://platform.claude.com/docs/ko/build-with-claude/claude-on-amazon-bedrock-legacy)는 헤더가 아닌 요청 본문에서 베타 이름을 읽습니다. 본문의 `anthropic_beta` 배열에 요소당 하나의 이름으로 나열하세요. 예: `"anthropic_beta": ["feature1", "feature2"]`. ### 엔드포인트별 헤더 일부 베타 API는 특정 엔드포인트로 범위가 한정되어 있으며 모든 요청에 기능별 베타 헤더가 필요합니다: | 엔드포인트 | 베타 헤더 | | ------------------------------------------------ | --------------------------- | | `/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/ko/managed-agents/overview), [에이전트 메모리 사용하기](https://platform.claude.com/docs/ko/managed-agents/memory), [MCP 터널 레퍼런스](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/reference#tunnels-api)를 참조하세요. 동일한 엔드포인트에 적용되는 엔드포인트별 헤더를 항상 함께 사용할 수 있는 것은 아닙니다. 메모리 스토어 엔드포인트에서는 `agent-memory-2026-07-22`가 `managed-agents-2026-04-01`을 대체하며, 동일한 요청에 둘 다 보내면 `400` 오류가 반환됩니다. SDK는 각 엔드포인트에 맞는 올바른 헤더를 자동으로 전송합니다. ### 버전 명명 규칙 베타 기능 이름은 일반적으로 `feature-name-YYYY-MM-DD` 패턴을 따르며, 여기서 날짜는 베타가 출시된 시점을 나타냅니다. 항상 문서에 명시된 정확한 베타 기능 이름을 사용하세요. ## 오류 처리 유효하지 않은 베타 이름을 사용하거나 조직에서 액세스 권한이 없는 베타를 사용하면 `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" } ``` ## 도움 받기 베타 기능 업데이트에 대해서는 [릴리스 노트](https://platform.claude.com/docs/ko/release-notes/overview)를 참조하세요. 프로덕션 문제에 대한 도움이 필요하면 [지원팀](https://support.claude.com/)에 문의하세요. ## 다음 단계 Claude API가 반환하는 HTTP 상태 코드, 오류 응답 형식, 요청 ID를 이해하고 SDK의 타입이 지정된 예외로 오류를 처리하세요. 현재 베타 상태인 API를 포함하여 Claude API의 기능을 살펴보세요.