베타 헤더

베타 헤더를 사용하면 실험적 기능과 새로운 모델 기능이 표준 API의 일부가 되기 전에 접근할 수 있습니다.



베타 헤더 사용 방법

베타 기능에 접근하려면 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

각 기능의 문서에는 전송해야 할 정확한 베타 이름이 명시되어 있습니다. API 개요에는 현재 베타 상태인 API가 나열되어 있습니다.

다음 예제는 cURL, ant CLI, SDK를 사용한 동일한 요청을 보여줍니다. SDK는 betas 매개변수로 베타 이름을 받아 anthropic-beta 헤더를 자동으로 전송합니다:

client = Anthropic()

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

print(response.content)



여러 베타 기능

단일 요청에서 여러 베타 기능을 사용하려면 모든 기능 이름을 쉼표로 구분하여 헤더에 포함하세요:

anthropic-beta: feature1,feature2,feature3

SDK를 사용할 때는 betas 매개변수에 각 기능을 나열하세요(예: betas=["feature1", "feature2"]). CLI를 사용할 때는 기능 이름을 쉼표로 구분하여 단일 --beta 플래그로 전달하세요(예: --beta feature1,feature2). 플래그를 반복하지 마세요. 현재는 첫 번째 플래그의 값만 적용됩니다.



엔드포인트별 헤더

일부 베타 API는 특정 엔드포인트로 범위가 제한되며 모든 요청에 기능별 베타 헤더가 필요합니다:

SDK의 beta 네임스페이스는 이러한 헤더를 자동으로 추가합니다. 원시 HTTP 요청을 할 때만 직접 추가하세요. 자세한 내용은 Managed Agents 개요와 MCP 터널 레퍼런스를 참조하세요.



버전 명명 규칙

베타 기능 이름은 일반적으로 feature-name-YYYY-MM-DD 패턴을 따르며, 날짜는 베타가 출시된 시점을 나타냅니다. 항상 문서에 명시된 정확한 베타 기능 이름을 사용하세요.



오류 처리

유효하지 않은 베타 이름을 사용하거나 조직에서 접근 권한이 없는 베타를 사용하면 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"
}



도움 받기

베타 기능 업데이트에 대해서는 릴리스 노트를 참조하세요. 프로덕션 문제에 대한 도움이 필요하면 지원팀에 문의하세요.



다음 단계