Claude Opus 4.7 API 사용법

TL;DR

Claude Opus 4.7 (claude-opus-4-7)은 Anthropic의 가장 유능한 GA 모델입니다. 1M 토큰 컨텍스트 창, 128K 최대 출력, 적응형 사고(adaptive thinking), 새로운 xhigh 노력 수준, 작업 예산, 고해상도 비전(3.75 MP) 및 도구 사용을 지원합니다. 이 가이드는 모든 주요 기능에 대한 API 설정, 인증, 그리고 Python, TypeScript, cURL로 작성된 작동하는 코드 예제를 다룹니다.

소개

Anthropic은 Claude Opus 4.7을 2026년 4월 16일에 출시했습니다. 이 모델은 Claude 제품군 중 가장 강력한 모델이며, 복잡한 추론, 자율 에이전트, 그리고 비전 중심 워크플로우를 위한 최적의 선택입니다.

이전에 Claude API를 사용해 본 경험이 있다면 대부분의 인터페이스가 익숙할 것입니다. 하지만 Opus 4.7은 여러 가지 새로운 기능과 코드 업데이트를 필요로 하는 주요 변경 사항을 도입했습니다. 확장된 사고 예산은 사라졌습니다. 샘플링 매개변수(temperature, top_p, top_k)도 사라졌습니다. 이제 사고 모드는 적응형 사고만 지원하며, 기본적으로 꺼져 있습니다.

이 가이드는 API 키를 얻는 것부터 첫 요청을 보내는 것, 적응형 사고를 사용하는 것, 고해상도 이미지를 전송하는 것, 도구 사용을 설정하는 것, 작업 예산을 구성하는 것, 그리고 응답을 스트리밍하는 것까지 모든 단계를 안내합니다. 모든 예제는 테스트를 거쳤으며 바로 복사하여 사용할 수 있습니다. 또한 Apidog를 사용하여 API 호출을 디버깅하고 테스트하는 방법을 보여주며, 이는 원시 JSON을 파싱하는 것보다 다단계 도구 사용 대화를 훨씬 쉽게 검사할 수 있도록 합니다.

button

시작하기

API 키 가져오기

console.anthropic.com에서 가입하세요.
대시보드에서 API Keys로 이동하세요.
Create Key를 클릭하고 키를 복사하세요.
환경 변수로 저장하세요:

export ANTHROPIC_API_KEY="sk-ant-your-key-here"

SDK 설치

Python:

pip install anthropic

TypeScript/Node.js:

npm install @anthropic-ai/sdk

API 엔드포인트

모든 요청은 다음으로 전송됩니다:

POST https://api.anthropic.com/v1/messages

필수 헤더:

x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

기본 텍스트 요청

가장 간단한 API 호출. 메시지를 보내고 응답을 받습니다.

Python:

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "HTTP/2 서버 푸시가 세 문장으로 어떻게 작동하는지 설명해주세요."}
    ]
)

print(message.content[0].text)

TypeScript:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const message = await client.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 1024,
  messages: [
    { role: "user", content: "HTTP/2 서버 푸시가 세 문장으로 어떻게 작동하는지 설명해주세요." }
  ],
});

console.log(message.content[0].text);

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-opus-4-7",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "HTTP/2 서버 푸시가 세 문장으로 어떻게 작동하는지 설명해주세요."}
    ]
  }'

적응형 사고

적응형 사고는 Opus 4.7에서 유일하게 지원되는 사고 모드입니다. Claude가 작업 복잡성에 따라 추론 토큰을 동적으로 할당할 수 있도록 합니다. 기본적으로 꺼져 있으므로 명시적으로 활성화해야 합니다.

Python:

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16384,
    thinking={
        "type": "adaptive",
        "display": "summarized"  # optional: see thinking output
    },
    messages=[
        {"role": "user", "content": "이 알고리즘의 시간 복잡도를 분석하고 최적화 방안을 제안해주세요:\n\ndef find_pairs(arr, target):\n    result = []\n    for i in range(len(arr)):\n        for j in range(i+1, len(arr)):\n            if arr[i] + arr[j] == target:\n                result.append((arr[i], arr[j]))\n    return result"}
    ]
)

for block in message.content:
    if block.type == "thinking":
        print("Thinking:", block.thinking)
    elif block.type == "text":
        print("Response:", block.text)

핵심 사항:

"type": "adaptive"는 사고를 활성화합니다. budget_tokens를 설정하지 마세요. 이제 400 오류를 반환합니다.
"display": "summarized"는 사고 내용을 응답에서 볼 수 있도록 합니다. 기본값은 "omitted"입니다.
추론 깊이를 제어하려면 effort 매개변수와 결합하세요.

Effort 매개변수 사용하기

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16384,
    thinking={"type": "adaptive"},
    output_config={"effort": "xhigh"},  # xhigh | high | medium | low
    messages=[
        {"role": "user", "content": "이 풀 리퀘스트를 보안 취약점 여부에 대해 검토해주세요..."}
    ]
)

Opus 4.7의 노력 수준:

수준	최적의 용도
`xhigh`	코딩, 에이전트 작업, 복잡한 추론
`high`	가장 지능이 중요한 작업
`medium`	균형 잡힌 속도 대 품질
`low`	간단한 작업, 빠른 응답

고해상도 비전

Opus 4.7은 긴 가장자리(3.75 메가픽셀)에서 최대 2,576픽셀의 이미지를 허용합니다. 좌표는 실제 픽셀과 1:1로 매핑됩니다.

Python — URL에서 이미지 분석:

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://example.com/architecture-diagram.png"
                    }
                },
                {
                    "type": "text",
                    "text": "이 아키텍처 다이어그램을 설명해주세요. 모든 서비스와 그들 간의 연결을 나열해주세요."
                }
            ]
        }
    ]
)

print(message.content[0].text)

Python — base64를 사용하여 로컬 이미지 분석:

import base64

with open("screenshot.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data
                    }
                },
                {
                    "type": "text",
                    "text": "이 스크린샷에서 어떤 UI 버그가 보이시나요?"
                }
            ]
        }
    ]
)

고해상도 이미지는 더 많은 토큰을 소비합니다. 전체 충실도가 필요하지 않다면 비용을 줄이기 위해 이미지를 보내기 전에 크기를 조정하세요.

도구 사용 (함수 호출)

도구 사용은 Claude가 사용자가 정의한 함수를 호출할 수 있도록 합니다. Opus 4.7은 기본적으로 추론을 선호하며 도구 호출을 더 적게 사용하는 경향이 있습니다. 도구 사용을 늘리려면 노력 수준을 높이세요.

Python:

import json

tools = [
    {
        "name": "get_weather",
        "description": "도시의 현재 날씨를 가져옵니다. 기온, 상태, 습도를 반환합니다.",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "도시 이름, 예: 'San Francisco'"
                },
                "units": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "기온 단위"
                }
            },
            "required": ["city"]
        }
    }
]

messages = [
    {"role": "user", "content": "지금 도쿄의 날씨는 어떤가요?"}
]

# 첫 번째 호출 — Claude가 도구를 요청합니다
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    tools=tools,
    messages=messages,
)

# 도구 호출 처리
if response.stop_reason == "tool_use":
    messages.append({"role": "assistant", "content": response.content})

    tool_results = []
    for block in response.content:
        if block.type == "tool_use":
            # 여기에 함수를 실행하세요
            result = {"temperature": 22, "conditions": "부분적으로 흐림", "humidity": 65}

            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": json.dumps(result)
            })

    messages.append({"role": "user", "content": tool_results})

    # 두 번째 호출 — Claude가 도구 결과를 사용합니다
    final_response = client.messages.create(
        model="claude-opus-4-7",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )
    print(final_response.content[0].text)

에이전트 루프 패턴

여러 도구 호출을 순서대로 실행하는 자율 에이전트의 경우:

def run_agent(system_prompt: str, tools: list, user_message: str) -> str:
    messages = [{"role": "user", "content": user_message}]

    while True:
        response = client.messages.create(
            model="claude-opus-4-7",
            max_tokens=16384,
            system=system_prompt,
            tools=tools,
            thinking={"type": "adaptive"},
            output_config={"effort": "xhigh"},
            messages=messages,
        )

        messages.append({"role": "assistant", "content": response.content})

        if response.stop_reason != "tool_use":
            return "".join(
                block.text for block in response.content
                if hasattr(block, "text")
            )

        tool_results = []
        for block in response.content:
            if block.type == "tool_use":
                result = execute_tool(block.name, block.input)
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": result,
                })

        messages.append({"role": "user", "content": tool_results})

작업 예산 (베타)

작업 예산은 Claude에게 전체 에이전트 루프에 대한 토큰 할당량을 제공합니다. 모델은 카운트다운을 보면서 예산이 소진됨에 따라 작업을 마무리합니다.

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=128000,
    output_config={
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 128000},
    },
    messages=[
        {"role": "user", "content": "코드베이스를 검토하고 리팩토링 계획을 제안해주세요."}
    ],
    betas=["task-budgets-2026-03-13"],
)

주요 제약 사항:

최소 예산: 20,000 토큰
권고 사항이며, 엄격한 한도는 아닙니다. Claude가 초과할 수 있습니다.
max_tokens (모델이 볼 수 없는 엄격한 상한선)과는 다릅니다.
베타 헤더 task-budgets-2026-03-13이 필요합니다.

스트리밍 응답

채팅 인터페이스에서 실시간 출력을 위해 응답을 스트리밍합니다.

Python:

with client.messages.stream(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "오류 처리가 포함된 CSV 파일을 파싱하는 Python 함수를 작성해주세요."}
    ]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

TypeScript:

const stream = await client.messages.stream({
  model: "claude-opus-4-7",
  max_tokens: 4096,
  messages: [
    { role: "user", content: "오류 처리가 포함된 CSV 파일을 파싱하는 Python 함수를 작성해주세요." }
  ],
});

for await (const event of stream) {
  if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
    process.stdout.write(event.delta.text);
  }
}

display: "summarized"로 적응형 사고를 활성화한 경우, 사고 블록이 먼저 스트리밍된 다음 텍스트 응답이 스트리밍됩니다. display: "summarized"가 없으면, 사용자는 사고 중에 일시 중지를 경험한 후 텍스트 출력을 보게 됩니다.

프롬프트 캐싱

반복되는 컨텍스트(시스템 프롬프트, 긴 문서)를 캐싱하여 비용을 줄입니다.

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "당신은 선임 코드 리뷰어입니다. 보안 취약점, 성능 문제, 모범 사례 위반 여부에 대해 코드를 검토하세요...",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        {"role": "user", "content": "이 함수를 검토해주세요:\n\ndef process_user_input(data):\n    return eval(data)"}
    ]
)

Opus 4.7의 캐시 가격:

작업	비용
5분 캐시 쓰기	$6.25 / MTok (기본의 1.25배)
1시간 캐시 쓰기	$10 / MTok (기본의 2배)
캐시 읽기/히트	$0.50 / MTok (기본의 0.1배)

단 한 번의 캐시 읽기로 5분 캐시 쓰기 비용을 상쇄할 수 있습니다. 두 번의 읽기로 1시간 쓰기 비용을 상쇄할 수 있습니다.

다단계 대화

메시지 배열에 추가하여 여러 단계에서 컨텍스트를 유지합니다.

messages = []

# 1단계
messages.append({"role": "user", "content": "할 일 앱을 위한 REST API를 만들어야 합니다."})

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=messages,
)

messages.append({"role": "assistant", "content": response.content})

# 2단계
messages.append({"role": "user", "content": "JWT 토큰으로 인증을 추가해주세요."})

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=messages,
)

Apidog로 API 호출 테스트하기

Claude API 통합을 구축하는 것은 다단계 메시지, 도구 정의, 도구 결과, Base64 이미지 및 스트리밍 응답과 같은 복잡한 페이로드를 포함합니다. Apidog와 같은 도구는 디버깅 및 테스트를 간소화합니다.

환경 설정:

Apidog에서 새 프로젝트를 생성하고 Claude Messages API 엔드포인트를 추가하세요.
ANTHROPIC_API_KEY를 환경 변수에 저장하세요.
필수 헤더(x-api-key, anthropic-version, content-type)를 설정하세요.

도구 사용 흐름 테스트:

Apidog를 사용하면 요청을 연결하여 완전한 도구 사용 루프를 시뮬레이션할 수 있습니다. 초기 메시지를 보내고, Claude의 도구 호출을 검사하고, 도구 결과를 구축하고, 다시 보낼 수 있습니다. 시각적 요청/응답 검사기는 각 페이로드에 정확히 무엇이 들어 있는지 보여줍니다.

모델 비교:

claude-opus-4-6 및 claude-opus-4-7에 동일한 프롬프트를 실행하여 토큰 수, 응답 품질 및 지연 시간을 비교하세요. Apidog의 테스트 러너는 A/B 비교를 반복 가능하게 만듭니다.

스키마 유효성 검사:

예상 응답 형식에 대한 JSON 스키마를 정의하고 Apidog가 Claude의 응답이 일치하는지 자동으로 검사하도록 하세요. 이는 프롬프트를 변경하거나 모델을 전환할 때 발생하는 회귀를 포착합니다.

button

일반적인 오류 및 해결 방법

오류	원인	해결 방법
400: `thinking.budget_tokens` 지원되지 않음	확장된 사고 구문 사용	`thinking: {"type": "adaptive"}`로 전환
400: `temperature` 지원되지 않음	기본값이 아닌 샘플링 매개변수 설정	`temperature`, `top_p`, `top_k` 제거
400: `max_tokens` 초과	새로운 토크나이저가 더 많은 토큰 생성	`max_tokens` 증가 (최대 128,000)
429: Rate limited	너무 많은 요청	지수 백오프 구현; 티어 제한 확인
빈 사고 블록	기본 사고 표시가 `"omitted"`임	사고 구성에 `display: "summarized"` 추가

가격 참조

사용량	비용
입력 토큰	$5 / MTok
출력 토큰	$25 / MTok
배치 입력	$2.50 / MTok
배치 출력	$12.50 / MTok
캐시 읽기	$0.50 / MTok
5분 캐시 쓰기	$6.25 / MTok
1시간 캐시 쓰기	$10 / MTok

참고: Opus 4.7의 새로운 토크나이저는 Opus 4.6에 비해 동일한 텍스트에 대해 최대 35% 더 많은 토큰을 사용할 수 있습니다. 프로덕션 배포 전에 /v1/messages/count_tokens 엔드포인트를 사용하여 비용을 예측하세요.

결론

Claude Opus 4.7은 Claude 제품군 중 가장 유능한 모델입니다. API는 Opus 4.6과 대부분 호환되지만, 확장된 사고 예산 및 샘플링 매개변수가 제거되어 코드 변경이 필요합니다. 적응형 사고, xhigh 노력 수준, 작업 예산 및 고해상도 비전과 같은 새로운 기능은 모델이 추론하는 방식과 비용에 대한 더 많은 제어를 제공합니다.

기본 텍스트 요청으로 시작하고, 복잡한 작업에는 적응형 사고를 추가하며, 에이전트가 성장함에 따라 도구 사용 및 작업 예산을 계층화하세요. Apidog를 사용하여 통합을 테스트하고, 페이로드를 검증하고, 모델 버전 간의 성능을 비교하세요.

button