---
title: API 개요
url: https://platform.claude.com/docs/ko/api/overview
description: Claude API의 사용 가능한 엔드포인트, 인증 헤더, 클라이언트 SDK, 페이지네이션, 속도 제한 및 클라우드 플랫폼 접근 옵션을 이해하세요.
---
Claude API는 `https://api.anthropic.com`에 위치한 RESTful API로, Claude 모델과 Claude Managed Agents에 대한 프로그래밍 방식의 접근을 제공합니다.
**Claude를 처음 사용하시나요?** 직접적인 모델 접근을 위해서는 [시작하기](https://platform.claude.com/docs/ko/get-started)와 [Messages로 작업하기](https://platform.claude.com/docs/ko/build-with-claude/working-with-messages)부터 시작하세요. 관리형 에이전트 인프라에 대해서는 [Claude Managed Agents 빠른 시작](https://platform.claude.com/docs/ko/managed-agents/quickstart)을 참조하세요.
## 사전 요구 사항
Claude API를 사용하려면 다음이 필요합니다:
* [Claude Console 계정](https://platform.claude.com)
* Console에서 발급받은 [API 키](https://platform.claude.com/settings/keys) 또는 구성된 [Workload Identity Federation](https://platform.claude.com/docs/ko/manage-claude/workload-identity-federation) 규칙
단계별 설정 지침은 [시작하기](https://platform.claude.com/docs/ko/get-started)를 참조하세요.
## 사용 가능한 API
Claude API에는 다음 API가 포함됩니다:
* **[Messages API](https://platform.claude.com/docs/ko/api/messages/create)**: 대화형 상호작용을 위해 Claude에 메시지를 전송합니다 (`POST /v1/messages`)
* **[Message Batches API](https://platform.claude.com/docs/ko/api/messages/batches/create)**: 대량의 Messages 요청을 비동기적으로 처리하여 비용을 50% 절감합니다 (`POST /v1/messages/batches`)
* **[Token Counting API](https://platform.claude.com/docs/ko/api/messages/count_tokens)**: 비용과 속도 제한을 관리하기 위해 전송 전에 메시지의 토큰 수를 계산합니다 (`POST /v1/messages/count_tokens`)
* **[Models API](https://platform.claude.com/docs/ko/api/models/list)**: 사용 가능한 Claude 모델과 세부 정보를 나열합니다 (`GET /v1/models`)
* **[Files API](https://platform.claude.com/docs/ko/api/files/upload)**: 여러 API 호출에서 사용할 파일을 업로드하고 관리합니다 (`POST /v1/files`, `GET /v1/files`)
* **[Skills API](https://platform.claude.com/docs/ko/api/skills/create)**: 사용자 지정 에이전트 스킬을 생성하고 관리합니다 (`POST /v1/skills`, `GET /v1/skills`)
다음 API는 베타 버전입니다:
* **[Agents API](https://platform.claude.com/docs/ko/managed-agents/agent-setup)**: Claude Managed Agents를 위한 재사용 가능하고 버전 관리되는 에이전트 구성을 정의합니다 (`POST /v1/agents`, `GET /v1/agents`)
* **[Sessions API](https://platform.claude.com/docs/ko/managed-agents/sessions)**: 관리형 클라우드 샌드박스에서 상태 저장 에이전트 세션을 실행합니다 (`POST /v1/sessions`, `GET /v1/sessions/{id}/events/stream`)
* **[Environments API](https://platform.claude.com/docs/ko/managed-agents/environments)**: 에이전트 세션을 위한 샌드박스 템플릿을 구성합니다 (`POST /v1/environments`, `GET /v1/environments`)
모든 엔드포인트, 매개변수 및 응답 스키마가 포함된 전체 API 참조는 탐색 메뉴에 나열된 API 참조 페이지를 살펴보세요. 베타 기능에 접근하려면 [Beta 헤더](https://platform.claude.com/docs/ko/api/beta-headers)를 참조하세요.
## 인증
각 인증 방법과 사용 시기에 대한 자세한 내용은 [인증](https://platform.claude.com/docs/ko/manage-claude/authentication)을 참조하세요. Claude API에 대한 요청에는 다음 헤더가 포함됩니다:
| 헤더 | 값 | 필수 여부 |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Authorization` | `Bearer `. 여기서 ``은 API 키 또는 [Workload Identity Federation](https://platform.claude.com/docs/ko/manage-claude/workload-identity-federation)을 통해 `POST /v1/oauth/token`에서 얻은 단기 액세스 토큰입니다 | 예, `x-api-key`가 설정되지 않은 경우 |
| `x-api-key` | Console에서 발급받은 API 키. `Authorization`의 레거시 대체 수단이며 여전히 지원됩니다 | 아니요 |
| `anthropic-workspace-id` | 요청이 실행되는 [워크스페이스](https://platform.claude.com/docs/ko/manage-claude/workspaces)의 ID (예: `wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ`). [워크스페이스 선택](https://platform.claude.com/docs/ko/manage-claude/authentication#select-a-workspace)을 참조하세요. | 다중 워크스페이스 API 키에서는 필수입니다. 다른 API 키에서는 선택 사항입니다. 단일 워크스페이스용으로 생성된 키는 헤더를 생략하면 해당 워크스페이스에서 실행됩니다. 토큰 교환 시 워크스페이스를 선택하는 Workload Identity Federation 토큰에서는 사용되지 않습니다. |
| `anthropic-version` | API 버전 (예: `2023-06-01`) | 예 |
| `content-type` | `application/json` | 예 |
[클라이언트 SDK](https://platform.claude.com/docs/ko/api/overview#client-sdks)를 사용하는 경우, SDK가 인증, 버전 및 content-type 헤더를 자동으로 전송합니다. 키에 필요한 경우 `anthropic-workspace-id`는 직접 전달합니다. API 버전 관리에 대한 자세한 내용은 [API 버전](https://platform.claude.com/docs/ko/api/versioning)을 참조하세요.
[클라우드 플랫폼](https://platform.claude.com/docs/ko/api/overview#claude-api-vs-cloud-platforms)을 통해 Claude에 접근할 때는 인증이 클라우드 제공업체의 IAM 시스템과 통합됩니다. 지원되는 자격 증명 유형, 필수 헤더 및 인증 옵션은 플랫폼별 문서를 참조하세요.
### API 키 발급받기
API는 웹 [Console](https://platform.claude.com/)을 통해 제공됩니다. Console에서 [playground](https://platform.claude.com/playground)(`platform.claude.com/playground`)를 사용하여 브라우저에서 API를 시험해 본 다음 [API 키](https://platform.claude.com/settings/keys) 페이지(`platform.claude.com/settings/keys`)에서 API 키를 생성할 수 있습니다. 방법은 [Claude API 키 받기](https://platform.claude.com/docs/ko/get-api-key)를 참조하세요. 키를 생성할 때 각 키의 유형([키 유형](https://platform.claude.com/docs/ko/manage-claude/authentication#key-types) 참조)과 [만료](https://platform.claude.com/docs/ko/manage-claude/authentication#key-expiration)를 선택합니다. Console의 [워크스페이스](https://platform.claude.com/settings/workspaces)를 사용하여 환경을 분리하고 사용 사례별로 [지출을 관리](https://platform.claude.com/docs/ko/api/rate-limits)하세요.
## 클라이언트 SDK
Anthropic은 인증, 요청 형식 지정, 오류 처리 등을 처리하여 API 통합을 단순화하는 공식 SDK를 제공합니다.
**이점:**
* 자동 헤더 관리 (인증, `anthropic-version`, `content-type`)
* 타입 안전 요청 및 응답 처리
* 내장된 재시도 로직 및 오류 처리
* 스트리밍 지원
* 요청 타임아웃 및 연결 관리
클라이언트 SDK 목록은 [클라이언트 SDK](https://platform.claude.com/docs/ko/cli-sdks-libraries/overview)를 참조하세요.
## Claude API와 클라우드 플랫폼 비교
Claude는 직접적인 Claude API와 클라우드 플랫폼을 통해 사용할 수 있습니다. 인프라, 기능 가용성, 규정 준수 요구 사항 및 가격 선호도에 따라 선택하세요.
### Claude API
* 최신 모델 및 기능에 대한 **직접 접근**
* **Anthropic 청구 및 지원**
* **적합한 경우:** 새로운 통합, 전체 기능 접근, Anthropic과의 직접적인 관계
### 클라우드 플랫폼 API
AWS, Google Cloud 또는 Microsoft Azure를 통해 Claude에 접근합니다:
* 클라우드 제공업체 청구 및 IAM과 **통합**
* **기능 가용성은 플랫폼에 따라 다릅니다:** Anthropic이 운영하는 플랫폼에는 [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)가 포함됩니다. 파트너가 운영하는 플랫폼에는 Amazon Bedrock과 Google Cloud가 포함됩니다. 기능 가용성 및 시기는 각 플랫폼의 페이지를 참조하세요.
* **적합한 경우:** 기존 클라우드 약정, 특정 규정 준수 요구 사항, 통합된 클라우드 청구
| 플랫폼 | 제공업체 | 문서 |
| ---------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| Agent Platform | Google Cloud | [Google Cloud의 Claude](https://platform.claude.com/docs/ko/build-with-claude/claude-on-vertex-ai) |
| Amazon Bedrock | AWS | [Amazon Bedrock의 Claude](https://platform.claude.com/docs/ko/build-with-claude/claude-in-amazon-bedrock) |
| Claude Platform on AWS | AWS (Anthropic 운영) | [Claude Platform on AWS](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws) |
| Microsoft Foundry | Microsoft Azure (Anthropic 운영) | [Microsoft Foundry의 Claude](https://platform.claude.com/docs/ko/build-with-claude/claude-in-microsoft-foundry) |
Claude Managed Agents는 직접적인 Claude API와 [Claude Platform on AWS](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws)를 통해 사용할 수 있습니다. 플랫폼 전반의 기능 가용성은 [기능 개요](https://platform.claude.com/docs/ko/build-with-claude/overview)를 참조하세요.
## 요청 및 응답 형식
### 요청 크기 제한
| 엔드포인트 | 최대 요청 크기 |
| --------------------------------------------------------------------------------------------- | -------- |
| Messages, Token Counting | 32 MB |
| [Message Batches API](https://platform.claude.com/docs/ko/build-with-claude/batch-processing) | 256 MB |
| [Files API](https://platform.claude.com/docs/ko/build-with-claude/files) | 500 MB |
| Sessions, Agents, Environments | 32 MB |
이러한 제한을 초과하면 413 `request_too_large` 오류가 발생합니다.
파트너가 운영하는 플랫폼에는 자체 요청 크기 제한이 있습니다: Bedrock은 요청을 20 MB로 제한하고, Google Cloud는 요청을 30 MB로 제한합니다. Claude Platform on AWS는 직접적인 Claude API와 동일한 제한을 사용합니다. 현재 값은 플랫폼 문서를 참조하세요.
### 응답 헤더
Claude API는 응답에 다음 헤더를 포함합니다:
| 헤더 | 설명 |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `request-id` | `req_018EeWyXxfu5pfWkrYcMdjWG`와 같은 요청에 대한 전역적으로 고유한 식별자입니다. 특정 요청에 대해 지원팀에 문의할 때 포함하세요. [요청 ID](https://platform.claude.com/docs/ko/api/errors#request-id)를 참조하세요. |
| `anthropic-organization-id` | 요청에 사용된 API 키 또는 액세스 토큰이 속한 조직의 ID입니다. |
| `anthropic-workspace-id` | API 키 또는 액세스 토큰이 확인된 [워크스페이스](https://platform.claude.com/docs/ko/manage-claude/workspaces)의 `wrkspc_` 접두사가 붙은 ID입니다 (예: `wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ`). 조직의 기본 워크스페이스인 경우에도 포함됩니다. 자격 증명이 워크스페이스로 확인되지 않거나(예: Admin API 요청) 인증이 완료되기 전에 요청이 실패하는 경우에는 없습니다. [API 응답 뒤의 워크스페이스 식별하기](https://platform.claude.com/docs/ko/manage-claude/workspaces#identify-the-workspace-behind-an-api-response)를 참조하세요. |
속도 제한 헤더는 속도 제한의 [응답 헤더](https://platform.claude.com/docs/ko/api/rate-limits#response-headers)를 참조하세요. 각 SDK에서 이름으로 응답 헤더를 읽는 예제는 [API 응답 뒤의 워크스페이스 식별하기](https://platform.claude.com/docs/ko/manage-claude/workspaces#identify-the-workspace-behind-an-api-response)를 참조하세요.
Claude Platform on AWS는 표준 `request-id` 헤더와 함께 AWS 요청 ID(`x-amzn-requestid`)를 추가합니다. 이중 ID 처리 패턴은 [요청 ID](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#request-ids)를 참조하세요.
## 페이지네이션
목록 엔드포인트는 결과를 페이지 단위로 반환합니다. 대부분의 최신 목록 엔드포인트는 이 섹션에서 설명하는 `page` 및 `next_page` 커서 방식을 사용합니다. 일부는 다른 방식을 사용합니다. 이 섹션 끝의 참고 사항을 확인하세요. `limit` 쿼리 매개변수를 사용하여 페이지 크기를 제어하고 `page` 쿼리 매개변수를 사용하여 인접한 페이지를 가져옵니다. 각 응답에는 페이지 간 탐색을 위한 커서 필드와 함께 `data` 배열이 포함됩니다.
| 이름 | 위치 | 설명 |
| ----------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| `limit` | 쿼리 매개변수 | 페이지당 반환할 최대 항목 수입니다. |
| `page` | 쿼리 매개변수 | 이전 응답의 불투명 커서입니다. 인접한 페이지를 가져오려면 여기에 `next_page` 또는 `prev_page` 값을 전달하세요. |
| `order` | 쿼리 매개변수 | 정렬을 지원하는 목록 엔드포인트에서 결과의 정렬 방향(`asc` 또는 `desc`)입니다. `page` 커서는 생성될 때의 `order`와 함께만 유효합니다. |
| `next_page` | 응답 필드 | 다음 페이지의 커서이거나, 더 이상 결과가 없는 경우 `null`입니다. |
| `prev_page` | 응답 필드 | 역방향 페이지네이션을 지원하는 엔드포인트(현재 `GET /v1/sessions`)에서 이전 페이지의 커서이거나, 첫 페이지에 있는 경우 `null`입니다. 다른 목록 엔드포인트는 이 필드를 생략합니다. |
이전 페이지로 돌아가려면 `prev_page`를 `page` 매개변수로 전달하세요. 첫 페이지에 있을 때 `prev_page`는 `null`입니다. 모든 목록 엔드포인트가 `prev_page`를 지원하는 것은 아닙니다. `GET /v1/sessions`만 `prev_page`를 반환합니다. 역방향 페이지네이션을 지원하지 않는 목록 엔드포인트에서는 이 필드가 `null`이 아니라 응답에서 아예 없습니다. 요청 과정에 대한 안내는 [세션 나열하기](https://platform.claude.com/docs/ko/managed-agents/session-operations#listing-sessions)를 참조하세요.
SDK는 `next_page`를 자동으로 따라가는 자동 페이지네이션 이터레이터를 제공합니다. 예를 들어, `for session in client.beta.sessions.list()` (typescript: `for await (const session of client.beta.sessions.list())`; go: `client.Beta.Sessions.ListAutoPaging()`; java: `client.beta().sessions().list().autoPager()`; csharp: `(await client.Beta.Sessions.List()).Paginate()`; php: `$client->beta->sessions->list()->pagingEachItem()`; ruby: `client.beta.sessions.list.auto_paging_each`)는 모든 세션을 순회합니다. SDK 자동 페이지네이션은 순방향으로만 동작합니다. 이전 페이지로 돌아가려면 응답에서 `prev_page`를 읽어 직접 `page` 매개변수로 다시 전달하세요. 자세한 내용은 [클라이언트 SDK](https://platform.claude.com/docs/ko/cli-sdks-libraries/overview)를 참조하세요.
일부 목록 엔드포인트는 다른 커서 방식을 사용합니다. [Message Batches API](https://platform.claude.com/docs/ko/build-with-claude/batch-processing), [Models API](https://platform.claude.com/docs/ko/api/models/list) 및 여러 [Admin API](https://platform.claude.com/docs/ko/manage-claude/admin-api) 엔드포인트는 `page` 대신 `after_id` 및 `before_id` 쿼리 매개변수를 사용합니다. 이들의 응답은 `next_page` 대신 `has_more`, `first_id`, `last_id`를 반환합니다. 정확한 페이지네이션 필드는 각 엔드포인트의 참조 페이지를 확인하세요.
## 속도 제한 및 가용성
### 속도 제한
API는 오용을 방지하고 용량을 관리하기 위해 속도 제한과 지출 제한을 적용합니다. 제한은 사용 등급으로 구성됩니다. 조직은 자동으로 등급에 배치되며 시간이 지남에 따라 더 높은 등급으로 이동할 수 있습니다. 각 등급에는 다음이 있습니다:
* **지출 제한**: API 사용에 대한 최대 월간 비용
* **속도 제한**: 분당 최대 요청 수(RPM) 및 분당 토큰 수(TPM)
Console의 [속도 제한](https://platform.claude.com/usage/limits) 페이지에서 속도 제한을, [청구](https://platform.claude.com/settings/billing) 페이지에서 지출 제한을 확인할 수 있습니다. 더 높은 속도 제한이나 더 높은 월간 지출 한도가 필요하면 속도 제한 페이지에서 **등급 상향 요청**을 사용하세요.
제한, 등급 및 속도 제한에 사용되는 토큰 버킷 알고리즘에 대한 자세한 내용은 [속도 제한](https://platform.claude.com/docs/ko/api/rate-limits)을 참조하세요.
### 가용성
Claude API는 전 세계 [많은 국가 및 지역](https://platform.claude.com/docs/ko/api/supported-regions)에서 사용할 수 있습니다. 지원되는 지역 페이지에서 귀하의 위치에서의 가용성을 확인하세요.
## 다음 단계
직접적인 모델 상호작용을 위한 전체 API 사양
Agents, Sessions 및 Environments 엔드포인트
Python, TypeScript, C#, Go, Java, PHP 및 Ruby
사용 등급, 더 높은 제한 요청 및 토큰 버킷 알고리즘