Skip to main content
POST
두 API를 혼용하지 마세요: /v1/*는 추론 API(본 문서, 업스트림 그대로 투과·래퍼 없음); /api/*는 관리 API(잔액/로그 조회 등, 응답은 {success, message, data}). 다른 문서에서 /v1/messages{code, data}를 반환한다고 적혀 있어도 본 문서를 기준으로 하세요.

인증

인증은 다음 두 방식을 지원하며, 둘 중 하나를 사용합니다:
string
Anthropic 스타일 인증 헤더API 키 관리 페이지를 방문하여 API 키를 받으세요
string
Bearer Token 인증(x-api-key와 택일)
string
API 버전(선택. 생략해도 정상 응답)이후 Anthropic 공식 엔드포인트로 이전하기 쉽도록 포함을 권장합니다:예: 2025-10-01

요청 본문

string
기본값:"claude-sonnet-4-6"
필수
Model name
  • claude-opus-4-8 - Claude Opus 4.8 flagship model
  • claude-opus-4-7 - Claude Opus 4.7 flagship model
  • claude-opus-4-6 - Claude Opus 4.6 flagship model
  • claude-sonnet-4-6 - Claude Sonnet 4.6 balanced version
  • claude-opus-4-5-20251101 - Claude Opus 4.5 model
array
필수
메시지 목록모델이 다음 응답을 생성하기 위한 메시지 배열입니다. 각 메시지는 rolecontent 두 필드를 포함합니다.💡 빠른 입력 (Try it 영역):
  1. ”+ Add an item”을 클릭하여 메시지 추가
  2. role 입력: user (사용자 메시지) 또는 assistant (AI 응답, 다중 턴용)
  3. content 입력: 하고 싶은 말
단일 사용자 메시지:
다중 턴 대화:
미리 채워진 어시스턴트 응답:
integer
필수
생성할 최대 토큰 수(필수, Anthropic 공식과 동일)중지하기 전에 생성할 최대 토큰 수입니다. 모델이 이 제한에 도달하기 전에 중지될 수 있습니다.모델마다 최대값이 다릅니다. 최소값: 1
object
Extended thinking 설정활성화하면 응답 contentthinking 블록이 포함될 수 있습니다. 플랫폼의 -thinking 모델 별칭에 의존하기보다 표준 모델명 + 본 파라미터 사용을 권장합니다. 공식 엔드포인트로 코드 변경 없이 이전하기 쉽습니다.다중 턴 대화에서 thinking 블록을 다시 보낼 때는 signature그대로 반환해야 합니다. 그렇지 않으면 업스트림이 거부합니다.
string | array
시스템 프롬프트시스템 프롬프트는 Claude의 역할, 성격, 목표 및 지시사항을 설정합니다.문자열 형식:
구조화된 형식:
number
Temperature 매개변수, 범위 0-1출력의 무작위성을 제어합니다:
  • 낮은 값 (예: 0.2): 더 결정적이고 보수적
  • 높은 값 (예: 0.8): 더 무작위적이고 창의적
기본값: 1.0
number
핵 샘플링 매개변수, 범위 0-1핵 샘플링을 사용합니다. temperature 또는 top_p 중 하나만 사용하는 것을 권장합니다.기본값: 1.0
integer
Top-K 샘플링상위 K개 옵션에서만 샘플링하여 확률이 낮은 “롱테일” 응답을 제거합니다.고급 사용 사례에만 권장됩니다.
boolean
스트리밍 활성화true이면 Server-Sent Events (SSE)를 사용하여 응답을 스트리밍합니다.기본값: false
array
중지 시퀀스모델이 생성을 중지하도록 하는 사용자 정의 텍스트 시퀀스입니다.최대 4개의 시퀀스.예: ["\n\nHuman:", "\n\nAssistant:"]
object
메타데이터요청에 대한 메타데이터 객체입니다.포함:
  • user_id: 사용자 식별자
array
도구 정의모델이 작업을 완료하는 데 사용할 수 있는 도구 목록입니다.함수 도구 예:
지원되는 도구 유형:
  • 사용자 정의 함수 도구
  • 컴퓨터 사용 도구 (computer_20241022)
  • 텍스트 편집기 도구 (text_editor_20241022)
  • Bash 도구 (bash_20241022)
object
도구 선택 전략모델이 도구를 사용하는 방법을 제어합니다:
  • {"type": "auto"}: 자동 결정 (기본값)
  • {"type": "any"}: 도구를 반드시 사용해야 함
  • {"type": "tool", "name": "tool_name"}: 특정 도구 사용

응답

string
고유 메시지 식별자예: "msg_013Zva2CMHLNnXjNJJKqJ2EF"
string
객체 유형항상 "message"
string
역할항상 "assistant"
array
콘텐츠 블록 배열contenttype으로 블록 종류를 구분합니다. 한 번의 응답에 여러 블록이 포함될 수 있습니다(예: thinking 활성화 시 thinking + text 두 블록).text 블록:
tool_use 블록:
caller는 업스트림이 추가한 필드로, 공식 문서에는 아직 수록되지 않았습니다. 파싱 시 무시하면 됩니다.
thinking 블록(요청 본문에 thinking 파라미터가 있을 때 등장):
다중 턴 대화에서 thinking 블록을 다시 보낼 때는 signature그대로 반환해야 합니다. 그렇지 않으면 업스트림이 거부합니다.
content[0]이 텍스트라고 가정하지 마세요. thinking을 켜면 content[0]이 thinking 블록일 수 있습니다. 다음처럼 순회하여 필터링하세요:
string
요청을 처리한 모델예: "claude-sonnet-4-6"
string
중지 이유가능한 값:
  • end_turn: 자연스러운 완료
  • max_tokens: 최대 토큰 도달
  • stop_sequence: 중지 시퀀스 도달
  • tool_use: 도구 호출됨
string | null
트리거된 중지 시퀀스중지 시퀀스로 인해 중지된 경우 해당 시퀀스. 그렇지 않으면 null
object | null
Anthropic의 비교적 새로운 필드. 일반 요청에서는 null
object
토큰 사용량 통계(비스트리밍 전체 구조)

사용 예제

기본 대화

다중 턴 대화

시스템 프롬프트 사용

스트리밍 응답

도구 사용

비전 이해

Base64 이미지

모범 사례

1. 프롬프트 엔지니어링

명확한 역할 정의:
구조화된 출력:

2. 오류 처리

3. 토큰 최적화

4. 응답 미리 채우기

스트리밍 응답 처리

Python 스트리밍

JavaScript 스트리밍

플랫폼 차이 및 연동 주의사항

응답 래퍼 없음

POST /v1/messages 성공 시 Anthropic message 객체를 직접 반환합니다. {code, data} 외부 래퍼는 없습니다. 공식 SDK, Claude Code, Cline 등과 1:1 호환됩니다.

오류 형식(공식과의 유일한 실질적 차이)

Anthropic 공식 대비: 최상위에 "type": "error"가 없고, error.typeinvalid_request_error 등 의미론적 유형이 아니라 항상 apimart_error입니다. 연동 권장: error.type으로 재시도 분기하지 마세요. **HTTP 상태 코드 + error.code**를 사용하세요: 장애 신고 시 error.message 끝의 request id와 응답 헤더 x-oneapi-request-id를 제공하세요.

스트리밍 SSE

요청에 "stream": true를 추가합니다. 이벤트 순서는 공식과 동일합니다: message_startcontent_block_startpingcontent_block_delta(여러 번) → content_block_stopmessage_deltamessage_stop ⚠️ 스트리밍과 비스트리밍의 usage 구조가 다릅니다: message_delta.usage는 보통 4개의 토큰 필드만 있으며 cache_creation, service_tier, inference_geo없습니다. 분리해서 파싱하거나 모두 선택 필드로 처리하세요.

미구현 엔드포인트

POST /v1/messages/count_tokens미구현이며 404를 반환합니다. 공식 SDK의 client.messages.count_tokens()는 실패합니다. 토큰을 미리 추정하려면 로컬에서 계산하거나 응답의 usage.input_tokens를 읽으세요.

알 수 없는 필드는 반드시 무시

본 API는 업스트림을 투과하므로 Anthropic이 언제든 필드를 추가할 수 있습니다(예: stop_details, inference_geo, caller, output_tokens_details). 엄격한 schema를 사용하지 마세요:
  • Go: DisallowUnknownFields() 사용 금지
  • Pydantic: extra="forbid" 사용 금지
  • TypeScript / Zod: .strict() 대신 .passthrough() 사용

모델명 권장

-thinking 접미사가 붙은 동명 모델은 플랫폼 확장 별칭입니다. 권장은 접미사 없는 표준 모델명 + 요청 본문의 thinking 파라미터로, 공식 엔드포인트 이전이 쉽습니다. 요청 본문의 기타 필드는 공식과 동일합니다: model, messages, max_tokens(필수), system, temperature, top_p, top_k, stop_sequences, stream, tools, tool_choice, thinking, metadata. 의미는 Anthropic Messages API를 따릅니다.

중요 참고사항

  1. API 키 보안:
    • API 키를 환경 변수에 저장하세요
    • 소스 코드에 키를 하드코딩하지 마세요
    • 정기적으로 키를 교체하세요
  2. 요청 제한:
    • API 요청 제한에 유의하세요
    • 재시도 메커니즘을 구현하세요(HTTP 상태 코드 기준)
    • 지수 백오프를 사용하세요
  3. 토큰 관리:
    • 토큰 사용량을 모니터링하세요(usage 읽기)
    • 프롬프트 길이를 최적화하세요
    • 적절한 max_tokens 값을 사용하세요
    • thinking 활성화 시 output_tokens에 thinking이 이미 포함됩니다. 중복 과금하지 마세요
  4. 모델 선택:
    • Opus: 복잡한 작업, 깊은 사고 필요
    • Sonnet: 균형 잡힌 성능과 비용
    • Haiku: 빠른 응답, 간단한 작업
  5. 콘텐츠 파싱:
    • content를 순회해 type == "text"를 가져오세요. content[0].text를 고정으로 쓰지 마세요
    • 모델이 Markdown 코드 블록으로 JSON을 감싸 반환하면 모델 출력이며 API 래퍼가 아닙니다(아래 FAQ 참고)
  6. 콘텐츠 필터링:
    • 사용자 입력을 검증하세요
    • 민감한 정보를 필터링하세요
    • 콘텐츠 조정을 구현하세요

FAQ

응답 content의 text가 ```json ... ``` 코드 블록인데, 어떻게 제거하나요?

API 구조 문제가 아닙니다. text 필드에는 모델이 생성한 원본 내용이 들어갑니다. 모델이 JSON을 원한다고 판단하면 Markdown 코드 블록으로 감쌉니다. API는 모델 출력을 바꾸지 않으며, 바꿔서도 안 됩니다. 깨끗한 구조화 데이터를 얻는 올바른 방법은 세 가지입니다(권장 순):
  1. tools로 구조화 출력을 강제——가장 안정적이며, input 필드가 바로 파싱된 객체입니다:
  1. assistant 메시지를 prefill하여 모델이 {부터 이어 쓰게 하기:
  1. system prompt에서 「JSON만 출력하고 Markdown 코드 블록을 붙이지 말 것」을 명시하기.
정규식으로 code fence를 벗기는 방법은 비권장입니다——모델이 가끔 펜스를 생략하면 파싱이 실패합니다.