베타 헤더

베타 헤더를 사용하면 실험적 기능과 새로운 모델 기능이 표준 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-5",
    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 터널 참조를 참조하세요.

동일한 엔드포인트에 적용되는 엔드포인트별 헤더가 항상 함께 사용 가능한 것은 아닙니다. 메모리 스토어 엔드포인트에서는 agent-memory-2026-07-22가 managed-agents-2026-04-01을 대체합니다. 동일한 요청에 둘 다 전송하면 400 오류가 반환됩니다. 클라이언트 SDK는 각 엔드포인트에 맞는 올바른 헤더를 자동으로 전송합니다.



버전 명명 규칙

베타 기능 이름은 일반적으로 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"
}



도움 받기

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



다음 단계