DEV Community

Cover image for 클로드 오푸스 5 API 사용법
Rihpig
Rihpig

Posted on • Originally published at apidog.com

클로드 오푸스 5 API 사용법

Claude Opus 5는 2026년 7월 24일에 출시되었으며, Anthropic은 이제 개발자에게 Claude Opus 5부터 사용하도록 안내합니다. 어떤 모델을 선택할지 확실하지 않다면 Opus 5부터 시작하세요. API 모델 ID는 날짜 접미사 없는 claude-opus-5입니다.

지금 Apidog 사용해 보기

이 가이드는 API 키 발급, 첫 요청 전송, 스트리밍, 도구 사용, 적응형 사고, 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는 사고 토큰과 최종 응답 토큰을 합한 하드캡입니다. 따라서 Opus 4.8에서 복사한 요청이 Opus 5에서는 응답 도중 잘릴 수 있습니다.

기존 요청의 max_tokens가 예상 답변 길이에 맞춰 촘촘히 설정되어 있었다면 값을 늘리세요.

2. 사고 비활성화 시 effort 수준 제한

다음 조합은 400 오류를 반환합니다.

{
  "thinking": { "type": "disabled" },
  "output_config": { "effort": "xhigh" }
}
Enter fullscreen mode Exit fullscreen mode

사고를 비활성화한 경우 effort는 최대 high까지만 사용할 수 있습니다.

해결 방법은 둘 중 하나입니다.

  1. 사고를 활성화한 상태에서 비용 제어를 위해 effort를 낮춥니다.
  2. 사고를 비활성화하고 effort를 high 이하로 제한합니다.

Anthropic은 첫 번째 방법을 권장합니다. 사고를 비활성화하면 모델이 도구 호출을 실행 가능한 tool_use 블록이 아니라 일반 텍스트로 작성하거나, <thinking> 태그가 노출된 출력을 반환할 수 있습니다. 이런 텍스트는 도구를 실행하지 못하며 이후 에이전트 턴을 오염시킬 수 있습니다.

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

1단계: API 키 발급받기

Claude 개발자 플랫폼에 로그인한 뒤 조직 설정의 API 키 섹션에서 키를 생성하세요. 키는 생성 직후 한 번만 복사할 수 있으므로 안전한 위치에 보관해야 합니다.

키를 코드에 하드코딩하지 말고 환경 변수로 저장합니다.

export ANTHROPIC_API_KEY="sk-ant-..."
Enter fullscreen mode Exit fullscreen mode

Apidog 같은 GUI 클라이언트에서 테스트한다면 환경별 변수를 만드세요.

  • 로컬: ANTHROPIC_API_KEY
  • 스테이징: ANTHROPIC_API_KEY
  • 프로덕션: ANTHROPIC_API_KEY

요청 헤더에서는 다음처럼 참조합니다.

{{ANTHROPIC_API_KEY}}
Enter fullscreen mode Exit fullscreen mode

이렇게 하면 저장된 요청을 팀과 공유하면서도 비밀값이 컬렉션 내보내기에 포함되지 않습니다.

Apidog 환경 변수 설정 화면

요청이 성공하려면 청구 크레딧도 추가해야 합니다. Opus 5의 가격은 Opus 4.8과 동일하게 입력 토큰 100만 개당 5달러, 출력 토큰 100만 개당 25달러입니다. 캐싱, 배치, 고속 모드 요율은 Opus 5 전체 가격 분석에서 확인할 수 있습니다.

2단계: 첫 번째 요청 보내기

Messages API 엔드포인트는 다음과 같습니다.

POST https://api.anthropic.com/v1/messages
Enter fullscreen mode Exit fullscreen mode

필수 헤더는 세 가지입니다.

  • x-api-key
  • anthropic-version
  • content-type 
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."
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

여기서는 max_tokens를 4096으로 설정했습니다. 시작 예제에서 자주 보이는 1024보다 큰 값인데, 사고 토큰도 같은 예산을 사용하기 때문입니다.

Python SDK 예제 

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)
Enter fullscreen mode Exit fullscreen mode

message.content를 반복 처리하는 이유는 응답이 단일 문자열이 아니라 유형화된 블록 배열이기 때문입니다.

사고가 활성화되면 일반적으로 text 블록보다 먼저 thinking 블록이 포함될 수 있습니다. 따라서 아래처럼 첫 번째 블록이 항상 답변이라고 가정하면 안 됩니다.

# 잘못된 가정
print(message.content[0].text)
Enter fullscreen mode Exit fullscreen mode

Opus 5에서는 반드시 블록 타입을 검사하세요.

for block in message.content:
    if block.type == "text":
        print(block.text)
Enter fullscreen mode Exit fullscreen mode

구현 시 참고할 주요 사양은 다음과 같습니다.

  • 컨텍스트 창: 기본 및 최대 100만 토큰
  • Messages API 최대 출력: 128k 토큰
  • 지식 차단일: 2026년 5월
  • 100만 토큰 컨텍스트에 베타 헤더나 장문 컨텍스트 가격 프리미엄은 없음

전체 표는 Anthropic의 모델 개요에서 확인할 수 있습니다. 추가 사양은 Claude Opus 5 소개도 참고하세요.

3단계: 적응형 사고(adaptive thinking) 처리하기

적응형 사고는 모델이 요청별로 필요한 내부 추론량을 결정하는 동작입니다. 개발자가 사고 토큰 예산을 직접 지정하지는 않으며, 다음 단계의 effort로 간접 조절합니다.

구현할 때는 다음을 지키세요.

  • 블록 타입별로 파싱합니다. 사용자에게 표시할 출력은 block.type == "text"로 필터링합니다.
  • 사고 블록을 수정하지 않고 보존합니다. 다중 턴 또는 도구 호출 루프에서는 어시스턴트 콘텐츠 배열 전체를 메시지 기록에 추가합니다.
  • max_tokens를 사고와 응답의 공유 예산으로 계산합니다. 응답이 잘리면 stop_reason: "max_tokens"가 반환됩니다.

테스트에서는 stop_reason을 검사하는 단언을 추가하세요.

assert message.stop_reason != "max_tokens", "응답이 max_tokens 제한으로 잘렸습니다."
Enter fullscreen mode Exit fullscreen mode

사고를 완전히 비활성화해야 한다면 다음처럼 요청합니다.

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

이때 effort는 의도적으로 high로 제한됩니다. xhigh 또는 max로 올리면 400 오류가 발생합니다.

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

effort는 output_config 아래에서 설정합니다.

{
  "output_config": {
    "effort": "high"
  }
}
Enter fullscreen mode Exit fullscreen mode

사용 가능한 값은 다음과 같습니다.

  • low
  • medium
  • high
  • xhigh
  • max

기본값은 high입니다.

다음은 긴 코딩 또는 에이전트 작업에 xhigh를 사용하는 예시입니다.

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."
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

설정 전에 다음 세 가지를 확인하세요.

  1. Opus 4.8 effort 값을 그대로 재사용하지 마세요.

    Opus 5에서 low와 medium은 이전 Opus 모델보다 의미 있게 강해졌습니다. 기존 매핑을 믿기보다 자체 평가 세트로 다시 측정하세요.

  2. 코딩 및 에이전트 작업은 xhigh부터 평가하세요.

    이 경우 max_tokens가 특히 중요합니다. 긴 에이전트 턴에서는 65536을 시작점으로 사용할 수 있습니다.

  3. 낮은 effort가 더 짧은 최종 답변을 의미하지는 않습니다.

    effort는 주로 사고량을 줄입니다. 더 짧은 출력이 필요하면 프롬프트에 명시하세요.

예를 들면 다음과 같습니다.

답변은 5개 이하의 불릿 포인트로 제한하고, 코드 예제는 포함하지 마세요.
Enter fullscreen mode Exit fullscreen mode

자세한 평가 방법은 effort 매개변수 심층 분석에서 확인할 수 있습니다.

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)
Enter fullscreen mode Exit fullscreen mode

원시 SSE 이벤트 순서는 다음과 같습니다.

  1. message_start
  2. content_block_start
  3. content_block_delta
  4. content_block_stop
  5. message_delta
  6. message_stop

message_delta에는 stop_reason과 최종 출력 토큰 수가 포함됩니다.

사고가 활성화된 경우, 일반적으로 두 종류의 콘텐츠 블록이 순서대로 스트리밍됩니다.

  • 사고 블록: thinking_delta
  • 텍스트 블록: text_delta

UI에서 두 델타를 하나의 버퍼에 렌더링하면 내부 추론이 사용자에게 노출될 수 있습니다. 처음부터 블록 타입에 따라 분리해서 처리하세요.

def handle_delta(delta_type, text):
    if delta_type == "thinking_delta":
        # 사용자 UI에 출력하지 않음
        log_thinking(text)
    elif delta_type == "text_delta":
        render_to_user(text)
Enter fullscreen mode Exit fullscreen mode

SSE를 터미널에서 직접 검사하기 불편하다면 Apidog에서 스트림을 실행해 이벤트와 블록 경계를 확인할 수 있습니다.

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

도구 정의는 tools 배열에 추가합니다. 모델이 도구를 호출하면 다음 상태로 응답합니다.

stop_reason: "tool_use"
Enter fullscreen mode Exit fullscreen mode

그리고 tool_use 콘텐츠 블록에 호출할 도구와 입력값이 포함됩니다.

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(block for block in message.content if block.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,
                    }
                ],
            },
        ],
    )
Enter fullscreen mode Exit fullscreen mode

중요한 부분은 다음입니다.

{
    "role": "assistant",
    "content": message.content,
}
Enter fullscreen mode Exit fullscreen mode

message.content 전체를 전달해야 사고 블록과 도구 호출 블록이 보존됩니다. 어시스턴트 턴을 텍스트로 수동 재구성하지 마세요.

Opus 5에서 에이전트 구현 시 알아둘 사항도 있습니다.

  • tool_choice가 auto 또는 none일 때 도구 사용 시스템 프롬프트 오버헤드는 286 토큰입니다.
  • Opus 4.8에서는 290 토큰, Opus 4.7에서는 675 토큰이었습니다.
  • mid-conversation-tool-changes-2026-07-01 베타 헤더를 사용하면 프롬프트 캐시를 무효화하지 않고 턴 사이에 도구를 추가하거나 제거할 수 있습니다.
  • Opus 5는 Opus 4.8보다 하위 에이전트에 쉽게 위임할 수 있으므로, 비용 민감한 워크로드에서는 시스템 프롬프트로 작업 범위를 명확히 제한하세요.

7단계: usage 객체로 캐시 적중 확인하기

모든 응답에는 usage 객체가 포함됩니다. 프롬프트 캐싱이 실제로 작동하는지 확인하는 기준은 이 객체입니다.

{
  "usage": {
    "input_tokens": 84,
    "cache_creation_input_tokens": 6421,
    "cache_read_input_tokens": 0,
    "output_tokens": 913
  }
}
Enter fullscreen mode Exit fullscreen mode

안정적인 시스템 지시문이나 참조 자료를 캐시하려면 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."
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

캐시 동작은 다음처럼 확인합니다.

  • 첫 호출: cache_creation_input_tokens > 0, cache_read_input_tokens == 0
  • 동일한 접두사를 사용하는 두 번째 호출: cache_read_input_tokens > 0

두 번째 호출에서도 캐시 읽기 토큰이 0이라면 다음을 확인하세요.

  • 캐시 대상 접두사가 바이트 단위로 동일한지
  • 캐시 가능한 최소 토큰 수를 충족하는지
  • 시스템 프롬프트나 앞선 메시지가 미세하게 변경되지 않았는지

Opus 5의 캐시 최소값은 Opus 4.8의 1,024토큰에서 줄어든 512토큰입니다. 캐시 읽기는 기본 입력 가격 100만 토큰당 5달러 대신 0.50달러로 청구됩니다.

테스트에 캐시 단언을 추가하면 프롬프트 수정으로 인한 캐시 무효화를 청구서가 아니라 실패한 테스트로 발견할 수 있습니다.

assert response.usage.cache_read_input_tokens > 0, (
    "반복 호출에서 프롬프트 캐시가 적중하지 않았습니다."
)
Enter fullscreen mode Exit fullscreen mode

추가 절감 전략은 Claude API 비용 절감 가이드를 참고하세요.

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

위에서 다룬 모든 것은 인증 헤더, JSON 본문, SSE 스트림, 도구 호출, 응답 검증으로 구성된 HTTP 요청입니다. Apidog는 요청 전송, 비밀값 관리, 스트림 렌더링, 응답 테스트에 사용할 수 있는 API 개발 플랫폼입니다.

Apidog가 모델 추론을 실행하거나 모델을 라우팅하는 것은 아닙니다. 실제 호출은 Anthropic으로 전달됩니다.

Apidog에서 Claude API 요청을 테스트하는 화면

첫날부터 적용할 수 있는 구성은 다음과 같습니다.

  1. 요청 생성

    POST https://api.anthropic.com/v1/messages 요청을 만들고 세 가지 필수 헤더를 추가합니다. API 키는 인라인으로 입력하지 말고 환경 변수에서 참조합니다.

  2. 컬렉션에 저장

    팀원이 매번 블로그 예제에서 요청을 다시 만들지 않도록 검증된 요청을 컬렉션으로 관리합니다.

  3. effort별 요청 복제

    output_config.effort가 low, medium, high, xhigh인 요청을 각각 만들고 같은 프롬프트를 실행합니다. 품질, 지연 시간, 토큰 수를 나란히 비교하세요.

  4. SSE 스트림 확인

    "stream": true를 설정하고 도착 이벤트를 확인합니다. 사고 블록과 텍스트 블록을 애플리케이션에서 분리 처리할 수 있는지 검증하세요.

  5. 도구 호출 페이로드 검사

    stop_reason이 tool_use일 때 모델이 생성한 input 객체를 확인합니다. 예상보다 넓은 입력이 생성된다면 input_schema를 더 엄격하게 만드세요.

  6. 응답 단언 추가

    아래 조건을 테스트로 추가합니다.

   stop_reason != "max_tokens"
   cache_read_input_tokens > 0
Enter fullscreen mode Exit fullscreen mode

Apidog 다운로드 후 같은 컬렉션 패턴으로 다른 Claude 모델도 비교할 수 있습니다. 예를 들어 Sonnet 5 또는 기존 Opus 4.8 요청을 대상으로 동작 차이를 확인하세요.

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

  • thinking: disabled와 xhigh 또는 max effort를 함께 사용한 400 오류

    effort를 high로 낮추거나 사고를 다시 활성화하세요.

  • 샘플링 매개변수 관련 400 오류

    temperature, top_p, top_k가 기본값이 아니면 Opus 4.8과 마찬가지로 400 오류가 발생합니다. 대신 시스템 프롬프트로 동작을 조절하세요.

  • 잘린 답변

    stop_reason: "max_tokens"는 사고와 응답이 공유하는 토큰 예산이 부족했다는 뜻입니다. max_tokens를 높이세요.

  • Priority Tier 미지원

    Opus 5는 Priority Tier를 지원하지 않습니다. Opus 4.8에서는 계속 지원됩니다. 엔터프라이즈 용량 계획에 의존한다면 트래픽 전환 전에 확인해야 합니다.

  • 대화 중간 시스템 메시지

    Opus 5에서는 messages 배열 안의 role: "system" 항목이 허용됩니다. Opus 4.8에서는 같은 형식이 400 오류를 반환했습니다.

  • 과도한 검증 지시

    Opus 5는 명시적 지시 없이도 자체 작업을 검증할 수 있습니다. Opus 4.8에서 가져온 “응답 전에 답변을 다시 확인하세요” 같은 지시는 이득 없이 사고 토큰만 늘릴 수 있으므로 제거를 검토하세요.

솔직한 한계

Opus 5는 Claude 스택의 최상위 모델이 아닙니다. Fable 5는 Anthropic의 “가장 유능한 광범위 출시 모델” 지위를 유지하며, 가격은 입력 토큰 100만 개당 10달러, 출력 토큰 100만 개당 50달러입니다.

Anthropic은 Opus 5가 사이버 보안 공격 및 자율 생물학 연구 영역에서 Mythos 5보다 뒤처진다고도 명시했습니다.

출시 벤치마크 주장도 주의해서 해석해야 합니다.

  • Frontier-Bench v0.1에서 Opus 4.8의 약 2배
  • ARC-AGI 3에서 다음으로 우수한 모델의 약 3배
  • CursorBench 3.2에서 Fable 5의 0.5% 이내

이 수치는 모두 Anthropic이 공개한 값이며, 2026년 7월 25일 기준 독립적으로 재현되지 않았습니다. 공급업체 결과로 취급하고, 실제 워크로드와 평가 세트로 직접 검증하세요.

가격 차이가 정당화되는 상황은 Opus 5와 Fable 5 비교에서 확인할 수 있으며, 원본 주장 출처는 Anthropic의 출시 게시물입니다.

자주 묻는 질문

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

claude-opus-5이며 날짜 접미사가 없습니다.

Amazon Bedrock에서는 anthropic.claude-opus-5를 사용합니다. Google Cloud와 AWS의 Claude 플랫폼은 퍼스트 파티 ID를 사용합니다.

작동하던 Opus 4.8 요청이 Opus 5에서 잘리기 시작한 이유는 무엇인가요?

사고가 기본 활성화되었기 때문입니다. max_tokens는 사고 토큰과 응답 토큰을 함께 제한합니다.

max_tokens를 늘리고 stop_reason: "max_tokens"를 검사하세요.

사고를 비활성화했을 때 왜 400 오류가 발생하나요?

대부분 다음 조합이 원인입니다.

{
  "thinking": { "type": "disabled" },
  "output_config": { "effort": "xhigh" }
}
Enter fullscreen mode Exit fullscreen mode

effort를 high 이하로 낮추거나, 사고를 활성화한 뒤 effort를 낮추세요.

100만 토큰 컨텍스트 창에 베타 헤더가 필요한가요?

아닙니다. Opus 5에서는 100만 토큰이 기본이자 최대값이며, 베타 헤더나 장문 컨텍스트 가격 프리미엄이 없습니다.

Batch API에서 300k 출력을 사용하려면 output-300k-2026-03-24 베타 헤더가 필요합니다. Messages API 출력은 128k로 제한됩니다.

Opus 4.8의 effort 설정을 그대로 재사용할 수 있나요?

권장되지 않습니다. Opus 5에서는 수준이 재조정되었고 low, medium이 더 강력해졌습니다. 자체 평가 세트로 새 스윕을 실행하세요.

Apidog가 모델을 실행하나요?

아닙니다. Apidog는 HTTP 요청을 보내고, 검사하고, 테스트합니다. 모델 추론은 Anthropic 측에서 실행됩니다. Apidog는 API 키, 스트리밍, 도구 호출 페이로드, 응답 단언을 관리하고 검증하는 데 사용할 수 있습니다.

Top comments (0)