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) 지원 중단 등 주요 변경 사항이 있습니다. 사고 모드는 적응형(adaptive)만 지원하며, 기본적으로 꺼져 있으니 직접 활성화해야 합니다.
이 글에선 API 키 획득, 첫 요청, 적응형 사고/고해상도 이미지/도구 사용/작업 예산/스트리밍 등 전체 워크플로우를 단계별로 다룹니다. 모든 코드는 즉시 복사·실행 가능하며, Apidog를 통한 API 호출 디버깅 및 다단계 도구 사용 대화도 예시로 제공합니다.
시작하기
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에서 유일하게 지원되는 사고 모드입니다. 작업 복잡성에 따라 추론 토큰을 자동 할당합니다. 기본값은 OFF이므로 명시적으로 활성화 필요.
Python:
message = client.messages.create(
model="claude-opus-4-7",
max_tokens=16384,
thinking={
"type": "adaptive",
"display": "summarized" # optional: 사고 내용 출력
},
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사용 금지) -
"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은 최대 2,576픽셀(긴 변, 3.75MP) 이미지를 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은 기본적으로 추론을 우선시하므로, 도구 호출 빈도를 높이려면 effort 값을 올리세요.
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})
작업 예산 (베타)
작업 예산은 전체 에이전트 루프에서 토큰 한도를 부여합니다. 모델은 예산 내에서 작업을 마무리합니다.
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 토큰
- 권고(soft limit)이며 초과 가능
-
max_tokens와는 별도(모델이 볼 수 없음) - 베타 헤더
task-budgets-2026-03-13필요
스트리밍 응답
실시간 출력을 원한다면 스트리밍 API를 사용하세요.
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"을 설정하면 사고 블록이 먼저 스트리밍됩니다. 미설정 시 사고 후 텍스트가 일괄 출력됩니다.
프롬프트 캐싱
시스템 프롬프트, 긴 문서 등 반복되는 컨텍스트는 캐싱해 비용을 절감하세요.
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-opus-4-6과 claude-opus-4-7을 비교해 토큰, 응답 품질, 지연 시간 등을 분석하세요.
스키마 유효성 검사:
JSON 스키마로 예상 응답 포맷을 정의, 프롬프트/모델 변경 시 회귀 자동 포착.
일반적인 오류 및 해결 방법
| 오류 | 원인 | 해결 방법 |
|---|---|---|
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의 토크나이저는 4.6 대비 최대 35% 더 많은 토큰이 소모될 수 있습니다. 배포 전
/v1/messages/count_tokens로 예측 필수.
결론
Claude Opus 4.7은 Anthropic 제품군에서 가장 강력합니다. API는 Opus 4.6과 유사하지만, 사고 예산/샘플링 매개변수 제거로 인한 코드 수정이 필요합니다. 적응형 사고, xhigh 노력, 작업 예산, 고해상도 비전 등 새로운 기능으로 추론 품질과 비용 제어가 대폭 향상되었습니다.
실전 도입 시 기본 텍스트 요청부터 시작, 복잡도에 따라 적응형 사고/도구 사용/작업 예산을 계층화하세요. 통합 테스트, 페이로드 검증, 모델 버전 비교에는 Apidog를 적극 활용하세요.
Top comments (0)