메인 콘텐츠로 건너뛰기
POST

소개

Claude의 네이티브 메시지 API로, Claude Code와 같은 Anthropic 네이티브 클라이언트에 적합합니다. 이 API는 Anthropic API 사양을 따르며 확장 사고(Extended Thinking), 도구 호출 등 Claude 모델의 고급 기능을 모두 제공합니다.
OpenAI 호환 클라이언트(예: OpenAI SDK)를 사용하는 경우 /v1/chat/completions 엔드포인트 사용을 권장합니다.

인증

string
필수
Bearer 토큰, 예: Bearer sk-xxxxxxxxxx

요청 매개변수

string
필수
Claude 모델 식별자. 지원 모델:
  • claude-fable-5-1 - Claude Fable 5.1 (최신, 최고 성능, 최고 난도의 추론과 장기 Agent 작업에 적합)
  • claude-opus-5-5 - Claude Opus 5.5 (최신 Opus, 복잡한 Agent 및 코딩 작업)
  • claude-sonnet-5-5 - Claude Sonnet 5.5 (최신 Sonnet, 속도와 지능의 균형)
  • claude-haiku-5-5 - Claude Haiku 5.5 (최신 Haiku, 가장 빠르고 비용이 가장 낮음)
  • claude-fable-5 - Claude Fable 5
  • claude-opus-5 - Claude Opus 5
  • claude-sonnet-5 - Claude Sonnet 5
  • claude-opus-4-8 - Claude Opus 4.8
  • claude-opus-4-7 - Claude Opus 4.7
  • claude-opus-4-6 - Claude Opus 4.6
  • claude-sonnet-4-6 - Claude Sonnet 4.6 (균형 잡힌 성능)
  • claude-opus-4-5-20251101 - Claude Opus 4.5
  • claude-haiku-4-5-20251001 - Claude Haiku 4.5
  • claude-sonnet-4-5-20250929 - Claude Sonnet 4.5
  • claude-sonnet-4-20250514 - Claude Sonnet 4
  • 기타 Claude 시리즈 모델
공식 문서: 모델 개요 | 마이그레이션 가이드: Fable 5.1 · Opus 5.5 · Sonnet 5.5 · Haiku 5.5
array
필수
대화 메시지 목록. 각 항목은 role(user / assistant이며, 일부 최신 모델은 system도 지원합니다. 아래 참조)과 content를 포함합니다. content는 문자열 또는 미디어 콘텐츠 배열일 수 있습니다.모델 지원: 모든 Claude 모델에서 지원됩니다.대화 중간의 system 메시지(role: "system")messages 배열 중간에 {"role": "system", "content": "..."}를 삽입하면 대화 도중에 운영자 지시(예: 모드 전환, 상태 주입)를 추가할 수 있으며, 이미 캐시된 앞부분의 대화 프리픽스를 무효화하지 않습니다. 최상위 system을 수정하는 방식보다 캐시를 더 아낄 수 있고 프롬프트 인젝션에도 덜 취약합니다. 정식 출시되었으며 beta 요청 헤더는 필요하지 않습니다. 공식 지원 플랫폼은 Claude API, Amazon Bedrock, Google Cloud입니다. 공식 문서: Mid-conversation system messages위치 규칙(지원되는 모델에서도 위반하면 400을 반환합니다):
  • messages[0]이 될 수 없습니다.
  • 반드시 user 메시지 바로 뒤(또는 서버 도구 호출로 끝나는 assistant 메시지 바로 뒤)에 와야 합니다.
  • 배열의 마지막 항목이거나, 바로 뒤에 assistant 메시지가 와야 합니다.
  • assistant의 tool_use와 대응하는 tool_result 사이에 삽입할 수 없습니다(Agent 루프에서는 tool_result를 담은 user 메시지 뒤에 둘 수 있습니다).
최상위 system 필드는 모든 모델에서 정상적으로 사용할 수 있습니다. role: "system" 메시지는 이를 보완하는 용도로, 멀티턴 대화 도중 지시를 추가해야 하는 경우에 적합합니다. /v1/chat/completions(OpenAI 호환 형식)로 전달한 system 메시지는 Claude의 최상위 system 필드로 병합되며, 이 규칙을 따르지 않습니다.
어시스턴트 prefill(assistant prefill): role: "assistant"로 끝나는 메시지로 모델 응답의 앞부분을 미리 채우는 방식은 claude-sonnet-4-6, claude-opus-4-6 및 이후의 모든 모델에서 400을 반환합니다(claude-sonnet-5, claude-sonnet-5-5, claude-opus-5-5, claude-fable-5-1, claude-haiku-5-5 포함. Haiku 5.5는 사고를 끈 상태에서도 불가). 사고를 켠 경우에는 어떤 모델에서도 사용할 수 없습니다. 대신 output_config.format(구조화된 출력) 또는 시스템 프롬프트로 출력 형식을 제약하세요.
number
필수
생성할 최대 토큰 수로, 응답 길이를 제어합니다. 0보다 커야 합니다. 사고 토큰도 이 한도에 포함되므로 사고를 켤 때는 충분한 여유를 확보해야 하며, 그렇지 않으면 stop_reason: "max_tokens"로 잘릴 수 있습니다.모델 지원(모델마다 단일 요청의 출력 상한이 다릅니다)
string|array
시스템 프롬프트. 문자열 또는 미디어 콘텐츠 배열로 지정할 수 있습니다. 모델의 동작과 역할을 설정하는 데 사용됩니다.모델 지원: 모든 Claude 모델에서 지원되며 차이가 없습니다.
number
기본값:"1.0"
무작위성 제어, 0-1. 값이 높을수록 응답이 더 무작위적입니다.모델 지원
claude-haiku-5-5는 검증이 더 엄격합니다. temperature는 1만 허용하며 그 외의 모든 값(0 포함)은 400을 반환합니다. temperature와 top_p를 함께 전달해도 400을 반환합니다. 기존에 Haiku 4.5에서 temperature: 0으로 분류 작업을 하던 경우, 이 매개변수를 삭제하고 구조화된 출력(output_config.format)으로 결과를 제약하세요. 공식 문서: Claude Haiku 5.5 마이그레이션 가이드
Claude 4 이상의 모든 모델: temperature와 top_p는 동시에 전달할 수 없으며 둘 중 하나만 선택해야 합니다.
number
기본값:"1.0"
Nucleus 샘플링 매개변수, 0-1. 생성 다양성을 제어합니다.모델 지원
number
Top-K 샘플링 매개변수.모델 지원
boolean
기본값:"false"
스트리밍 출력 활성화 여부. SSE 형식의 데이터 청크를 반환합니다.모델 지원: 모든 Claude 모델에서 지원되며 차이가 없습니다.
공식 SDK는 max_tokens > 21333일 때 스트리밍을 강제하며, 그렇지 않으면 HTTP 타임아웃 오류가 발생합니다(클라이언트 측 검증이며 서버 제한이 아닙니다). 사고를 켜거나 큰 max_tokens를 사용할 때는 항상 스트리밍을 활성화하는 것을 권장합니다.
array
중지 시퀀스 목록. 모델이 이 시퀀스를 생성하면 생성이 중단되며, 이때 응답의 stop_reason은 stop_sequence입니다.모델 지원: 모든 Claude 모델에서 지원되며 차이가 없습니다.
array
도구 정의 목록. 함수 도구와 웹 검색 도구를 지원합니다.모델 지원: 모든 Claude 모델에서 지원되며 차이가 없습니다(사용 가능한 서버 도구 유형은 모델 세대에 따라 다릅니다).
object
도구 선택 전략. 모델이 도구를 사용하는 방식을 제어하며, auto(기본값), none, any, tool 중에서 선택할 수 있습니다.모델 지원
강제 호출을 지원하지 않는 모델에서는 {"type": "auto"}를 사용하고 프롬프트에서 사용할 도구를 명시적으로 요청하세요. 아울러 도구 정의에 strict: true를 추가하면 매개변수가 schema를 따르도록 보장할 수 있습니다. auto는 도구 호출을 보장하지 않으므로 코드에서 호출 여부를 확인하고, 호출되지 않았다면 재시도하세요. 강제 호출의 목적이 JSON을 얻는 것뿐이라면 구조화된 출력(output_config.format)을 직접 사용하세요.공식 문서: Forced tool use is not supported | Strict tool use
object
확장 사고 설정. Claude의 심층 추론 기능을 활성화합니다.모델 지원(세대별 차이가 가장 큰 매개변수이므로 아래 표를 확인하세요)
Claude Opus 4.7부터, 그리고 Fable, Opus 5 / 5.5, Sonnet 5 / 5.5, Haiku 5.5 전 시리즈에서 {"type": "enabled", "budget_tokens": N}은 무조건 400을 반환합니다. 대신 {"type": "adaptive"} + output_config.effort로 사고 깊이를 제어하세요. budget_tokens는 Claude 4.5 및 이전 모델에서만 필수이며, Opus 4.6 / Sonnet 4.6에서는 지원 중단 예정이지만 당분간 사용할 수 있습니다.
display의 기본값은 모델마다 다릅니다: Claude Fable 5.1, Fable 5, Opus 5.5, Opus 5, Sonnet 5.5, Sonnet 5, Haiku 5.5, Opus 4.8, Opus 4.7은 "omitted"가 기본값이며, Claude Opus 4.6, Sonnet 4.6 및 이전 모델은 "summarized"가 기본값입니다. 전자에서 사고 과정을 사용자에게 보여주려면 반드시 "display": "summarized"를 명시적으로 설정해야 하며, 그렇지 않으면 사고 내용이 빈 문자열로 반환됩니다.
Fable 5.1, Opus 5.5, Sonnet 5.5의 응답 구조 변경: 모델이 두 번의 도구 호출 사이에 작성하는 긴 진행 상황 설명은 더 이상 text 블록이 아니라 thinking 블록으로 반환됩니다. 기본값인 display: "omitted"에서는 이 블록의 내용이 비어 있으므로, text 블록만 렌더링하는 클라이언트는 긴 Agent 턴 동안 출력이 오랫동안 없을 수 있습니다. 블록의 위치에 의존하지 말고 블록의 type에 따라 응답을 파싱하세요. 여러 번의 도구 호출이 있을 때는 thinking 블록을 그대로 다시 전달하세요.공식 문서: Thinking | 사고 표시 제어(display) | 진행 상황 업데이트(progress updates) | thinking 블록 보존
object
Claude Sonnet 5.5 전용. claude-sonnet-5-5에서는 {"type": "disabled"}가 400을 반환하므로, 사고를 끄고 싶다면 {"type": "between_tools"}를 사용하세요. 이는 이 모델의 사고 최저 단계입니다. 모델은 extended thinking을 수행하지 않으며, 두 번의 도구 호출 사이에 작성한 짧은 진행 상황 설명이 thinking 블록으로 반환되고 요약 텍스트가 포함됩니다(adaptive가 기본적으로 빈 내용을 반환하는 것과 다릅니다). beta 요청 헤더는 필요하지 않습니다.사용 제한(하나라도 위반하면 **400 invalid_request_error**를 반환합니다):
공식 권장 사항은 **adaptive thinking + effort: "low"**를 우선 사용하는 것입니다. low 단계에서는 모델이 아주 짧게 사고하며, 간단한 요청은 대체로 사고를 바로 건너뜁니다. 사고를 정말 꺼야 할 때만 between_tools를 사용하세요. 동일한 요청 본문을 다른 모델로 재시도하는 코드(예: 폴백, 라우팅)가 있다면 먼저 between_tools를 제거하는 것을 잊지 마세요.공식 문서: Turn off up-front thinking(Sonnet 5.5 마이그레이션 가이드) | Running without up-front thinking
object
출력 설정. 모델의 사고 깊이와 토큰 소비를 제어합니다.
이 매개변수는 응답의 모든 토큰(본문, 도구 호출, 사고)에 영향을 주므로 사고를 활성화하지 않아도 적용됩니다.모델 지원
Claude Opus 5와 Haiku 5.5에서는 effort가 "xhigh" 또는 "max"일 때 사고를 비활성화할 수 없습니다. 이때 "thinking": {"type": "disabled"}를 함께 전달하면 400이 반환됩니다. 사고를 끄려면 effort를 "high" 이하로 설정하세요. Sonnet 5.5의 between_tools도 같은 규칙입니다. Opus 5.5는 어떤 단계에서도 사고를 끌 수 없으며, effort를 낮추는 방법으로만 사고를 줄일 수 있습니다.
공식 문서: Effort | Sonnet 5.5 권장 단계 | Opus 5.5 마이그레이션 가이드
object
추적 및 디버깅용 요청 메타데이터.모델 지원: 모든 Claude 모델에서 지원되며 차이가 없습니다.
string
기본값:"auto"
서비스 티어. 이 요청에 사용할 수 있는 용량 유형을 제어합니다. auto(Priority Tier 용량을 우선 사용하고, 부족하면 표준 용량으로 대체) 또는 standard_only(표준 용량만 사용) 중에서 선택할 수 있습니다. 응답의 usage.service_tier에는 이 요청이 실제로 적용된 티어가 반환됩니다. 자세한 내용은 서비스 티어(Service Tier)를 참조하세요.
array
MCP(Model Context Protocol) 서버 설정. tools의 mcp_toolset 항목과 함께 사용해야 하며, 둘 중 하나라도 빠지면 매개변수 검증 오류가 발생합니다.
object
컨텍스트 관리 설정. 대화 컨텍스트 처리 방식을 제어합니다.
object
자동 캐싱을 활성화합니다. 요청 본문 최상위에 지정하면 시스템이 마지막 캐시 가능 블록에 브레이크포인트(breakpoint)를 자동으로 적용하고, 대화가 길어짐에 따라 자동으로 뒤로 이동시킵니다. 별도의 표시를 관리할 필요가 없습니다. Prompt Caching 참조.
레거시 Amazon Bedrock 통합(InvokeModel / Converse, Opus 4.6 이하 모델)은 최상위 cache_control을 지원하지 않으며 전달하면 400을 반환합니다. 해당 모델에서는 콘텐츠 블록 단위의 명시적 브레이크포인트를 사용하세요. 플랫폼별 지원 현황 참조.

매개변수 지원 요약표

이 엔드포인트가 지원하는 Claude 모델에서 각 매개변수의 사용 가능 여부를 정리했습니다(✅ 지원 / ⚠️ 조건부 / ❌ 전달 시 400). 최신 세대 모델 이전 세대 및 그 이전 모델
위 표는 Anthropic 공식 API 문서를 기준으로 정리했습니다(확인 날짜: 2026-10-14). 모델별 세부 사항은 공식 마이그레이션 가이드를 참조하세요: Fable 5.1 · Opus 5.5 · Sonnet 5.5 · Haiku 5.5. 모델 기능은 버전에 따라 달라질 수 있으므로 정확한 내용은 모델 마켓과 실제 호출 결과를 기준으로 하세요.

Prompt Caching(프롬프트 캐싱)

Prompt Caching을 사용하면 자주 사용하는 컨텍스트 콘텐츠를 캐시하여 비용을 크게 절감하고 응답 속도를 향상시킬 수 있습니다. 공식 문서: Prompt caching 활성화 방법은 두 가지이며, 단독으로도 조합해서도 사용할 수 있습니다.

캐시 제어 매개변수

두 방식의 필드 구조는 동일합니다. 필드 설명:

자동 캐싱(최상위 cache_control)

cache_control을 요청 본문 루트에 그대로 넣으면 됩니다. 콘텐츠 블록에 별도 표시를 할 필요가 없습니다.
브레이크포인트는 대화가 길어지면 자동으로 뒤로 이동합니다. 매 요청마다 마지막 캐시 가능 블록까지 캐시하고, 이전 콘텐츠는 캐시에서 읽습니다.

플랫폼별 지원 현황

자동 캐싱(최상위 cache_control)은 대부분의 플랫폼에서 사용할 수 있으며, 유일한 예외는 레거시 Amazon Bedrock 통합입니다. 즉 AWS에서의 지원 여부는 어떤 Bedrock 통합을 사용하는지에 따라 달라지며, 이는 모델에 의해 결정됩니다. 모델별 대조:
특정 모델이 실제로 어떤 경로를 사용하는지 확실하지 않다면 동일한 프리픽스로 두 번 요청한 뒤 두 번째 응답의 usage.cache_read_input_tokens가 0보다 큰지 확인하여 캐시가 실제로 적중했는지 검증하세요.

명시적 브레이크포인트(콘텐츠 블록 단위 cache_control)

system 배열 요소 또는 messages의 content 배열 요소 내부에 지정합니다.

두 방식 조합하기

자동 캐싱과 명시적 브레이크포인트는 함께 사용할 수 있습니다. 대표적인 패턴은 명시적 브레이크포인트로 시스템 프롬프트를 고정하고, 길어지는 대화 부분은 자동 캐싱에 맡기는 것입니다.
조합 시 규칙 및 경계 상황:
  • 자동 캐싱은 4개의 브레이크포인트 슬롯 중 1개를 사용합니다
  • 명시적 브레이크포인트가 이미 4개인 상태에서 최상위 cache_control을 보내면 400을 반환합니다(남은 슬롯 없음)
  • 마지막 블록에 **동일한 ttl**의 명시적 cache_control이 이미 있으면 자동 캐싱은 무동작이며 슬롯을 추가로 쓰지 않습니다
  • 마지막 블록에 **다른 ttl**의 명시적 cache_control이 있으면 400을 반환합니다
  • 마지막 블록이 브레이크포인트 대상으로 적합하지 않으면 시스템이 앞쪽으로 되짚어 가장 가까운 적합한 블록을 찾고, 없으면 캐싱을 건너뜁니다(오류 없음)

캐싱 메커니즘

  • 캐시 브레이크포인트: 요청당 최대 4개의 콘텐츠 블록을 지정할 수 있습니다. 각 브레이크포인트는 처음부터 해당 블록까지의 전체 프리픽스를 캐시 항목으로 각각 기록합니다
  • 캐시 적중: 요청 시 시스템이 브레이크포인트 지점에서 프리픽스를 비교하며, 일치하지 않으면 한 블록씩 앞으로 되짚어 탐색합니다. 되짚기 범위는 최대 20개 콘텐츠 블록이며, 이 범위를 벗어난 이전 캐시는 적중하지 않으므로 이 경우 더 앞쪽에 브레이크포인트를 추가하는 것이 좋습니다
  • 캐시 임계값: 모델별 최소 캐시 가능 길이보다 짧은 콘텐츠는 캐시되지 않습니다(오류 없이 일반 입력으로 처리됨). 모델별 임계값은 아래 표를 참조하세요
  • 캐시 유효 기간: 5분(기본값) 또는 1시간
  • 비용: 캐시 읽기는 일반 입력 가격의 10%(90% 저렴)이며, 캐시 쓰기에는 할증이 있습니다 — 5분 캐시는 1.25배, 1시간 캐시는 2배

모델별 최소 캐시 가능 길이

사용 사례

  1. 긴 문서 분석: system에 대용량 문서를 캐시하고 여러 질문 수행
  2. 코드베이스 이해: 코드 컨텍스트를 캐시하여 다중 턴 코드 분석
  3. 지식 베이스 Q&A: 지식 베이스 콘텐츠를 캐시하여 빠른 조회
  4. 다중 턴 대화: 대화 기록을 캐시하여 컨텍스트 일관성 유지

기본 예제

고급 기능

시스템 프롬프트

시스템 프롬프트는 문자열 또는 미디어 콘텐츠 배열로 설정할 수 있습니다.

확장 사고(Extended Thinking)

Claude는 확장 사고를 지원하며, 모델은 최종 답변을 내놓기 전에 먼저 내부적으로 추론합니다. 세대별로 작성 방식이 다릅니다(공식 문서: Thinking).
  • budget_tokens는 이전 모델에만 사용하며, 최소 1024이고 max_tokens보다 작아야 합니다
  • 사고를 켜면 이전 모델에서는 temperature / top_k를 사용할 수 없고 top_p는 0.95 ~ 1만 허용됩니다. 최신 모델에서는 이러한 샘플링 매개변수를 아예 전달하지 마세요
  • 사고 토큰은 max_tokens에 포함되므로 충분한 여유를 확보하세요(장기 Agent 코딩은 64K부터 시작할 수 있습니다)
  • 최신 모델의 display 기본값은 "omitted"이므로, 사고 내용을 보려면 "display": "summarized"를 명시적으로 설정해야 합니다. 스트리밍과 비스트리밍 모두 thinking 블록을 반환합니다
  • 여러 번의 도구 호출이 있을 때는 thinking 블록(signature 포함)을 수정하거나 삭제하지 말고 그대로 다시 전달하세요

도구 호출(Tools)

함수 도구와 웹 검색 도구를 지원합니다.

tool_choice 매개변수 상세

tool_choice는 모델이 도구를 사용하는 방식을 제어합니다.
any와 tool은 claude-fable-5-1, claude-opus-5-5, claude-sonnet-5-5에서 400을 반환합니다. 대체 방법은 위의 tool_choice 매개변수 설명을 참조하세요. auto와 함께 쓰는 disable_parallel_tool_use: true는 여전히 사용할 수 있으며, 「최대 한 번만 호출」을 의미합니다.
예제:

텍스트 편집기 도구(Text Editor Tool)

Claude 공식 사전 정의 파일 읽기/쓰기 도구로, 모델이 로컬 파일을 조회하고 수정할 수 있게 합니다. 코드 디버깅, 리팩터링, 문서 편집 시나리오에서 흔히 사용됩니다. schema는 Anthropic이 정의하고 실제 실행은 사용자의 프로그램이 로컬에서 수행합니다. 모델이 tool_use 블록을 반환하면, 사용자가 해당 파일 작업을 실행한 뒤 그 결과를 tool_result로 다시 전달합니다. 선언 시 input_schema는 필요 없으며 type과 name만 지정하면 됩니다.
모델은 tool_use.input.command에 다음 명령 중 하나를 반환합니다.
path는 모델이 생성하므로 신뢰할 수 없는 입력입니다. 실행 전에 반드시 정규 경로로 해석한 뒤 프로젝트 루트 디렉터리 안에 있는지 검증하여 .., 심볼릭 링크 등을 통한 경로 탐색(path traversal)을 방지하세요. 오류가 발생하면 is_error: true인 tool_result를 반환하면 모델이 이를 바탕으로 재시도할 수 있습니다.
구버전 text_editor_20250124 + str_replace_editor는 Claude 4 이상 모델에서 더 이상 지원되지 않으며, undo_edit 명령도 제거되었습니다. 전체 명령 설명과 언어별 참조 구현은 Anthropic 공식 문서를 참조하세요: Text editor tool.

서비스 티어(Service Tier)

Anthropic은 가용성, 성능, 비용 사이에서 균형을 맞출 수 있도록 세 가지 서비스 티어를 제공합니다. Standard(기본값, best-effort), Priority Tier(우선 스케줄링, 피크 시간대의 overloaded 오류 감소), Batch(비동기 배치 처리)입니다. service_tier 매개변수로 이 요청에 사용할 수 있는 용량을 제어합니다.
응답의 usage.service_tier에는 이 요청이 실제로 적용된 티어(예: "priority" / "standard")가 반환되며, 이를 통해 스케줄링 결과를 확인할 수 있습니다.
Priority Tier의 용량 약정은 신규 구매가 중단되었으며, 기존 계약 사용자만 계약 만료 시까지 계속 사용할 수 있습니다. 그 외 계정의 요청은 실제로 모두 표준 용량으로 처리됩니다. 또한 Priority Tier는 claude-fable-5-1, claude-opus-5-5, claude-sonnet-5-5, claude-opus-5, claude-sonnet-5를 포함하지 않으며, 이 모델들에 Priority Tier를 지정하면 검증에 실패합니다.
service_tier는 Anthropic 공식 매개변수이며 이 플랫폼은 이를 업스트림으로 그대로 전달합니다. 실제 스케줄링 결과는 응답의 usage.service_tier를 기준으로 하세요. 자세한 내용은 공식 문서를 참조하세요: Service tiers.

멀티모달 입력(이미지)

메시지에 이미지를 포함할 수 있습니다.

Prompt Caching(프롬프트 캐싱)

자주 사용하는 컨텍스트 콘텐츠를 캐시하면 비용을 크게 절감하고 응답 속도를 향상시킬 수 있습니다.
첫 번째 요청 응답:
5분 이내 재요청(다른 질문, 동일한 system):
캐시 핵심 사항:
  • 콘텐츠가 1024 토큰 이상이어야(Claude Sonnet 4.5 기준) 캐싱이 적용됩니다
  • ttl을 지정하지 않으면 캐시는 5분 동안 유효합니다
  • ttl: "1h"이면 캐시는 1시간 동안 유효합니다
  • 캐시 읽기 비용은 일반 입력보다 90% 저렴하며, 캐시 쓰기에는 할증이 있습니다(5분 1.25배, 1시간 2배)
  • 요청당 최대 4개의 콘텐츠 블록을 지정할 수 있으며, 각 브레이크포인트는 각각 하나의 캐시 항목을 기록합니다
  • 캐시는 콘텐츠의 완전 일치를 기반으로 하므로 어떤 변경이든 캐시 무효화를 유발합니다
모범 사례:
  • 변하지 않는 긴 컨텍스트(문서, 코드베이스 등)는 system에 넣고 캐싱을 활성화하세요
  • 장기적으로 안정적인 콘텐츠에는 1시간 캐시(ttl: "1h")를 사용하세요
  • 자주 바뀌는 콘텐츠에는 기본 5분 캐시(ttl 생략)를 사용하세요
  • 멀티턴 대화에서는 대화 기록을 캐시할 수 있습니다
  • cache_creation_input_tokens와 cache_read_input_tokens를 주기적으로 모니터링하여 비용을 최적화하세요

응답 형식

캐시 사용 시 usage 필드:
  • input_tokens: 현재 요청의 캐시되지 않은 입력 토큰
  • cache_creation_input_tokens: 최초 캐시 생성 토큰(첫 번째 요청에서만 값이 있음)
  • cache_read_input_tokens: 캐시에서 읽은 토큰(캐시 적중 시 값이 있음)
  • output_tokens: 생성된 출력 토큰

오류 처리

시스템은 업스트림 Claude API의 오류를 통합 처리하여 표준화된 오류 응답 형식을 반환합니다. 오류 응답 예제:

/v1/chat/completions와 비교

  • Claude Code 또는 기타 Anthropic 네이티브 클라이언트를 사용하는 경우 /v1/messages 엔드포인트 사용을 권장합니다
  • OpenAI SDK를 사용하거나 OpenAI 형식 호환이 필요한 경우 /v1/chat/completions 엔드포인트 사용을 권장합니다
  • 두 엔드포인트의 기능은 본질적으로 동일하며, 주요 차이는 요청/응답 형식에 있습니다

참고 사항

  • max_tokens는 필수 매개변수이며 0보다 커야 합니다
  • messages 배열은 비어 있을 수 없습니다
  • budget_tokens는 Claude 4.5 및 이전 모델에서만 사용하며 최소 1024입니다. 최신 모델은 thinking.type: "adaptive" + output_config.effort를 사용하세요
  • 최신 모델은 기본적으로 사고 내용을 반환하지 않으므로, 표시하려면 thinking.display: "summarized"를 설정하세요
  • thinking.type: "between_tools"는 claude-sonnet-5-5에서만 사용할 수 있으며 다른 thinking 필드와 함께 전달할 수 없습니다
  • claude-fable-5-1, claude-opus-5-5, claude-sonnet-5-5는 강제 도구 호출(tool_choice가 any / tool)을 지원하지 않습니다
  • 도구 호출은 여러 라운드의 상호작용이 필요합니다: 1라운드에서 도구 호출 요청 반환, 2라운드에서 도구 실행 결과 반환
  • 이미지 입력은 base64 인코딩이 필요합니다
  • 스트리밍 출력을 사용하면 첫 토큰 응답 시간과 상호작용 경험을 개선할 수 있습니다
  • 도구 호출에는 모델 응답 차단을 방지하기 위한 적절한 타임아웃 및 재시도 메커니즘이 있어야 합니다
  • 확장 사고는 복잡한 문제에 대한 추론 품질을 크게 향상시킬 수 있습니다

관련 리소스

Chat Completions (OpenAI 호환)

OpenAI 호환 채팅 엔드포인트 문서 보기

모델 목록

지원되는 모든 모델 정보 보기