Claude API 문서 개편: GA/Beta 엔드포인트 및 신규 인증 방식 정리

2026년 5월 22일, Anthropic의 Claude API 문서가 대폭 재구성되었습니다. 기존의 「Client SDKs」 페이지가 「Using the API」 가이드로 개편되었으며, GA(General Availability, 일반 제공)와 Beta 엔드포인트가 명확하게 정리되었습니다.

또한, Workload Identity Federation (WIF)을 통한 Bearer 토큰 인증이 정식으로 지원되며, 엔드포인트별 요청 크기 제한(Request Size Limit)도 명문화되었습니다. Claude를 사용한 개발 및 운영과 관련된 모든 분들에게 영향을 미치는 변경 사항입니다.

📌 영향을 받는 사람

• Claude API를 직접 이용하는 개발자
• Managed Agents / Agentic 시스템을 구축 및 운영 중인 팀
• AWS / Google Cloud / Azure를 통해 Claude를 이용하는 분
• CI/CD 파이프라인이나 운영 환경에서 Claude API를 호출하고 있는 엔지니어

이전 문서에서는 SDK 중심의 안내에 그쳤으나, 이번 개편을 통해 Claude API가 https://api.anthropic.com의 RESTful API임을 명시하면서 각 엔드포인트의 상태가 정리되었습니다.

상태	엔드포인트	메서드	비고
GA	Messages API	POST /v1/messages	메인 추론 엔드포인트
GA	Message Batches API	POST /v1/messages/batches	50% 비용 절감
GA	Token Counting API	POST /v1/messages/count_tokens	사전 토큰 수 추정
GA	Models API	GET /v1/models	이용 가능한 모델 목록
Beta	Files API	—	파일 업로드 관리
Beta	Skills API	—	Managed Agents용 스킬 정의
Beta	Agents API	—	에이전트 실행 관리
Beta	Sessions API	—	세션 상태 관리
Beta	Environments API	—	실행 환경 설정 및 관리

⚠️ Breaking Change (중대한 변경 사항)

Beta 엔드포인트(Files, Skills, Agents, Sessions, Environments)는 사양 변경의 가능성이 있습니다. 운영 환경에 도입하기 전에 변경 이력을 지속적으로 확인하는 것을 강력히 권장합니다.

기존의 x-api-key에 더해, 수명이 짧은 액세스 토큰을 사용한 Bearer 인증이 정식으로 지원되었습니다. 이는 CI/CD 파이프라인이나 여러 서비스 간의 인증 통합 시 보안 강화로 직결되는 변경입니다.

필수 헤더(Header) 정리

헤더	필수/선택	설명
x-api-key	둘 중 하나 필수	기존의 API 키 인증
Authorization: Bearer <token>	둘 중 하나 필수	WIF를 통한 단기 토큰 인증
anthropic-version	필수	API 버전 지정
content-type: application/json	필수	요청 형식

제한을 초과하면 413 request_too_large 에러가 반환됩니다. 대용량 데이터를 다루는 시스템에서는 사전에 확인이 필요합니다.

엔드포인트	직접 Claude API 사용	Vertex AI	Bedrock
Messages / Token Counting / Sessions / Agents / Environments	32 MB	30 MB	20 MB
Message Batches	256 MB	—	—
Files	500 MB	—	—

💡 Tips

Claude Platform on AWS는 직접 Claude API와 동일한 제한이 적용됩니다. Vertex AI 또는 Bedrock을 경유하는 경우에는 클라우드 측의 고유 제한(각각 30MB / 20MB)에 주의하십시오.

Claude의 이용 경로가 명확하게 분류되었습니다.

Claude Managed Agents를 사용할 수 있는 경로는 직접적인 Claude API와 Claude Platform on AWS뿐입니다. Bedrock이나 Vertex AI를 경유해서는 Managed Agents를 이용할 수 없다는 점에 주의하십시오.

Managed Agents를 사용 중인 경우

• 이용 중인 Agents / Sessions / Environments API가 Beta 상태임을 인지하고, 변경 통지를 추적할 수 있는 체계를 갖출 것

• Bedrock / Vertex AI를 통해 Managed Agents를 이용하려고 하는 경우, 직접 API 또는 Claude Platform on AWS로의 이전을 검토할 것

대용량 데이터를 다루는 시스템

• Vertex AI 경유 시 30MB, Bedrock 경유 시 20MB의 상한선에 걸려 있지 않은지 확인할 것

• Files API (Beta, 500MB)를 사용하여 대용량 파일의 송수신을 효율화할 수 있음

CI/CD 파이프라인이나 IAM 통합을 검토 중인 경우

• Workload Identity Federation을 사용한 Bearer 토큰 인증으로 전환하면, 수명이 긴 API 키를 시크릿 (Secret)으로 관리해야 하는 리스크를 줄일 수 있음

Message Batches API를 사용하지 않는 경우

• GA 상태에서 50%의 비용 절감이 가능합니다. 대량의 요청을 배치 처리 (Batch processing)로 전환하는 것만으로도 비용을 절반으로 줄일 수 있습니다.

import anthropic
client = anthropic.Anthropic(api_key="sk-ant-...")
response = client.messages.create(
...

import anthropic
import httpx
# Workload Identity Federation으로 토큰을 취득
...

import anthropic
client = anthropic.Anthropic(api_key="sk-ant-...")
# 여러 요청을 배치로 전송
...

이번 Claude API 문서 개편은 단순한 정보 정리에 그치지 않고, 향후 기능 확장 방향을 보여주는 중요한 업데이트입니다.

변경점	중요도	대응 긴급도
GA/Beta 엔드포인트의 체계화	🔴 높음	즉시 확인
...

특히 Managed Agents 계열의 API (Agents / Sessions / Skills / Environments)는 모두 Beta 상태이며, 향후에도 사양 변경이 발생할 수 있습니다. 운영 환경에서 사용할 경우에는 폴백 (Fallback) 설계나 변경 통지 구독을 강력히 권장합니다. 또한, Message Batches API는 GA 상태에서 50% 비용 절감이라는 강력한 이점이 있으므로, 아직 사용하지 않는 분들은 즉시 검토할 가치가 있습니다.