Anthropic Messages API는 Claude에 프롬프트를 보내기 위한 주요 HTTP 인터페이스입니다. 핵심 엔드포인트는 POST /v1/messages이며, 모델, 유형별 메시지 콘텐츠 블록 목록, 토큰 제한을 제공하면 하나 이상의 출력 블록을 포함하는 어시스턴트 메시지를 받습니다.
이 가이드는 Anthropic API 문서를 구현 체크리스트로 전환합니다. 요청 계약, 다중 턴 상태, 스트리밍, 비전, Files API, 도구 사용, 그리고 에이전트 백엔드가 Anthropic 네이티브와 OpenAI 호환 모델 공급자를 모두 지원해야 할 때의 선택지를 다룹니다.
Messages API 엔드포인트 및 필수 헤더
Anthropic의 네이티브 Messages API는 다음 엔드포인트를 사용합니다:
POST https://api.anthropic.com/v1/messages
직접 HTTP 요청에는 일반적으로 다음 헤더가 포함됩니다:
| 헤더 | 목적 |
|---|---|
x-api-key |
Anthropic 계정 인증 |
anthropic-version |
문서화된 API 버전 계약 선택 |
content-type: application/json |
JSON 요청 본문 선언 |
API 버전 헤더는 모델 버전이 아닙니다. HTTP API 동작을 제어하며, model 필드는 추론에 사용되는 Claude 모델을 선택합니다. 두 값을 애플리케이션 코드 전체에 흩뿌리지 않고 구성에 유지하세요.
요청 및 응답 구조
기본 요청은 세 개의 필드를 포함합니다:
{
"model": "YOUR_CLAUDE_MODEL_ID",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": "멱등성 키를 두 문단으로 설명해 주세요."
}
]
}
응답은 단순 문자열이 아닌 어시스턴트 메시지입니다. content 속성은 유형별 블록의 배열이므로, 프로덕션 코드는 각 블록의 type을 검사한 후 필드를 읽어야 합니다.
{
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "멱등성 키는..."
}
],
"stop_reason": "end_turn",
"usage": {
"input_tokens": 18,
"output_tokens": 126
}
}
이 블록 기반 설계는 이미지나 도구를 추가할 때 중요해집니다. 단일 어시스턴트 턴에는 텍스트와 도구 요청이 포함될 수 있으며, 사용자 턴에는 텍스트와 함께 이미지 또는 문서 블록이 포함될 수 있습니다.
최소 curl 요청
자격 증명을 환경 변수에 저장하고 현재 Anthropic 계정에서 사용 가능한 모델 ID를 사용하세요:
export ANTHROPIC_API_KEY="your-api-key"
export ANTHROPIC_MODEL="your-claude-model-id"
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data '{
"model": "'"$ANTHROPIC_MODEL"'",
"max_tokens": 512,
"messages": [
{
"role": "user",
"content": "API 지연 시간을 줄이는 실용적인 방법 세 가지를 알려주세요."
}
]
}'
오래된 튜토리얼에서 복사한 모델 이름을 하드코딩하지 마세요. 모델 가용성과 별칭은 변경될 수 있으므로, 배포 구성은 공급자의 최신 모델 문서 또는 콘솔에서 확인된 모델 ID를 사용해야 합니다.
Anthropic SDK를 사용한 Python 사용법
공식 Python SDK는 인증 헤더를 처리하고 응답을 유형화된 객체로 변환합니다:
import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
message = client.messages.create(
model=os.environ["ANTHROPIC_MODEL"],
max_tokens=512,
messages=[
{
"role": "user",
"content": "UUID 문자열을 검증하는 Python 함수를 작성해 주세요.",
}
],
)
for block in message.content:
if block.type == "text":
print(block.text)
콘텐츠 블록을 반복하는 것이 message.content[0]이 항상 텍스트라고 가정하는 것보다 안전합니다. 에이전트 애플리케이션은 도구 사용 블록을 받을 수 있으며, 멀티모달 기능은 대화에 다른 블록 유형을 추가할 수 있습니다.
다중 턴 대화 및 시스템 프롬프트
Messages API는 상태 비저장(stateless)입니다. 애플리케이션은 관련 대화 기록을 각 요청마다 다시 전송합니다:
{
"model": "YOUR_CLAUDE_MODEL_ID",
"max_tokens": 512,
"system": "당신은 간결한 API 문서 도우미입니다.",
"messages": [
{"role": "user", "content": "HTTP 429는 무엇을 의미하나요?"},
{"role": "assistant", "content": "속도 제한을 나타냅니다."},
{"role": "user", "content": "클라이언트는 어떻게 재시도해야 하나요?"}
]
}
Anthropic은 시스템 지시문을 role: "system" 메시지가 아닌 최상위 system 필드에 배치합니다. 이는 OpenAI 호환 스키마에서 요청을 변환할 때 고려해야 할 중요한 차이점 중 하나입니다.
장기 실행 세션의 경우 무제한 대화록을 재전송하지 마세요. 최근 턴을 유지하고, 작업에 여전히 영향을 미치는 결정과 도구 결과를 보존하며, 프롬프트가 선택한 모델의 컨텍스트 한도에 가까워지기 전에 이전 컨텍스트를 요약하세요.
스트리밍 응답
인터페이스가 점진적으로 출력을 표시해야 할 때 stream: true를 설정하세요:
import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
with client.messages.stream(
model=os.environ["ANTHROPIC_MODEL"],
max_tokens=1024,
messages=[
{"role": "user", "content": "데이터베이스 커넥션 풀링에 대해 설명해 주세요."}
],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
스트리밍은 인지된 지연 시간을 개선하지만 상태 관리 작업이 추가됩니다. 애플리케이션은 조기 종료되는 연결, 부분 텍스트, 이벤트 순서, 최종 사용량 메타데이터를 처리해야 합니다. 도구 사용 에이전트의 경우, 구문 분석 또는 실행하기 전에 완전한 도구 입력 블록을 버퍼링하세요.
Claude Vision API 요청
Claude Vision API는 동일한 Messages 엔드포인트를 사용합니다. 관련 텍스트 질문 앞에 이미지 콘텐츠 블록을 추가하세요. 이미지는 지원되는 base64 데이터 또는 현재 비전 문서에 설명된 허용된 소스 유형으로 제공할 수 있습니다.
import base64
import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
with open("architecture.png", "rb") as image_file:
image_data = base64.b64encode(image_file.read()).decode("utf-8")
message = client.messages.create(
model=os.environ["ANTHROPIC_VISION_MODEL"],
max_tokens=700,
messages=[
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": image_data,
},
},
{
"type": "text",
"text": "이 아키텍처 다이어그램에서 두 가지 신뢰성 위험을 식별해 주세요.",
},
],
}
],
)
전송하기 전에 과도하게 큰 이미지 크기를 조정하세요. 큰 이미지는 전송 시간과 토큰 사용량을 증가시키면서도 반드시 답변 품질을 향상시키지는 않습니다. 또한 MIME 유형을 확인하세요. JPEG 데이터를 PNG로 선언하는 것은 요청 거부의 일반적인 원인입니다.
Anthropic Files API 사용법
Anthropic Files API는 파일을 한 번 업로드하고 이후 Messages API 호출에서 인코딩 및 반복 전송 없이 참조할 수 있게 할 때 유용합니다. 정확한 가용성, 지원되는 파일 유형 및 요청 필드는 기능 상태에 따라 다를 수 있으므로, 프로덕션에서 의존하기 전에 현재 Files API 문서를 확인하세요.
일반적인 통합은 두 단계로 이루어집니다:
- 파일을 업로드하고 반환된 파일 식별자를 애플리케이션의 문서 레코드와 함께 유지합니다.
- 메시지를 생성할 때 지원되는 콘텐츠 블록에서 해당 식별자를 참조합니다.
파일 ID를 공급자별 리소스로 취급하세요. 각 ID를 생성한 공급자와 계정을 기록하고, 자체 접근 제어를 적용하며, 삭제 정책을 정의하세요. 파일 식별자는 권한 확인 없이 신뢰할 수 없는 사용자로부터 직접 받아들여서는 안 됩니다.
간헐적인 작은 이미지의 경우 base64가 간단합니다. 많은 요청에 걸쳐 사용되는 문서의 경우, 공급자 파일 리소스가 반복 업로드를 줄일 수 있습니다. 애플리케이션이 여러 공급자에서 작동해야 하는 경우, 원본 객체를 자체 스토리지에 유지하고 공급자별 파일 ID를 캐시로 생성하세요.
에이전트 백엔드를 위한 도구 사용
도구를 사용하면 Claude가 애플리케이션 정의 함수를 요청할 수 있습니다. 백엔드는 각 도구를 이름, 목적 및 JSON Schema 입력 계약으로 설명합니다. 그러면 모델은 작업을 실행한 척하는 대신 tool_use 블록을 반환할 수 있습니다.
{
"name": "get_order_status",
"description": "고객 주문의 현재 상태를 조회합니다.",
"input_schema": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "고객에게 표시되는 주문 식별자."
}
},
"required": ["order_id"]
}
}
안전한 실행 루프는 다음과 같습니다:
- 메시지와 도구 정의를 모델로 보냅니다.
tool_use콘텐츠 블록을 감지합니다.- 입력을 스키마 및 권한 부여 규칙에 대해 검증합니다.
- 통제된 환경에서 도구를 실행합니다.
- 다음 사용자 턴에서 일치하는
tool_result블록을 반환합니다. - 모델이 정상적인 답변을 생성하거나 루프 제한에 도달할 때까지 계속합니다.
도구 인수를 신뢰할 수 있는 셸, SQL 또는 파일 경로로 절대 실행하지 마세요. 코딩 에이전트의 경우, 생성된 명령을 Novita Agent Sandbox와 같은 격리된 환경에서 명시적인 시간, 네트워크, 파일 시스템 및 리소스 제한과 함께 실행하세요.
Anthropic 네이티브 vs OpenAI 호환 요청
Anthropic 네이티브와 OpenAI 호환 API는 동일한 일반 문제를 해결하지만, 와이어 형식은 동일하지 않습니다.
| 관심사 | Anthropic Messages API | OpenAI 호환 채팅 API |
|---|---|---|
| 일반 엔드포인트 | /v1/messages |
/v1/chat/completions |
| 시스템 지시문 | 최상위 system 필드 |
일반적으로 system 또는 developer 메시지 |
| 출력 표현 | 유형화된 콘텐츠 블록 | 일반적으로 choices[].message |
| 도구 요청 | tool_use 블록 |
일반적으로 tool_calls |
| 도구 결과 | tool_result 콘텐츠 블록 |
일반적으로 tool 역할 메시지 |
OpenAI 호환 엔드포인트는 애플리케이션이 이미 OpenAI SDK를 사용하거나 최소한의 전송 변경으로 오픈소스 모델 간에 전환해야 할 때 유용합니다. Novita AI는 OpenAI 호환 LLM API를 제공하므로, 동일한 클라이언트 구조로 기본 URL과 모델 구성을 변경하여 여러 사용 가능한 모델을 대상으로 지정할 수 있습니다.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["NOVITA_API_KEY"],
base_url="https://api.novita.ai/v3/openai",
)
response = client.chat.completions.create(
model=os.environ["NOVITA_MODEL"],
messages=[
{
"role": "user",
"content": "이 재시도 전략의 실패 모드를 검토해 주세요.",
}
],
)
print(response.choices[0].message.content)
이것은 모든 Anthropic 기능의 드롭인 변환이 아닙니다. 애플리케이션이 Anthropic 특정 콘텐츠 블록, 도구 의미론, 인용 또는 베타 기능에 의존하는 경우, Anthropic 네이티브 어댑터를 유지하세요. 공통 요청 모델에 맞는 워크로드에는 공유 OpenAI 호환 경로를 사용하세요.
공급자 중립적인 에이전트 백엔드 구축
공급자 중립적인 백엔드는 모든 공급자가 동일한 척하지 않고 애플리케이션 개념을 정규화해야 합니다. 실용적인 설계는 네 개의 계층을 가집니다:
- 대화 모델: 역할, 텍스트, 이미지, 도구 호출 및 도구 결과를 내부 스키마에 저장합니다.
- 공급자 어댑터: 내부 스키마를 Anthropic Messages 또는 OpenAI 호환 페이로드로 변환합니다.
- 기능 레지스트리: 선택한 모델이 비전, 도구, 구조화된 출력 또는 기타 필요한 동작을 지원하는지 추적합니다.
- 실행 계층: 추론 공급자와 별도로 도구와 코드를 실행합니다.
이러한 분리를 통해 팀은 Anthropic 네이티브 동작이 중요한 곳에서 Claude를 사용하면서도 호환되는 워크로드를 Novita AI를 통해 오픈소스 모델로 라우팅할 수 있습니다. 오픈소스 경로는 비용 제어, 모델 실험, 데이터 위치 요구 사항 또는 단일 공급자 종속성 회피에 유용할 수 있습니다. 두 모델이 모두 채팅 메시지를 수락한다고 해서 상호 교환 가능하다고 가정하지 말고, 자체 작업에서 출력 품질과 도구 신뢰성을 테스트하세요.
에이전트 워크로드의 경우 실행 계층에 동등한 주의를 기울여야 합니다. 모델 전환은 안전하지 않은 명령으로부터 인프라를 보호하지 않습니다. 격리된 샌드박스를 사용하고, 도구 허용 목록을 적용하며, 반복 횟수에 상한을 두고, 비밀 정보를 제거한 상태에서 각 모델 결정과 도구 결과를 기록하세요.
일반적인 오류 및 디버깅
400 Bad Request
JSON 형태, 콘텐츠 블록 유형, 필수 필드 및 선택한 모델이 요청된 기능을 지원하는지 확인하세요. 공급자의 요청 ID와 구조화된 오류 본문을 기록하되, 자격 증명과 base64 파일 데이터는 삭제하세요.
401 인증 오류
API 키가 런타임 환경에 존재하고 의도된 공급자에 속하는지 확인하세요. Anthropic은 직접 HTTP 요청에 x-api-key를 사용합니다. OpenAI 호환 클라이언트는 일반적으로 베어러 토큰을 자동으로 전송합니다.
404 모델 또는 리소스를 찾을 수 없음
모델 ID를 현재 공급자 문서 또는 콘솔과 대조하여 확인하세요. Files API 리소스의 경우 파일이 요청에 사용된 동일한 계정 및 환경에 속하는지도 확인하세요.
429 속도 제한
지수 백오프와 지터(jitter)를 사용하여 재시도하되, 시도 횟수에 상한을 두세요. 백그라운드 작업을 대기열에 넣고, 공급자별 동시성을 제한하며, 동일한 간격으로 모든 실패한 요청을 즉시 재시도하지 마세요.
컨텍스트 또는 토큰 제한 오류
대화 기록, 이미지 크기, 파일 콘텐츠 또는 요청된 출력 길이를 줄이세요. 시스템 지시문, 도구 스키마, 이전 도구 결과 및 멀티모달 콘텐츠를 포함한 전체 요청을 계산하세요.
추천 문서
- 코딩 에이전트란 무엇인가? 아키텍처, 도구 및 실행 루프
- MCP란 무엇인가? 개발자를 위한 모델 컨텍스트 프로토콜 가이드
- 오픈소스 LLM 가이드 2026: 모델, 트레이드오프 및 배포
구현 체크리스트
- API 키, 모델 ID, 기본 URL 및 API 버전을 런타임 구성에 유지하세요.
- 단일 텍스트 문자열을 가정하는 대신 유형화된 콘텐츠 블록을 구문 분석하세요.
- 각 상태 비저장 요청을 재구성하기에 충분한 대화 상태를 저장하세요.
- 도구 입력을 검증하고 모델 프로세스 외부에서 실행하세요.
- 시간 초과, 재시도 제한, 요청 ID 및 삭제된 관찰 가능성을 추가하세요.
- 가격이나 이름이 아닌 모델 기능에 따라 공급자 라우팅을 결정하세요.
- 배포 전에 모델 ID, 기능 상태, 제한 및 가격을 다시 확인하세요.
Messages API는 HTTP 계층에서 간단합니다. 더 어려운 엔지니어링 작업은 애플리케이션이 스트리밍, 멀티모달 입력, 도구, 영구 파일 또는 여러 모델 공급자를 추가할 때 나타납니다. 이러한 우려 사항을 명시적 어댑터 뒤에 유지하면 에이전트 백엔드가 비즈니스 로직을 하나의 요청 형식에 묶지 않고도 진화할 수 있습니다.
FAQ
Anthropic Messages API 엔드포인트는 무엇인가요?
네이티브 엔드포인트는 POST https://api.anthropic.com/v1/messages입니다. 요청에는 인증, Anthropic API 버전 헤더, 모델 ID, 토큰 제한 및 메시지 배열이 필요합니다.
Anthropic Messages API는 OpenAI 호환인가요?
아니요. 개념은 겹치지만 시스템 프롬프트, 콘텐츠 블록, 응답 객체 및 도구 사용 메시지가 다릅니다. 하나의 애플리케이션이 두 형식을 모두 지원해야 하는 경우 공급자 어댑터를 사용하세요.
Claude Vision API는 별도의 엔드포인트를 사용하나요?
아니요. 비전 요청은 이미지와 텍스트 콘텐츠 블록과 함께 Messages API를 사용합니다. 선택한 Claude 모델은 이미지 입력을 지원해야 합니다.
Anthropic Files API는 언제 사용해야 하나요?
지원되는 파일을 여러 요청에서 참조해야 하고 반복적인 base64 업로드가 낭비일 때 사용하세요. 공급자 파일 ID는 계정별 리소스이므로 자체 소스 파일과 권한 부여 레코드를 유지하세요.
Claude Code는 사용자 정의 API 백엔드를 사용할 수 있나요?
Claude Code 통합은 현재 Claude Code 릴리스에서 지원하는 인증 및 공급자 구성에 따라 다릅니다. OpenAI 호환 엔드포인트가 Anthropic의 Messages API를 구현한다고 가정하지 마세요. 사용자 정의 에이전트의 경우, 서로 다른 프로토콜을 동일하게 보이게 만드는 것보다 공급자 중립적인 어댑터가 일반적으로 더 명확합니다.
Novita AI를 통해 오픈소스 모델을 선택해야 하는 경우는 언제인가요?
OpenAI 호환 모델 전환, 오픈 모델 실험 또는 호환 워크로드에 대한 두 번째 공급자를 원할 때 고려하세요. Claude 특정 API 동작이 필요한 기능에는 Anthropic 네이티브 요청을 유지하고, 자체 프롬프트와 도구에서 두 경로를 모두 평가하세요.
