클로드 소네트 5 API 사용법: Apidog로 단계별 따라하기

Claude Sonnet 5는 2026년 6월 30일에 출시되었으며, Anthropic이 출시한 Sonnet 모델 중 가장 에이전시적인 모델입니다. 이는 훨씬 저렴한 가격으로 도구 사용 및 코딩 작업에서 Opus 4.8에 가까운 성능을 발휘하므로, 루프에서 도구를 호출하는 모든 작업에 강력한 기본값으로 사용할 수 있습니다. 이 가이드는 Claude Sonnet 5 API를 처음부터 끝까지 호출하는 방법을 보여줍니다: 키를 얻고, curl 및 Python으로 첫 번째 요청을 보내고, 응답을 읽고, 새로운 적응형 사고 기본값을 처리하고, 400 오류를 반환하는 세 가지 요청 변경 사항을 피하고, 긴 출력을 스트리밍하고, 새로운 토크나이저를 사용하여 토큰을 계산하는 방법입니다.

또한 이 모든 것을 Apidog에 설정하여 요청이 셸 기록에 흩어지지 않고 저장된 환경 및 자동화된 테스트와 함께 재사용 가능한 컬렉션에 보관되도록 할 것입니다. 이전에 Messages API를 호출한 적이 있다면 대부분의 내용이 익숙할 것입니다. 모델 ID는 claude-sonnet-5이며, 요청 형식은 이미 사용하고 있는 것과 일치합니다.

button

시작하기 전에 필요한 것

API를 호출하려면 세 가지가 필요합니다.

Anthropic 계정과 Claude 플랫폼 콘솔에서 얻은 API 키.
모델 ID: claude-sonnet-5. 날짜 접미사가 없는 정확한 문자열입니다.
HTTP 요청을 보낼 수 있는 방법. curl은 빠른 테스트에 유용합니다. 반복 작업 시에는 Apidog가 더 좋습니다.

Sonnet 5는 모든 API 고객에게 제공되며, Amazon Bedrock(AWS의 Claude 플랫폼을 통해), Vertex AI를 통한 Google Cloud, 그리고 Microsoft Foundry에서 미리보기로 제공됩니다. 이 가이드에서는 Anthropic API를 직접 사용합니다. 요청 본문은 플랫폼마다 동일하며, 인증 및 엔드포인트 호스트만 변경됩니다.

API 키 가져오기

Claude 플랫폼 콘솔에 로그인하여 API 키 섹션을 열고 새 키를 생성하세요. 한 번 복사하여 안전한 곳에 저장해두세요. 콘솔에서는 다시 표시되지 않습니다. 소스 코드에 키를 하드코딩하거나 git에 커밋하지 마세요. 대신 환경 변수로 설정하세요:

export ANTHROPIC_API_KEY="sk-ant-..."

ZDR 계약을 맺고 있다면 Sonnet 5는 제로 데이터 보존을 지원하므로 API 표면과 관련하여 변경될 사항은 없습니다.

첫 번째 요청

Sonnet 5 API는 Anthropic의 Messages 엔드포인트를 사용합니다. 다음은 curl을 사용한 최소한의 요청입니다.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "API 테스트에 대한 하이쿠를 작성해 주세요."}
    ]
  }'

Python SDK를 사용한 동일한 요청:

import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "API 테스트에 대한 하이쿠를 작성해 주세요."}
    ],
)

print(message.content[0].text)

두 필드가 중요한 역할을 합니다. model은 Sonnet 5를 선택합니다. max_tokens는 총 출력을 제한합니다. max_tokens가 Sonnet 4.6과 Sonnet 5에서 다르게 작동하며, 가장 잘못 이해하기 쉬운 부분이므로 계속 읽어보세요.

응답 읽기

성공적인 호출은 다음과 같은 JSON 본문과 함께 HTTP 200을 반환합니다 (일부 생략):

{
  "id": "msg_01ABC...",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5",
  "content": [
    {"type": "text", "text": "주장은 초록색,\n엔드포인트는 첫 시도에 응답하고,\n오늘 밤 병합 배포."}
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 18,
    "output_tokens": 27
  }
}

실제 작업에 중요한 몇 가지 필드가 있습니다.

content는 배열입니다. 텍스트는 type이 "text"인 블록에 있습니다. 도구 사용 또는 사고 기능이 활성화된 경우, 동일한 배열에서 다른 블록 유형을 볼 수 있으므로, content[0]이 항상 답이라고 가정하지 말고 반복하세요.
stop_reason은 생성이 왜 종료되었는지 알려줍니다. end_turn은 정상입니다. max_tokens는 한도에 도달하여 출력이 잘렸음을 의미합니다. refusal은 새로 추가되었으며 이해할 가치가 있습니다(아래 참조).
usage는 input_tokens 및 output_tokens를 보고합니다. 이것은 청구되는 기준이며, 새로운 토크나이저로 인해 동일한 텍스트에 대해 Sonnet 5에서 숫자가 더 높습니다.

거부(refusal) 정지 이유

Sonnet 5는 실시간 사이버 보안 안전장치를 갖춘 최초의 Sonnet 등급 모델입니다. 요청이 금지되거나 고위험 사이버 주제와 관련되면 모델이 거부할 수 있습니다. 거부는 오류가 아닌 stop_reason: "refusal"과 함께 일반 HTTP 200으로 반환됩니다. HTTP 호출 실패로 처리하기보다는, end_turn이 아닌 다른 정지 이유를 처리하는 방식과 동일하게 응답 구문 분석 코드에서 처리하세요.

적응형 사고는 기본적으로 켜져 있습니다

이것은 Sonnet 4.6 이후 가장 큰 행동 변화이며, 사람들을 혼란스럽게 만듭니다. Sonnet 4.6에서는 thinking 필드가 없으면 사고도 없었습니다. Sonnet 5에서는 적응형 사고가 기본적으로 켜져 있습니다. 이제 thinking 필드가 없는 요청은 적응형 사고로 실행되며, 사고 토큰은 총 출력에 포함됩니다.

max_tokens는 총 출력(사고 토큰 + 응답 텍스트)에 대한 엄격한 한도이므로, 4.6에서 편안했던 max_tokens 값은 이제 가시적인 답변이 완료되기 전에 잘릴 수 있습니다. 사고를 사용하지 않고 엄격한 max_tokens를 설정한 워크로드를 마이그레이션했다면, 이를 늘리거나 잘림을 예상해야 합니다.

사고 기능을 완전히 끄려면:

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    thinking={"type": "disabled"},
    messages=[
        {"role": "user", "content": "추론 없이 JSON만 반환해 주세요."}
    ],
)

적응형 사고를 켜두고 모델이 얼마나 열심히 작업할지 제어하려면, 수동 토큰 예산을 설정하려 하지 말고 effort 매개변수를 사용하세요. Effort는 low, medium, high, xhigh를 지원합니다. 더 높은 effort는 더 깊은 사고와 더 많은 토큰 소비를 의미합니다. Anthropic은 적응형 사고 페이지에 해당 동작을 문서화했습니다. 필드 값은 budget_tokens 숫자가 아닌 {"type": "adaptive"}입니다.

400을 반환하는 세 가지 요청 변경 사항

Sonnet 4.6 또는 이전 Claude 모델에서 코드를 포팅하는 경우, 이전에 작동했던 세 가지가 이제 400 오류를 반환합니다. 마이그레이션하기 전에 수정하세요.

수동 확장 사고 기능이 제거되었습니다. thinking: {type: "enabled", budget_tokens: N}은 400을 반환합니다. 이 기능은 4.6에서도 이미 사용 중단되었습니다. 대신 적응형 사고와 effort 매개변수를 사용하세요.
샘플링 매개변수는 거부됩니다. temperature, top_p 또는 top_k를 기본값이 아닌 값으로 설정하면 400을 반환합니다. 이를 제거하세요. 생략하거나 기본값으로 두는 것은 괜찮습니다. 대신 시스템 프롬프트 지침으로 동작을 조종하세요. 이 제약 조건은 Opus 4.7 이상에서 이미 적용되었지만, Sonnet 클래스에는 새로 적용됩니다.
어시스턴트 메시지 미리 채우기는 지원되지 않습니다. 어시스턴트 턴의 시작 부분을 미리 채우면 400을 반환합니다. 대신 구조화된 출력 또는 output_config.format 또는 시스템 프롬프트 지침을 사용하여 출력을 형성하세요.

Sonnet 4.6에서 실행되는 다른 모든 기능은 코드 변경 없이 Sonnet 5에서 실행됩니다. 요청, 응답 및 스트리밍 형식은 동일합니다. 더 자세한 마이그레이션 안내는 Sonnet 5가 상속하는 동일한 요청 표면을 다루는 Claude Sonnet 4.6 API 가이드를 참조하세요.

대용량 출력을 위한 스트리밍

Sonnet 5는 최대 128,000 토큰의 출력을 지원합니다. 긴 응답의 경우 또는 적응형 사고로 인해 총 출력이 높아지는 모든 요청의 경우, 전체 응답을 기다리지 않고 토큰이 생성되는 대로 얻을 수 있도록 결과를 스트리밍하세요. 스트리밍은 또한 대규모 생성 시 클라이언트 시간 초과를 방지합니다.

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=8000,
    messages=[
        {"role": "user", "content": "서점 결제 API에 대한 OpenAPI 3.1 사양 초안을 작성해 주세요."}
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

스트리밍 이벤트 형식은 Sonnet 4.6과 동일하므로 기존 스트림 핸들러는 변경 없이 작동합니다.

새 토크나이저를 사용한 토큰 계산

Sonnet 5는 새로운 토크나이저를 사용합니다. 동일한 입력 텍스트는 Sonnet 4.6보다 약 30% 더 많은 토큰, 즉 약 1.3배를 생성합니다. 이는 API 변경 사항이 아닙니다. 요청, 응답 및 스트리밍 형식은 동일하며, 이로 인해 코드를 변경할 필요가 없습니다. 그러나 토큰으로 측정하거나 예산을 책정하는 모든 것에 영향을 미칩니다.

동일한 텍스트에 대해 usage 숫자 및 토큰 계산 결과가 더 높습니다. Sonnet 5에 대해 다시 계산하세요. 4.6의 계산을 재사용하지 마세요.
1,000,000 토큰 컨텍스트 창은 이제 각 토큰이 더 적은 텍스트를 포함하므로 평균적으로 더 적은 텍스트를 담습니다.
예상 출력에 가깝게 설정된 max_tokens 값이 이제 잘릴 수 있습니다. 다시 확인하세요.
토큰당 가격은 변경되지 않았지만, 동일한 텍스트에 대한 요청당 비용은 더 높을 수 있습니다.

보내기 전에 count-tokens 엔드포인트를 사용하여 Sonnet 5의 실제 숫자를 기반으로 예산을 책정하세요:

count = client.messages.count_tokens(
    model="claude-sonnet-5",
    messages=[
        {"role": "user", "content": "Sonnet 5에서 이 프롬프트의 토큰을 예상해 주세요."}
    ],
    )
print(count.input_tokens)

Anthropic은 토큰 계산 페이지에 이 내용을 문서화했습니다.

오류, 속도 제한 및 비용 기본 사항

표준 HTTP 의미 체계가 적용됩니다. 400은 잘못된 요청을 의미합니다 (Sonnet 5에서는 위의 세 가지 변경 사항이 일반적인 용의자입니다). 401은 잘못되거나 누락된 API 키를 의미합니다. 429는 속도 제한에 도달했음을 의미합니다. retry-after 헤더를 읽고 다시 시도하기 전에 대기하세요. 거부는 오류가 아닌 200이므로 재시도 로직을 통해 처리하지 마세요.

가격 책정은 2026년 8월 31일까지 입력 토큰 100만 개당 2달러, 출력 토큰 100만 개당 10달러의 도입 요금이 적용됩니다. 그 이후에는 표준 입력 토큰 100만 개당 3달러, 출력 토큰 100만 개당 15달러로 변경되며, 이는 Sonnet 4.6과 동일한 토큰당 요율입니다. 토크나이저 변경으로 인해 동등한 텍스트에 대한 비용이 토큰당 요율이 동일하더라도 4.6보다 높을 수 있으므로, 단순한 동등성을 가정하기보다는 토큰 계산을 통해 실제 워크로드를 모델링하세요. 더 깊이 있는 비용 안내는 Claude API 비용 분석 및 Claude API 속도 제한 가이드를 참조하세요. Priority Tier는 Sonnet 5에서 사용할 수 없습니다.

Apidog에서 Sonnet 5 호출 테스트 및 구성하기

첫 curl 명령을 넘어섰다면, 요청을 저장하고, 키를 한 번만 저장하고, 응답을 자동으로 확인하고 싶을 것입니다. 바로 Apidog가 적합한 곳입니다. Apidog는 올인원 API 플랫폼이므로, 수동으로 보내는 동일한 요청이 재사용 가능하고 테스트 가능한 자산이 됩니다. Apidog를 다운로드하여 따라해보세요.

button

다음은 Sonnet 5 API를 위한 실용적인 설정입니다.

1. 요청 생성. Apidog에서 새 HTTP 요청을 추가하세요. 메서드를 POST로 설정하고 URL을 https://api.anthropic.com/v1/messages로 설정하세요. 헤더 anthropic-version: 2023-06-01 및 content-type: application/json을 추가하세요. "model": "claude-sonnet-5"가 포함된 JSON 본문을 붙여넣으세요.

2. API 키를 환경 변수로 저장. 환경(예: "Anthropic Production")을 생성하고 ANTHROPIC_API_KEY라는 변수를 추가하세요. x-api-key 헤더에서 {{ANTHROPIC_API_KEY}}로 참조하세요. 이제 키가 요청 본문 외부의 한 곳에 있으며, 요청을 편집하지 않고도 환경을 변경할 수 있습니다.

3. 컬렉션에 저장. Sonnet 5 요청, 일반 메시지 호출, 스트리밍 호출, 도구 호출 등을 하나의 컬렉션으로 그룹화하세요. 팀 전체가 curl 스니펫을 여기저기 복사하는 대신 동일하게 검증된 요청을 얻게 됩니다.

4. 자동화된 테스트 추가. 요청에 단언(assertion)을 추가하여 무언가 변경될 때 실행이 실패하도록 하세요. 예를 들어:

응답 상태가 200인지 단언.
model이 claude-sonnet-5와 같은지 단언.
stop_reason이 존재하고 max_tokens가 아닌지 단언 (토크나이저 변경 후 잘림을 빠르게 감지하는 방법).
usage.output_tokens가 0보다 큰지 단언.

이것들을 테스트 시나리오로 연결하고 프롬프트를 변경하거나 모델 버전을 마이그레이션할 때마다 CI에서 실행하세요. 마지막 단언은 적응형 사고가 기본적으로 켜짐으로 인해 발생하는 max_tokens 회귀를 감지하는 가장 저렴한 방법입니다.

5. 엔드포인트 모의(Mock). Apidog의 스마트 모의 기능은 Messages 형식에 대한 현실적인 응답을 반환하므로, 앱의 클라이언트 코드, 오류 처리 및 스트리밍 파서를 단 하나의 토큰도 소비하지 않고 빌드하고 테스트할 수 있습니다. 이는 프론트엔드 작업 및 자체 통합 계층의 부하 테스트에 유용합니다.

이를 위해 Postman에서 전환한다면, 2026년 Postman 없이 API 테스트에 대한 저희의 견해는 단일 도구에서 디자인-테스트-모의 워크플로우가 왕복 시간을 어떻게 절약하는지 다룹니다. 터미널을 선호하시나요? Apidog CLI 완전 가이드는 이러한 저장된 테스트를 파이프라인에서 실행하는 방법을 보여줍니다.

button

FAQ

Claude Sonnet 5 모델 ID는 무엇인가요?

claude-sonnet-5이며, 날짜 접미사가 없는 정확한 문자열입니다. Messages 요청의 model 필드에 사용하세요. 이는 claude-sonnet-4-6의 드롭인 대체품이므로, 대부분의 경우 모델 ID를 변경하고 세 가지를 검토하면 됩니다: 적응형 사고가 이제 기본적으로 켜져 있다는 점, 제거된 샘플링 매개변수, 제거된 수동 사고 예산. 모델에 대한 전체 내용은 Claude Sonnet 5란 무엇인가를 참조하세요.

Sonnet 5에서 max_tokens 출력이 잘리는 이유는 무엇인가요?

적응형 사고가 기본적으로 켜져 있으며, 사고 토큰이 응답 텍스트와 함께 max_tokens에 포함됩니다. 캡이 Sonnet 4.6에서 사고 없는 워크로드에 맞춰져 있었다면, 이를 늘리거나 사고를 전혀 원하지 않는 경우 thinking: {"type": "disabled"}로 설정하세요. 새로운 토크나이저는 동일한 텍스트에 대해 약 30% 더 많은 토큰을 생성하며, 이는 이 효과를 더욱 증폭시킵니다.

Sonnet 4.6에서 마이그레이션하려면 코드를 변경해야 하나요?

세 곳만 변경하면 됩니다. 기본값이 아닌 temperature, top_p, top_k를 제거하세요. thinking: {type: "enabled", budget_tokens: N}을 제거하세요. 어시스턴트 메시지 미리 채우기를 제거하세요. 이러한 각각은 Sonnet 5에서 400을 반환합니다. 스트리밍 및 응답 형식을 포함한 다른 모든 것은 변경되지 않습니다. Opus도 실행하는 경우, 저희의 Opus 4.8 API 가이드는 동일한 Messages 표면을 사용합니다.

거부(refusal)는 잡아야 할 오류인가요?

아닙니다. 사이버 보안 거부는 stop_reason: "refusal"과 함께 HTTP 200을 반환합니다. 실패한 요청으로 처리하지 말고, end_turn이 아닌 다른 정지 이유를 가진 정상적인 응답으로 처리하세요. 오류 시 재시도 경로로 보내지 마세요.

Sonnet 5 API 비용은 얼마인가요?

도입 가격은 2026년 8월 31일까지 입력 토큰 100만 개당 2달러, 출력 토큰 100만 개당 10달러이며, 그 이후에는 각각 3달러와 15달러로 변경됩니다. 토큰당 요율은 Sonnet 4.6과 동일하지만, 새로운 토크나이저로 인해 동등한 텍스트에 대한 비용이 더 높아질 수 있으므로, 동등성을 가정하기보다는 토큰 계산을 통해 측정하세요.