---
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 참조 페이지를 살펴보세요. 베타 기능에 접근하려면 [베타 헤더](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 버전 (예: `2026-10-21`) | 예 |
| `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, CLI 및 라이브러리](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), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/ko/build-with-claude/claude-models-on-google-cloud/anthropic-managed)와 [Microsoft Foundry](https://platform.claude.com/docs/ko/build-with-claude/claude-in-microsoft-foundry)가 포함됩니다. 파트너가 운영하는 플랫폼에는 Claude Models on Google Cloud (Google managed)와 Amazon Bedrock이 포함됩니다. 기능 가용성 및 시기는 각 플랫폼의 페이지를 참조하세요.
* **적합한 경우:** 기존 클라우드 약정, 특정 규정 준수 요구 사항, 통합된 클라우드 청구
| 플랫폼 | 제공업체 | 문서 |
| ------------------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Claude Models on Google Cloud (Google managed) | Google Cloud | [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/ko/build-with-claude/claude-models-on-google-cloud/google-managed) |
| 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) |
| Claude Models on Google Cloud (Anthropic managed) | Google Cloud (Anthropic 운영) | [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/ko/build-with-claude/claude-models-on-google-cloud/anthropic-managed) |
| 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) 및 [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/ko/build-with-claude/claude-models-on-google-cloud/anthropic-managed)를 통해 사용할 수 있습니다. 플랫폼 전반의 기능 가용성은 [기능 개요](https://platform.claude.com/docs/ko/build-with-claude/overview)를 참조하세요.
## 요청 및 응답 형식
### 요청 크기 제한
퍼스트 파티 Claude API는 다음과 같은 요청 크기 제한을 적용합니다:
| 엔드포인트 | 최대 요청 크기 |
| -------------------------------------------------------------------------------------------------------- | -------- |
| Messages, 토큰 카운팅 | 128 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 |
| 세션, 에이전트, 환경 | 32 MB |
이러한 제한을 초과하면 413 `request_too_large` 오류가 발생합니다.
파트너가 운영하는 플랫폼에는 자체 요청 크기 제한이 있습니다. Bedrock은 요청을 20 MB로 제한하고, Claude Models on Google Cloud (Google managed)는 요청을 30 MB로 제한합니다. Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) 및 Microsoft Foundry는 최대 32 MB의 Messages 및 토큰 카운팅 요청을 지원합니다. 최신 값은 해당 플랫폼의 문서를 참조하세요.
### 응답 헤더
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, CLI 및 라이브러리](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)
속도 제한은 [Claude Console의 속도 제한](https://platform.claude.com/usage/limits)에서, 지출 한도는 Console의 [결제](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 사양
에이전트, 세션 및 환경 엔드포인트
Python, TypeScript, C#, Go, Java, PHP 및 Ruby
사용 등급, 더 높은 제한 요청 및 토큰 버킷 알고리즘