API 레퍼런스API 사용하기

API 개요

Copy page



Claude API에서 사용 가능한 엔드포인트, 인증 헤더, 클라이언트 SDK, 페이지네이션, 속도 제한 및 클라우드 플랫폼 액세스 옵션을 이해합니다.

Claude API는 https://api.anthropic.com에서 제공되는 RESTful API로, Claude 모델과 Claude Managed Agents에 대한 프로그래밍 방식의 액세스를 제공합니다.

사전 요구 사항

Claude API를 사용하려면 다음이 필요합니다:

• Claude Console 계정
• API 키 또는 구성된 Workload Identity Federation 규칙

단계별 설정 지침은 시작하기를 참조하세요.

사용 가능한 API

Claude API에는 다음 API가 포함됩니다:

• Messages API: 대화형 상호작용을 위해 Claude에 메시지를 전송합니다 (POST /v1/messages)
• Message Batches API: 대량의 Messages 요청을 50% 비용 절감으로 비동기 처리합니다 (POST /v1/messages/batches)
• Token Counting API: 비용과 속도 제한을 관리하기 위해 전송 전에 메시지의 토큰 수를 계산합니다 (POST /v1/messages/count_tokens)
• Models API: 사용 가능한 Claude 모델과 세부 정보를 나열합니다 (GET /v1/models)
• Files API: 여러 API 호출에서 사용할 파일을 업로드하고 관리합니다 (POST /v1/files, GET /v1/files)
• Skills API: 사용자 정의 에이전트 스킬을 생성하고 관리합니다 (POST /v1/skills, GET /v1/skills)

다음 API는 베타 상태입니다:

• Agents API: Claude Managed Agents를 위한 재사용 가능하고 버전이 관리되는 에이전트 구성을 정의합니다 (POST /v1/agents, GET /v1/agents)
• Sessions API: 관리형 클라우드 샌드박스에서 상태를 유지하는 에이전트 세션을 실행합니다 (POST /v1/sessions, GET /v1/sessions/{id}/events/stream)
• Environments API: 에이전트 세션을 위한 샌드박스 템플릿을 구성합니다 (POST /v1/environments, GET /v1/environments)

모든 엔드포인트, 매개변수 및 응답 스키마가 포함된 전체 API 레퍼런스는 내비게이션에 나열된 API 레퍼런스 페이지를 살펴보세요. 베타 기능에 액세스하려면 베타 헤더를 참조하세요.

인증

각 인증 방법과 사용 시점에 대한 자세한 내용은 인증을 참조하세요. Claude API에 대한 요청에는 다음 헤더가 포함됩니다:

클라이언트 SDK를 사용하는 경우, SDK가 인증, 버전 및 content-type 헤더를 자동으로 전송합니다. 키에 필요한 경우 anthropic-workspace-id는 직접 전달해야 합니다. API 버전 관리에 대한 자세한 내용은 API 버전을 참조하세요.

클라우드 플랫폼을 통해 Claude에 액세스하는 경우, 인증은 클라우드 제공업체의 IAM 시스템과 통합됩니다. 지원되는 자격 증명 유형, 필수 헤더 및 인증 옵션은 플랫폼별 문서를 참조하세요.

API 키 발급받기

API는 웹 Console을 통해 제공됩니다. playground를 사용하여 브라우저에서 API를 시험해 본 다음 계정 설정에서 API 키를 생성할 수 있습니다(Claude API 키 받기 참조). 키를 생성할 때 각 키의 유형(키 유형 참조)과 만료를 선택합니다. 워크스페이스를 사용하여 환경을 분리하고 사용 사례별로 지출을 제어하세요.

클라이언트 SDK

Anthropic은 인증, 요청 형식 지정, 오류 처리 등을 처리하여 API 통합을 간소화하는 공식 SDK를 제공합니다.

이점:

• 자동 헤더 관리 (인증, anthropic-version, content-type)
• 타입 안전한 요청 및 응답 처리
• 내장된 재시도 로직 및 오류 처리
• "Streaming"(스트리밍) 지원
• 요청 타임아웃 및 연결 관리

클라이언트 SDK 목록은 클라이언트 SDK를 참조하세요.

Claude API와 클라우드 플랫폼 비교

Claude는 직접 Claude API와 클라우드 플랫폼을 통해 사용할 수 있습니다. 인프라, 기능 가용성, 규정 준수 요구 사항 및 가격 선호도에 따라 선택하세요.

Claude API

• 최신 모델과 기능에 대한 직접 액세스
• Anthropic 청구 및 지원
• 적합한 경우: 신규 통합, 전체 기능 액세스, Anthropic과의 직접적인 관계

클라우드 플랫폼 API

AWS, Google Cloud 또는 Microsoft Azure를 통해 Claude에 액세스합니다:

• 클라우드 제공업체의 청구 및 IAM과 통합
• 기능 가용성은 플랫폼마다 다릅니다: Anthropic이 운영하는 플랫폼에는 Claude Platform on AWS와 Microsoft Foundry가 있으며, 파트너가 운영하는 플랫폼에는 Amazon Bedrock과 Google Cloud가 있습니다. 기능 가용성과 제공 시기는 각 플랫폼의 페이지를 참조하세요.
• 적합한 경우: 기존 클라우드 약정, 특정 규정 준수 요구 사항, 통합된 클라우드 청구

요청 및 응답 형식

요청 크기 제한

이 제한을 초과하면 413 request_too_large 오류가 반환됩니다.

응답 헤더

Claude API는 응답에 다음 헤더를 포함합니다:

속도 제한 헤더에 대해서는 속도 제한 문서의 응답 헤더를 참조하세요. 각 SDK에서 이름으로 응답 헤더를 읽는 예제는 API 응답의 워크스페이스 식별하기를 참조하세요.

페이지네이션

목록 엔드포인트는 결과를 페이지 단위로 반환합니다. 대부분의 최신 목록 엔드포인트는 이 섹션에서 설명하는 page 및 next_page 커서 방식을 사용합니다. 일부는 다른 방식을 사용하며, 이 섹션 끝의 참고 사항을 확인하세요. limit 쿼리 매개변수를 사용하여 페이지 크기를 제어하고 page 쿼리 매개변수를 사용하여 인접한 페이지를 가져옵니다. 각 응답에는 페이지 간 이동을 위한 커서 필드와 함께 data 배열이 포함됩니다.

이전 페이지로 돌아가려면 prev_page를 page 매개변수로 전달하세요. 첫 페이지에 있을 때 prev_page는 null입니다. 모든 목록 엔드포인트가 prev_page를 지원하는 것은 아닙니다. GET /v1/sessions만 prev_page를 반환하며, 역방향 페이지네이션을 지원하지 않는 목록 엔드포인트에서는 이 필드가 null이 아니라 응답에서 아예 생략됩니다. 요청 과정에 대한 안내는 세션 나열하기를 참조하세요.

모든 SDK는 next_page를 자동으로 따라가는 자동 페이지네이션 이터레이터를 제공합니다. Python과 TypeScript에서는 목록 결과를 직접 반복하여 이를 사용할 수 있습니다. 다른 SDK는 별도의 메서드를 통해 이터레이터를 제공합니다. SDK 자동 페이지네이션은 정방향 전용이므로, 이전 페이지로 돌아가려면 응답에서 prev_page를 읽어 직접 page 매개변수로 전달해야 합니다. 언어별 세부 사항은 클라이언트 SDK를 참조하세요.

속도 제한 및 가용성

속도 제한

API는 오용을 방지하고 용량을 관리하기 위해 "rate limit"(속도 제한)과 지출 한도를 적용합니다. 제한은 사용 등급으로 구성되며, 조직은 자동으로 특정 등급에 배정되고 시간이 지남에 따라 더 높은 등급으로 이동할 수 있습니다. 각 등급에는 다음이 있습니다:

• 지출 한도: API 사용에 대한 최대 월간 비용
• 속도 제한: 분당 최대 요청 수(RPM) 및 분당 최대 토큰 수(TPM)

Console의 속도 제한 페이지에서 속도 제한을, 청구 페이지에서 지출 한도를 확인할 수 있습니다. 더 높은 속도 제한이나 더 높은 월간 지출 상한이 필요한 경우 속도 제한 페이지의 Request rate limit increase를 사용하세요.

제한, 등급 및 속도 제한에 사용되는 토큰 버킷 알고리즘에 대한 자세한 내용은 속도 제한을 참조하세요.

가용성

Claude API는 전 세계 여러 국가 및 지역에서 사용할 수 있습니다. 지원 지역 페이지에서 해당 위치의 가용성을 확인하세요.

다음 단계