Blog

클로드 오푸스 5 API 사용법

단계별 Claude Opus 5 API 가이드: 키 발급, claude-opus-5 모델 ID로 첫 호출 전송, 응답 스트리밍, 도구 사용 추가, 노력 조정, 그리고 캐시 적중 시 사용량 확인.

Ashley Innocent

Ashley Innocent

25 July 2026

클로드 오푸스 5 API 사용법

Apidog 엔터프라이즈

온프레미스 배포

SSO & RBAC

SOC 2 준수

Apidog Enterprise 살펴보기

Claude Opus 5는 2026년 7월 24일에 출시되었으며, Anthropic은 이제 개발자들에게 Claude Opus 5를 가장 먼저 사용하도록 안내합니다. 문서에는 어떤 모델을 사용할지 확실하지 않다면 Claude Opus 5부터 시작하라고 명시되어 있습니다. API 모델 ID는 날짜 접미사 없이 정확히 claude-opus-5 문자열입니다.

이 가이드는 키 발급, 첫 번째 요청 전송, 스트리밍, 도구 사용, 적응형 사고, effort 매개변수, 그리고 프롬프트 캐시가 작동하는지 확인하기 위한 usage 객체 읽기 등 전체 과정을 안내합니다. 여기의 모든 요청은 JSON 입출력을 사용하는 일반 HTTP 요청이므로, 애플리케이션 코드에 연결하기 전에 Apidog에서 이를 구축하고 디버깅할 수 있습니다.

버튼

Opus 4.8에서 변경된 두 가지 사항은 첫 호출부터 문제를 일으킬 수 있으므로, 다른 무엇보다 먼저 다룹니다. 새롭게 시작하는 것이 아니라 기존 서비스를 마이그레이션하는 경우, 이 가이드와 함께 전체 Opus 4.8에서 Opus 5로의 마이그레이션 가이드를 읽어보세요.

첫 호출 전: 두 가지 호환성 문제

1. 사고(Thinking)가 기본적으로 활성화됩니다. Opus 4.8에서는 thinking 필드가 없는 요청은 전혀 사고하지 않고 실행되었습니다. Opus 5에서는 동일한 요청이 적응형 사고(adaptive thinking)와 함께 실행됩니다. max_tokens는 여전히 사고 토큰과 응답 토큰을 합한 값에 대한 하드캡이므로, 작동하는 4.8 통합에서 복사한 요청 본문은 이제 답변 도중에 잘릴 수 있습니다. max_tokens가 예상 출력 길이에 맞춰 엄격하게 조정되었다면, 값을 높이세요.

2. 사고 비활성화는 노력(effort) 수준을 제한합니다. thinking: {"type": "disabled"}를 xhigh 또는 max의 effort와 함께 전송하면 400 오류가 반환됩니다. Anthropic은 요청별로 이를 적용하므로, 조용히 성능이 저하되는 대신 즉시 실패합니다. 해결책은 둘 중 하나를 선택하는 것입니다: 사고를 계속 활성화하고 비용 제어를 위해 effort를 낮추거나, 사고를 비활성화하고 effort를 high로 제한하세요.

Anthropic의 자체 권장 사항은 첫 번째 옵션입니다. 사고가 비활성화된 상태에서는 Opus 5가 때때로 도구 호출을 일반 텍스트로 작성하며(이들은 절대로 실행되지 않으며, 유출된 텍스트는 에이전트 루프의 이후 턴을 오염시킵니다), 때로는 <thinking> 태그가 보이는 출력으로 유출되기도 합니다. 사고를 계속 활성화하고 effort를 낮추면 이 두 가지를 모두 피할 수 있습니다.

두 가지 변경 사항은 Anthropic의 모델 마이그레이션 가이드에 문서화되어 있습니다.

1단계: API 키 발급받기

Claude 개발자 플랫폼에 로그인하고, 조직 설정의 API 키 섹션을 열어 키를 생성하세요. 한 번 복사해 두십시오. 나중에 다시 읽을 수 없습니다.

코드에 붙여넣는 대신 환경 변수에 저장하세요:

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

GUI 클라이언트에서 테스트하는 경우, 거기에도 키를 환경 변수에 넣으세요. Apidog에서는 ANTHROPIC_API_KEY 변수가 있는 환경(로컬, 스테이징, 프로덕션)을 생성한 다음, 헤더에서 {{ANTHROPIC_API_KEY}}를 참조하는 것을 의미합니다. 저장된 요청은 팀과 공유 가능하며 비밀은 컬렉션 내보내기에 포함되지 않습니다.

요청이 성공하려면 청구 크레딧을 추가해야 합니다. Opus 5의 요금은 입력 토큰 100만 개당 5달러, 출력 토큰 100만 개당 25달러로 Opus 4.8과 동일하며, 전체 가격 분석은 캐싱, 배치 및 고속 모드 요율을 다룹니다.

2단계: 첫 번째 요청 전송하기

엔드포인트는 POST https://api.anthropic.com/v1/messages입니다. 세 가지 헤더가 중요합니다: 키, API 버전, 그리고 콘텐츠 타입.

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": "claude-opus-5",
    "max_tokens": 4096,
    "messages": [
      {"role": "user", "content": "Explain the difference between a 429 and a 529 from an API perspective."}
    ]
  }'

max_tokens 값을 주목하세요. 4096은 대부분의 시작 스니펫에서 볼 수 있는 1024보다 의도적으로 상향된 값인데, 이는 사고(thinking) 토큰이 이제 동일한 예산에서 나오기 때문입니다.

공식 SDK를 통한 Python 코드:

import os
from anthropic import Anthropic

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

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Explain the difference between a 429 and a 529 from an API perspective."}
    ],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

message.content에 대한 저 반복문은 장식이 아닙니다. 응답 content는 유형화된 블록들의 배열이며, 사고(thinking)가 활성화되면 이제 text 블록 앞에 thinking 블록을 보게 될 것입니다. content[0].text가 답변이라고 가정한 코드는 Opus 5에서 작동하지 않습니다. 이것이 가장 흔한 업그레이드 실패 사례이며, 요청이 여전히 200을 반환하기 때문에 놓치기 쉽습니다.

구축하는 동안 알아두면 좋은 몇 가지 사양: Opus 5는 기본이자 최대값으로 100만 토큰 컨텍스트 창을 가지며(베타 헤더 없음, 장문 컨텍스트 가격 프리미엄 없음), Messages API에서는 최대 128k 출력, 그리고 2026년 5월까지의 지식 차단(knowledge cutoff)을 가집니다. 모델 개요에는 전체 표가 있으며, 당사의 Opus 5 설명은 나머지 사양 시트를 다룹니다.

3단계: 적응형 사고(adaptive thinking) 활용

적응형 사고는 모델이 요청에 대해 얼마나 많은 내부 추론이 필요한지 결정한다는 것을 의미합니다. 토큰 예산을 직접 설정하지 않습니다. 다음 단계에서 다룰 노력(effort)으로 이를 조절합니다.

코드에서 처리해야 할 사항:

사고를 완전히 끄려면:

{
  "model": "claude-opus-5",
  "max_tokens": 4096,
  "thinking": {"type": "disabled"},
  "output_config": {"effort": "high"},
  "messages": [{"role": "user", "content": "Return only the HTTP status code."}]
}

해당 요청에서 effort가 의도적으로 high로 제한됩니다. 이를 xhigh로 올리면 위에서 설명한 400 오류가 발생합니다.

4단계: output_config.effort로 비용 제어하기

effort 필드는 output_config 아래에 있으며, low, medium, high, xhigh, 또는 max 값을 가집니다. 기본값은 high입니다. 이는 주류 언론이 비용과 기능 사이의 토글로 설명했던 매개변수이며, API에서는 요청 본문의 단일 문자열입니다.

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": "claude-opus-5",
    "max_tokens": 65536,
    "output_config": {"effort": "xhigh"},
    "messages": [
      {"role": "user", "content": "Refactor this handler to stream responses and keep backpressure."}
    ]
  }'

조정하기 전에 알아야 할 세 가지 사항.

5단계: 응답 스트리밍하기

"stream": true를 추가하면 엔드포인트는 단일 JSON 본문 대신 서버 전송 이벤트(SSE)를 반환합니다.

with client.messages.stream(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Draft a retry policy for a flaky upstream."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

    final = stream.get_final_message()
    print("\n\nusage:", final.usage)

원시 SSE 시퀀스는 message_start, 각 블록당 content_block_start / content_block_delta / content_block_stop, stop_reason 및 최종 출력 토큰 수를 포함하는 message_delta, 그리고 마지막으로 message_stop입니다.

사고(thinking)가 활성화되면 두 개의 콘텐츠 블록이 순서대로 스트리밍됩니다: 델타가 thinking_delta로 도착하는 사고 블록, 그리고 text_delta가 있는 텍스트 블록. 모든 델타를 동일한 버퍼에 렌더링하는 UI는 모델의 추론을 사용자에게 출력할 것입니다. 처음부터 별도로 라우팅하세요.

스트리밍은 또한 GUI 클라이언트가 제 역할을 하는 지점인데, 터미널에서 원시 SSE를 읽는 것은 불편하기 때문입니다. Apidog는 이벤트 스트림을 도착하는 대로 렌더링하므로, 핸들러 코드를 한 줄도 작성하기 전에 블록 경계를 확인하고 파싱 가정을 확인할 수 있습니다.

6단계: 도구 사용 추가하기

도구 정의는 tools 배열에 들어갑니다. 모델은 stop_reason: "tool_use"와 tool_use 콘텐츠 블록으로 응답합니다. 도구를 실행하고 그 결과를 새로운 사용자 메시지의 tool_result 블록으로 다시 보냅니다.

tools = [
    {
        "name": "get_order_status",
        "description": "Look up the current status of a customer order by ID.",
        "input_schema": {
            "type": "object",
            "properties": {
                "order_id": {"type": "string", "description": "The order ID, e.g. A-10293"}
            },
            "required": ["order_id"],
        },
    }
]

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    tools=tools,
    messages=[{"role": "user", "content": "What's the status of order A-10293?"}],
)

if message.stop_reason == "tool_use":
    call = next(b for b in message.content if b.type == "tool_use")
    result = get_order_status(**call.input)

    follow_up = client.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        tools=tools,
        messages=[
            {"role": "user", "content": "What's the status of order A-10293?"},
            {"role": "assistant", "content": message.content},
            {"role": "user", "content": [
                {"type": "tool_result", "tool_use_id": call.id, "content": result}
            ]},
        ],
    )

message.content를 어시스턴트 턴으로 바로 전달하는 것이 사고(thinking) 블록을 유지하는 방법입니다. 해당 턴을 수동으로 재구성하지 마세요.

에이전트에 중요한 Opus 5의 두 가지 세부 사항. 도구 사용 시스템 프롬프트 오버헤드가 Opus 4.8보다 낮습니다: tool_choice가 auto 또는 none으로 설정된 경우 286 토큰이며, 4.8에서는 290 토큰, Opus 4.7에서는 675 토큰이었습니다. 요청당 적지만 백만 에이전트 턴에서는 실제적인 차이가 있습니다. 또한 mid-conversation-tool-changes-2026-07-01이라는 베타 헤더가 있어 프롬프트 캐시를 무효화하지 않고 턴 사이에 도구를 추가하거나 제거할 수 있습니다.

Opus 5는 또한 4.8보다 하위 에이전트에게 더 쉽게 위임합니다. 비용에 민감한 작업 부하의 경우, 청구서에서 이를 발견하기보다 시스템 프롬프트에서 명시적으로 범위를 지정하세요.

7단계: 캐시 적중을 위한 usage 객체 읽기

모든 응답에는 usage 객체가 포함됩니다. 이것은 프롬프트 캐싱이 제대로 작동하는지 확인할 수 있는 유일하고 정직한 방법입니다.

"usage": {
  "input_tokens": 84,
  "cache_creation_input_tokens": 6421,
  "cache_read_input_tokens": 0,
  "output_tokens": 913
}

블록을 캐시하려면 cache_control로 표시하세요:

{
  "model": "claude-opus-5",
  "max_tokens": 4096,
  "system": [
    {
      "type": "text",
      "text": "<your long, stable instructions and reference material>",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [{"role": "user", "content": "Question one."}]
}

첫 번째 호출: cache_creation_input_tokens는 0이 아니고 cache_read_input_tokens는 0입니다. 동일한 접두사를 사용한 두 번째 호출: 이 값들이 바뀝니다. 만약 바뀌지 않는다면, 접두사가 바이트 단위로 동일하지 않거나 최소값 미만입니다.

이 최소값은 Opus 5의 희소식입니다. 프롬프트 캐싱은 이제 Opus 4.8의 1,024 토큰에서 줄어든 512 토큰부터 적용됩니다. 이전에는 너무 짧아서 캐시되지 않던 프롬프트가 이제 코드 변경 없이 캐시되며, 캐시 읽기는 기본 입력 요금 5달러 대비 100만 토큰당 0.50달러로 청구됩니다. 테스트 스위트에서 cache_read_input_tokens를 단언하여, 캐시를 조용히 무효화하는 프롬프트 편집이 청구서가 아닌 실패하는 테스트로 나타나도록 하세요. 더 많은 정보를 원하시면 Claude API 요금 절감 가이드를 참조하세요.

Apidog에서 전체 흐름 테스트 및 디버그

위의 모든 내용은 인증 헤더, JSON 본문, SSE 스트림, 그리고 확인해야 하는 응답을 포함하는 HTTP 요청입니다. Apidog는 올인원 API 개발 플랫폼이며, Apidog가 처리하는 엔드포인트 유형에 정확히 해당합니다. 요청을 보내고, 키를 저장하고, 스트림을 렌더링하고, 응답을 테스트합니다. 추론을 실행하거나 모델을 라우팅하지 않습니다. 호출은 여전히 Anthropic으로 전달됩니다.

첫날부터 가치를 증명하는 설정:

  1. 1. 요청 생성. POST https://api.anthropic.com/v1/messages에 세 가지 헤더를 추가하고, 키는 인라인으로 붙여넣는 대신 환경 변수에서 가져옵니다.
  2. 2. 컬렉션에 저장. 팀원 각자가 블로그 스니펫에서 요청을 재구축하는 대신, 검증된 하나의 요청 형태를 재사용합니다.
  3. 3. effort 수준별로 포크. output_config.effort를 low, medium, high, xhigh로 설정한 요청을 복제하고, 각 요청에 동일한 프롬프트를 보내 출력 품질, 지연 시간, 토큰 수를 나란히 비교합니다. 이는 Anthropic이 수행하도록 요청하는 effort 스윕이며, 별도의 하네스를 작성하지 않고도 수행됩니다.
  4. 4. SSE 스트림 관찰. "stream": true를 켜고 이벤트가 도착하는 대로 읽어 사고(thinking) 블록과 텍스트 블록을 별도로 처리하는지 확인합니다.
  5. 5. 도구 호출 페이로드 검사. stop_reason이 tool_use로 반환될 때, 모델이 생성한 정확한 input 객체가 바로 거기에 있습니다. 이를 통해 input_schema가 너무 느슨했음을 알 수 있습니다.
  6. 6. 응답 단언(assert). stop_reason이 max_tokens가 아닌지(잘림 감지), 그리고 반복 호출 시 cache_read_input_tokens가 0보다 큰지(캐싱 감지) 확인하는 검사를 추가합니다.

따라하고 싶다면 Apidog를 다운로드하세요. 동일한 컬렉션 패턴은 모든 Claude 모델에 대해 작동하므로, Sonnet 5 또는 기존 Opus 4.8 요청을 대상으로 하여 동작을 비교할 수 있습니다.

실제로 마주칠 수 있는 오류 및 문제점

솔직한 한계

Opus 5는 Claude 스택의 최상위 모델이 아니며, 이를 솔직하게 말할 가치가 있습니다. Fable 5는 여전히 Anthropic의 "가장 유능한 광범위 출시 모델" 지위를 유지하며, 입력 100만 개당 10달러, 출력 100만 개당 50달러의 비용이 듭니다. Opus 5는 또한 Anthropic이 직접 명시했듯이 사이버 보안 공격 및 자율 생물학 연구 분야에서 Mythos 5에 뒤처집니다.

출시 벤치마크 주장(Frontier-Bench v0.1에서 Opus 4.8의 약 두 배, ARC-AGI 3에서 다음으로 우수한 모델의 약 3배, CursorBench 3.2에서 Fable 5의 0.5% 이내)은 모두 Anthropic 자체 수치이며 2026년 7월 25일 현재 독립적으로 재현되지 않았습니다. 이들을 공급업체가 실행한 결과로 간주하고, 자체 평가를 실행하십시오. Opus 5 대 Fable 5 비교는 가격 차이가 가치 있는 경우와 그렇지 않은 경우를 다루며, Anthropic의 출시 게시물이 이러한 주장의 주요 출처입니다.

자주 묻는 질문

Apidog에서 API 설계-첫 번째 연습

API를 더 쉽게 구축하고 사용하는 방법을 발견하세요

무료 회원가입다운로드