Claude code api 요약 -anthropic-beta

 

Claude code api 를 부를때 v1/message 를 통해서 response를 받는거 외 다른 API 내용에 대해서 정리해보자.

 

 

공식 문서 

https://platform.claude.com/docs/en/api/overview

API Overview

 

 

Claude API 엔드포인트 정리 (GA 기준)

엔드포인트메서드용도설명

/v1/messages	POST	기본 대화	Claude 모델에 메시지를 보내고 응답을 받는 핵심 API
/v1/messages/batches	POST	대량 요청 처리	여러 요청을 비동기로 처리, 비용 절감 및 처리량 최적화
/v1/messages/count_tokens	POST	토큰 계산	요청 전에 토큰 수를 계산해 비용 및 응답 길이 예측
/v1/models	GET	모델 조회	사용 가능한 Claude 모델 목록 및 메타 정보 조회

핵심 흐름 요약

1. 일반적인 사용
   /v1/messages 호출
   prompt 전달
   응답 수신

1. 비용/성능 최적화
   /v1/messages/count_tokens로 사전 계산
   /v1/messages/batches로 대량 처리

1. 환경 설정
   /v1/models로 모델 선택

 구조

• 메시지 생성 → /v1/messages
• 토큰 관리 → /v1/messages/count_tokens
• 대량 처리 → /v1/messages/batches
• 모델 관리 → /v1/models

 

Claude API (Beta) 엔드포인트 정리

※ anthropic-beta 헤더 필요

---

1. Files API (files-api-2025-04-14)

엔드포인트메서드용도설명

/v1/files	POST	파일 업로드	PDF, 이미지 등 파일을 업로드
/v1/files	GET	파일 목록 조회	업로드된 파일 리스트 조회
/v1/files/{id}	GET	파일 단건 조회	특정 파일 정보 조회

설명

• 파일을 한 번 업로드 후 여러 API 호출에서 재사용 가능
• 매 요청마다 base64로 이미지 전달할 필요 없음
• 비용 및 응답 속도 최적화에 유리
• PDF, 이미지 기반 처리(예: Vision)에 적합

---

2. Skills API (skills-2025-10-02)

엔드포인트메서드용도설명

/v1/skills	POST	스킬 생성	도메인 특화 지식 정의
/v1/skills	GET	스킬 목록 조회	생성된 스킬 리스트 조회

설명

• Agent에 붙이는 재사용 가능한 지식 단위
• tools와 다르게 “지식/컨텍스트 캡슐” 역할
• 필요할 때만 컨텍스트를 주입하는 구조 (progressive disclosure)
• 예: 특정 도메인 분석 규칙, 포맷 처리 로직

---

3. Agents API (managed-agents-2026-04-01)

엔드포인트메서드용도설명

/v1/agents	POST	Agent 생성	Agent 정의
/v1/agents	GET	Agent 목록 조회	Agent 리스트 조회
/v1/agents/{id}	PUT	Agent 업데이트	수정 시 버전 자동 증가
/v1/agents/{id}/archive	POST	Agent 아카이브	비활성화 처리

설명

• model, system prompt, tools, MCP, skills 등을 하나로 묶은 설정 단위
• Agent를 ID로 재사용 가능
• 변경 시 버전(v1, v2…) 자동 관리

---

4. Sessions API (managed-agents-2026-04-01)

엔드포인트메서드용도설명

/v1/sessions	POST	세션 생성	agent_id, environment_id 필요
/v1/sessions/{id}	GET	세션 조회	상태 및 정보 조회
/v1/sessions/{id}/events	POST	이벤트 전송	메시지/명령 전달
/v1/sessions/{id}/stream	GET	스트리밍 응답	실시간 응답 수신

설명

• Agent를 실행하는 stateful 인스턴스
• 대화 히스토리 자동 유지
• 상태 흐름: idle → running → terminated

---

5. Environments API (managed-agents-2026-04-01)

엔드포인트메서드용도설명

/v1/environments	POST	환경 생성	실행 환경 정의
/v1/environments	GET	환경 목록 조회	환경 리스트 조회

설명

• Session이 실행될 컨테이너 템플릿 정의
• 파일 시스템, 실행 환경 등을 설정

---

전체 흐름 요약

Files API        → 파일 업로드 및 재사용
Skills API       → 도메인 지식 정의
Agents API       → Agent 구성 및 버전 관리
Environments API → 실행 환경 정의
Sessions API     → Agent 실행 (stateful)

 

---

정리

• 단순 대화 → /v1/messages로 충분
• 파일 반복 처리 → Files API 도입 시 비용 절감
• 복잡한 Agent 시스템 → Agents + Sessions 구조 필요