Claude Sonnet 5.5

Anthropic Messages 형식으로 claude-sonnet-5-5를 호출합니다. 이 문서는 공식 요청 규격과 호환성 테스트에서 관찰한 동작을 구분합니다. 일부 고급 옵션은 아직 규격대로 작동하지 않으므로, 사용하기 전에 제한 사항을 확인해야 합니다.

현재 입력, 출력 및 캐시 요금은 모델 페이지에서 확인할 수 있습니다.

빠른 시작

curl https://api.seedrouter.ai/v1/messages \
  -H "x-api-key: $SEEDROUTER_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Explain how a rainbow forms in three sentences."}]
  }'

POST /v1/messages는 x-api-key 또는 Bearer 인증과 anthropic-version: 2023-06-01을 사용합니다. 공식 문서에서 beta 헤더를 요구하는 기능에는 anthropic-beta를 전송합니다. 인증 정보는 서버 측 코드에서 관리해야 합니다.

이 모델은 기본적인 OpenAI Chat Completions(POST /v1/chat/completions) 및 Responses(POST /v1/responses) 요청도 받습니다. 아래의 네이티브 파라미터를 사용하려면 Messages 형식을 사용합니다. OpenAI 형식 변환이 Anthropic의 모든 기능을 제공하는 것은 아닙니다.

공식 파라미터 규격

Sonnet 5.5의 컨텍스트 윈도우는 1M 토큰이며, 동기 요청의 출력 한도는 128000 토큰입니다. Batch 전용 출력 한도는 이 엔드포인트에 적용되지 않습니다. 표에 명시된 경우를 제외하면 애플리케이션은 선택적 속성의 기본값을 지정하지 않습니다.

between_tools는 자체 type 속성만 허용하며, 노력 수준은 low, medium, high만 허용합니다. display, budget_tokens, block_binding을 함께 보내면 안 됩니다. 예제는 다음과 같습니다.

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "thinking": {"type": "between_tools"},
  "output_config": {"effort": "medium"},
  "messages": [{"role": "user", "content": "Explain this concept briefly."}]
}

assistant 사전 채우기는 지원하지 않습니다. pause_turn을 이어가려면 반환된 서버 도구의 assistant 콘텐츠를 변경 없이 다시 전송해야 합니다. 압축은 기존 기록을 요약하는 동작이며 assistant 사전 채우기가 아닙니다. 사고 블록과 서명은 정확히 보존해야 합니다. 공식 바인딩 규칙을 따르지 않은 채 모델 간에 옮기거나 이전 기록을 편집해서는 안 됩니다.

네이티브 Claude API에서 컴퓨터 사용 기능에는 computer_toolset_20260801이 필요하며, computer_20251124는 거부됩니다. 이 실행 모델은 claude-opus-4-8, claude-opus-4-7, claude-sonnet-5를 사용하는 Advisor 설정도 거부합니다.

폴백 요청 필드

공식 fallbacks beta는 자격 요건에 맞는 분류기 거부에 대해 재시도합니다. 요청 속도 제한, 과부하 또는 서버 오류에는 재시도하지 않으며, 재시도 후에도 거부가 해소되지 않을 수 있습니다. server-side-fallback-2026-07-01을 보내면 "default" 또는 명시적 목록을 사용할 수 있습니다. server-side-fallback-2026-06-01은 목록만 지원합니다. 다른 날짜 버전은 거부됩니다.

명시적 목록에는 서로 다른 모델을 최대 세 개까지 지정할 수 있으며, 모두 요청 모델과 달라야 합니다. 허용되는 대상 모델은 beta Models API의 allowed_fallback_models에서 가져옵니다. 항목마다 허용되는 필드는 model, max_tokens, thinking, output_config, speed뿐이며, 재정의한 값은 해당 대상 모델에서 유효해야 합니다. 해당 폴백이 발생하면 칠월 beta는 Sonnet 5.5의 between_tools를 Sonnet 5의 disabled로 변환하고 display를 생략합니다. 유월 beta에서는 Sonnet 5의 사고 설정 재정의를 직접 제공해야 합니다.

fallback_credit_token은 거부 후 별도로 수행하는 재시도에 사용합니다. 문자열 형식은 엄격한 크레딧 적용을 선택하며, 객체 형식은 mode를 추가할 수 있습니다. strict 모드에서는 크레딧 적용에 실패하면 재시도가 거부됩니다. best_effort 모드에서는 토큰 처리 계층에서 실패하더라도 정상 요금으로 진행할 수 있으며, 해당 내용은 usage.fallback_credit에 기록됩니다. 다만 잘못된 형식의 토큰이나 크레딧과 fallbacks의 동시 사용은 여전히 실패합니다. 크레딧 적용에는 공식 크레딧 가이드에 설명된 요청 자격, 계정, 워크스페이스, 플랫폼 및 오 분의 유효기간 조건도 적용됩니다.

유해하지 않은 요청에 fallbacks: "default", 칠월 beta 헤더 및 speed: "standard"를 지정했을 때 예상한 텍스트가 반환되었습니다. 이는 요청 수락만 확인한 결과입니다. 폴백 실행과 크레딧 적용은 여기서 종단 간 검증을 완료하지 않았습니다.

미디어 및 도구 입력

이미지는 사용자 메시지의 image 블록을 사용하고, PDF는 document 블록을 사용합니다. 공식 소스 타입에는 공개 URL과 해당 MIME 타입이 지정된 base64가 포함됩니다. 호환성 검사에는 base64 PNG와 한 페이지의 base64 PDF를 사용했으며, 답변 내용도 확인했습니다. 모든 URL, 파일 크기, 이미지 해상도 또는 PDF 페이지 수의 경계 조건을 테스트한 것은 아닙니다.

클라이언트 측 도구는 표준 tool_use → tool_result 교환 방식을 사용합니다. 도구 사용 ID를 그대로 유지하고 사용자 메시지로 결과를 반환해야 합니다. 엄격 모드 도구 예제의 성공은 해당 예제의 인수만 검증하며, 지원되는 모든 JSON Schema 키워드를 검증하지는 않습니다.

응답

비스트리밍 응답에는 id, type: "message", role: "assistant", model, content, stop_reason, stop_sequence, usage가 포함됩니다. 그 밖에 container, diagnostics, context_management, stop_details 및 beta 응답 필드와 같은 선택적 공식 필드가 포함될 수 있습니다. 콘텐츠에는 텍스트, 사고, 도구 호출, 도구 결과 또는 기타 공식 블록 타입이 들어갈 수 있으므로, 첫 번째 블록이 텍스트라고 가정하면 안 됩니다.

스트리밍에서는 message_start, content_block_start, content_block_delta, content_block_stop, message_delta, message_stop을 처리해야 합니다. 스트림 안에서도 오류가 발생할 수 있습니다. 사용량에는 일반 입력/출력 토큰, 사고 토큰 세부 정보, 캐시 읽기, 각각 집계되는 5분 / 1시간 캐시 생성 토큰 수가 포함될 수 있습니다.

공식 분류기 거부는 HTTP 오류가 아니라 stop_reason: "refusal"과 stop_details가 포함된 정상 응답입니다. 폴백 응답에서는 model이 실제 응답한 모델을 나타내고, fallback 콘텐츠 블록이 전환을 표시하며, usage.iterations가 각 시도를 설명합니다. 요청한 모델이 응답했다고 가정하지 말고 이 필드들을 확인해야 합니다. 이러한 응답 동작은 여기서 아직 검증하지 않았습니다.

Messages 오류는 {"type":"error","error":{"type":"...","message":"..."}} 형식을 사용합니다. 실패한 요청에는 요금이 부과되지 않습니다.

호환성 검증: 2026-10-01

Beta 도구 실행, 실제 MCP 연결, Files API 참조, 지리적 데이터 레지던시, 사고 서명 재전송, 전체 컨텍스트/출력 상한, 미디어 경계 조건 및 거부/폴백 동작은 종단 간 검증을 완료하지 않았습니다. HTTP 200과 반환된 모델 이름만으로는 실제로 어떤 모델이 실행되었는지 인증할 수 없으며, 전달한 모든 옵션이 적용되었다고 증명할 수도 없습니다.

참고 자료

• Sonnet 5.5 공식 개요
• Sonnet 5.5 변경 사항 및 제한
• Messages 파라미터 참조
• 메시지별 노력 수준
• 온디맨드 압축
• 거부 및 폴백
• 폴백 크레딧
• OpenAPI 스키마
• 복사 가능한 Markdown