Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Claude Fable 5는 Anthropic에서 가장 뛰어난 성능으로 널리 출시된 모델로, Claude API, Amazon Bedrock, Claude Platform on AWS, Google Cloud, Microsoft Foundry에서 일반적으로 사용할 수 있습니다. Claude Mythos 5는 동일한 기능을 공유하며 Project Glasswing의 승인된 고객에게 제한적으로 제공됩니다.
claude-fable-5와 claude-mythos-5가 공유하는 기본 설정:
thinking 구성이 필요하지 않습니다. thinking: {type: "disabled"}와 수동 확장 사고(thinking: {type: "enabled", budget_tokens: N}) 모두 400 오류를 반환합니다.invalid_request_error가 반환됩니다. ZDR 계약이 있는 조직은 Anthropic 계정 팀에 문의하여 데이터 보존 구성에 대해 논의해야 합니다. 또는 워크스페이스별로 데이터 보존을 구성할 수 있습니다. 플랫폼별 세부 정보는 모델별 데이터 보존 요구 사항을 참조하세요.두 모델의 차이점:
stop_reason: "refusal"로 요청을 거부할 수 있는 안전 분류기를 실행합니다. Claude Mythos 5에는 이러한 분류기가 포함되어 있지 않습니다. 거부 및 폴백을 참조하세요.Claude Mythos 5는 초대 전용 연구 프리뷰인 Claude Mythos Preview의 접근 제한 후속 모델입니다. Claude Fable 5는 동일한 기능을 갖춘 일반 제공 모델이며, 이 섹션의 변경 사항은 두 대상 모델 모두에 동일하게 적용됩니다.
마이그레이션은 대부분 즉시 적용 가능합니다. Claude Mythos 5와 Claude Fable 5는 Claude Mythos Preview와 동일한 Messages API 및 동일한 도구 사용 패턴을 사용하며, 세 모델 모두 동일한 토크나이저를 사용하기 때문에 토큰 수는 거의 변경되지 않습니다. 확인해야 할 주요 변경 사항은 더 이상 사용할 수 없는 기능(다음 섹션에 나열됨)과 사고 출력입니다. Claude Fable 5로 마이그레이션하는 경우 Claude Mythos Preview와 Claude Mythos 5에는 없는 안전 분류기 거부도 대비해야 합니다. 거부 및 폴백을 참조하세요.
Claude Mythos Preview 종료 일정은 모델 지원 중단을 참조하세요.
model = "claude-mythos-preview" # Before
model = "claude-mythos-5" # After
# 또는 동일한 기능을 갖춘 정식 출시 모델의 경우:
model = "claude-fable-5" # After확장 사고 및 사고 토큰 예산: 수동 확장 사고(thinking: {type: "enabled", budget_tokens: N})는 claude-mythos-5 또는 claude-fable-5에서 지원되지 않으며 400 오류를 반환합니다. 적응형 사고가 항상 켜져 있습니다. 모델이 각 요청에서 언제, 얼마나 사고할지 결정하며, thinking 구성이 필요하지 않습니다. thinking: {type: "disabled"}는 오류를 반환합니다. budget_tokens에는 직접적인 대체 항목이 없습니다. 사고는 적응형이며, effort 매개변수는 사고 예산이 아닌 별도의 출력 수준 제어입니다.
이전 (Claude Mythos Preview):
client.messages.create(
model="claude-mythos-preview",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 10000},
messages=[{"role": "user", "content": "..."}],
)이후 (Claude Mythos 5):
client.messages.create(
model="claude-mythos-5",
max_tokens=16000,
messages=[{"role": "user", "content": "..."}],
)Claude Fable 5의 변경 사항은 모델 이름이 claude-fable-5인 것을 제외하고 동일합니다.
어시스턴트 프리필: 어시스턴트 메시지 프리필은 claude-mythos-5 또는 claude-fable-5에서 지원되지 않으며 Claude Mythos Preview와 마찬가지로 400 오류를 반환합니다. 대신 시스템 프롬프트 지침을 사용하세요.
사고 출력: claude-mythos-5와 claude-fable-5에서는 원시 사고 과정이 반환되지 않지만, thinking.display가 summarized로 설정된 경우 사고 블록은 여전히 읽을 수 있는 요약 텍스트를 포함합니다. 동일한 모델에서 대화를 계속할 때는 사고 블록을 변경하지 않고 그대로 다시 전달하세요. Claude Fable 5 및 Claude Mythos 5의 사고 출력을 참조하세요.
claude-mythos-5와 claude-fable-5는 claude-mythos-preview와 동일한 토크나이저(Claude Opus 4.7에서 도입된 토크나이저)를 사용합니다. claude-mythos-preview에서 마이그레이션할 때 토큰 수는 거의 변경되지 않습니다. Claude Opus 4.7 이전 모델과 비교하면 동일한 콘텐츠가 콘텐츠 및 워크로드 형태에 따라 약 30% 더 많은 토큰으로 토큰화될 수 있습니다.
/v1/messages/count_tokens는 claude-mythos-preview와 비교하여 claude-mythos-5 및 claude-fable-5에 대해 거의 변경되지 않은 값을 반환합니다. 자체 워크로드에서 비용과 지연 시간을 다시 측정하세요.
claude-mythos-preview에서 claude-mythos-5로, 또는 일반 제공 모델의 경우 claude-fable-5로 업데이트하세요.thinking: {type: "enabled", budget_tokens: N})을 제거하세요. 적응형 사고가 항상 켜져 있으며 thinking 필드가 필요하지 않습니다.thinking: {type: "disabled"} 구성을 제거하세요. claude-mythos-5와 claude-fable-5에서 사고를 비활성화하면 오류가 반환됩니다.budget_tokens를 제거하세요. 직접적인 대체 항목이 없습니다. 사고는 적응형이며, effort 매개변수는 사고 예산이 아닌 별도의 출력 수준 제어입니다.thinking 필드를 파싱하는 코드가 이를 표시 텍스트로만 처리하고 동일한 모델에서 계속할 때 사고 블록을 변경하지 않고 그대로 다시 전달하는지 확인하세요. thinking.display는 Claude Mythos Preview와 마찬가지로 claude-mythos-5와 claude-fable-5에서 기본값이 "omitted"입니다. 읽을 수 있는 요약을 받으려면 display: "summarized"를 설정하세요. Claude Fable 5 및 Claude Mythos 5의 사고 출력을 참조하세요.thinking 및 redacted_thinking 블록을 제거하세요. claude-mythos-5와 claude-fable-5의 사고 블록은 이를 생성한 모델에 연결되어 있으며, Claude Fable 5와 Claude Mythos 5 이외의 모델은 이를 조용히 무시합니다. 제거하면 모델 간 요청을 최소화하고 일관되게 유지할 수 있습니다.stop_reason: "refusal"을 처리하고 stop_details.category 필드를 읽으세요. Claude Fable 5는 Claude Mythos Preview와 Claude Mythos 5에는 없는 안전 분류기를 실행합니다. 거부 및 폴백을 참조하세요.claude-mythos-preview에서 마이그레이션할 때 토큰 수는 거의 변경되지 않습니다.Claude Fable 5와 Claude Mythos 5는 Claude Opus 5와 동일한 Messages API 및 동일한 도구 사용 패턴을 사용하며, 기본적으로 동일한 1M 토큰 컨텍스트 윈도우와 동일한 128k 최대 출력 토큰을 제공합니다. 프리필 및 샘플링 매개변수 제한과 사고 표시 동작은 Claude Opus 5에서 변경 없이 그대로 적용됩니다. 확인해야 할 변경 사항은 항상 켜진 사고, 가격, Priority Tier, 데이터 보존입니다.
model = "claude-opus-5" # Before
model = "claude-fable-5" # After
# 또는 동일한 기능을 갖춘 Project Glasswing 모델의 경우:
model = "claude-mythos-5" # After사고를 더 이상 비활성화할 수 없음: Claude Opus 5에서는 사고가 기본적으로 켜져 있으며 effort 수준이 high 이하일 때 thinking: {type: "disabled"}로 끌 수 있습니다. claude-fable-5와 claude-mythos-5에서는 적응형 사고가 항상 켜져 있으며, 모든 effort 수준에서 thinking: {type: "disabled"}는 400 오류를 반환합니다. thinking: {type: "disabled"} 구성을 제거하고 대신 더 낮은 effort 수준을 사용하여 토큰 소비를 제어하세요.
가격: Claude Fable 5와 Claude Mythos 5는 입력 토큰 100만 개당 $10 USD, 출력 토큰 100만 개당 $50 USD로 책정되어 있으며, Claude Opus 5의 $5 USD 및 $25 USD와 비교됩니다. Claude 가격을 참조하세요.
Priority Tier: Priority Tier는 Claude Opus 5에서 지원되지 않으므로 기존 트래픽은 영향을 받지 않습니다. 조직에 Priority Tier 약정이 있는 경우 Claude Fable 5는 이를 지원하지만 Claude Mythos 5는 지원하지 않습니다.
데이터 보존: Claude Fable 5와 Claude Mythos 5는 30일 데이터 보존이 필요하며 "zero data retention"(데이터 무보존), 즉 ZDR 계약에서는 사용할 수 없습니다. 두 모델 모두 Covered Model로 지정되어 있습니다. 모델별 데이터 보존 요구 사항을 참조하세요.
claude-opus-5에서 claude-fable-5(또는 claude-mythos-5)로 업데이트하세요.thinking: {type: "disabled"} 구성을 제거하세요. claude-fable-5와 claude-mythos-5에서 400 오류를 반환합니다. 대신 더 낮은 effort 수준을 사용하여 토큰 소비를 제어하고, Claude Opus 5에서 사고를 비활성화한 상태로 실행했던 워크로드의 경우 max_tokens를 다시 검토하세요.마이그레이션은 대부분 즉시 적용 가능합니다. Claude Fable 5와 Claude Mythos 5는 Claude Opus 4.8과 동일한 Messages API 및 동일한 도구 사용 패턴을 사용하며, 기본적으로 동일한 1M 토큰 컨텍스트 윈도우와 동일한 128k 최대 출력 토큰을 제공합니다. 모델이 동일한 토크나이저를 사용하기 때문에 토큰 수는 거의 변경되지 않습니다. 확인해야 할 주요 변경 사항은 항상 켜진 적응형 사고, 사고 출력, 안전 분류기 거부(Claude Fable 5만 해당), 가격입니다.
model = "claude-opus-4-8" # Before
model = "claude-fable-5" # After
# 또는 동일한 기능을 갖춘 Project Glasswing 모델의 경우:
model = "claude-mythos-5" # After이 섹션의 항목은 모델 ID를 교체한 후 확인할 가치가 있는 API 및 동작 차이점을 설명합니다. 별도로 명시된 경우를 제외하고 claude-fable-5와 claude-mythos-5에 동일하게 적용됩니다.
적응형 사고가 항상 켜져 있음: 적응형 사고는 claude-fable-5와 claude-mythos-5에서 유일한 사고 모드입니다. 모델이 각 요청에서 언제, 얼마나 사고할지 결정하며, thinking 구성이 필요하지 않습니다. thinking: {type: "disabled"}는 오류를 반환합니다. 사고 깊이를 제어하려면 effort 매개변수를 사용하세요.
확인해야 할 동작 변경: Claude Opus 4.8에서는 thinking 필드가 없는 요청이 사고 없이 실행되지만, claude-fable-5와 claude-mythos-5에서는 동일한 요청이 적응형 사고와 함께 실행됩니다. max_tokens는 사고와 응답 텍스트를 합한 총 출력에 대한 하드 제한으로 유지되므로, Claude Opus 4.8에서 사고 없이 실행했던 워크로드의 경우 이를 다시 검토하세요. 비용 제어를 참조하세요.
이전 (Claude Opus 4.8):
client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
thinking={"type": "adaptive"},
output_config={"effort": "high"},
messages=[{"role": "user", "content": "..."}],
)이후 (Claude Fable 5):
client.messages.create(
model="claude-fable-5",
max_tokens=16000,
output_config={"effort": "high"},
messages=[{"role": "user", "content": "..."}],
)Claude Mythos 5의 변경 사항은 모델 이름이 claude-mythos-5인 것을 제외하고 동일합니다.
확장 사고 및 사고 예산(변경 없음): 수동 확장 사고(thinking: {type: "enabled", budget_tokens: N})는 claude-fable-5 또는 claude-mythos-5에서 지원되지 않으며 Claude Opus 4.8과 마찬가지로 400 오류를 반환합니다. budget_tokens에는 직접적인 대체 항목이 없습니다. 사고는 적응형이며, effort 매개변수는 사고 예산이 아닌 별도의 출력 수준 제어입니다.
어시스턴트 프리필(변경 없음): 어시스턴트 메시지 프리필은 claude-fable-5 또는 claude-mythos-5에서 지원되지 않으며 Claude Opus 4.8과 마찬가지로 400 오류를 반환합니다. 대신 시스템 프롬프트 지침을 사용하세요.
사고 출력: claude-fable-5와 claude-mythos-5에서는 원시 사고 과정이 반환되지 않지만, thinking.display가 summarized로 설정된 경우 사고 블록은 여전히 읽을 수 있는 요약 텍스트를 포함합니다. 동일한 모델에서 대화를 계속할 때는 사고 블록을 변경하지 않고 그대로 다시 전달하세요. Claude Fable 5 및 Claude Mythos 5의 사고 출력을 참조하세요.
안전 분류기 및 refusal 중지 이유(Claude Fable 5만 해당): claude-fable-5는 요청 시 및 응답 생성 중에 안전 분류기를 실행합니다. Claude Mythos 5에는 이러한 분류기가 포함되어 있지 않습니다. 분류기가 요청을 거부하면 Messages API는 오류가 아닌 성공적인 HTTP 200 응답으로 stop_reason: "refusal"을 반환합니다. stop_details.category 필드는 어떤 분류기가 작동했는지 보고하며, "cyber", "bio", "reasoning_extraction"과 같은 카테고리를 포함하거나, 거부가 명명된 카테고리에 매핑되지 않는 경우 null을 반환합니다. 전체 목록은 거부 카테고리 표를 참조하세요.
출력이 생성되기 전에 거부된 요청의 입력 토큰에 대해서는 과금되지 않습니다. 분류기가 스트림 중간에 작동하면 입력과 이미 스트리밍된 출력에 대해 과금됩니다. 부분 출력은 폐기하세요.
거부된 요청을 다른 모델에서 자동으로 다시 실행하려면 Claude API에서 베타로 제공되는 옵트인 fallbacks 매개변수를 전달하세요. 이 매개변수는 Message Batches API 또는 Amazon Bedrock, Google Cloud, Microsoft Foundry에서는 사용할 수 없습니다. 이 세 플랫폼에서는 클라이언트 측에서 재시도를 실행하거나 SDK 거부 폴백 미들웨어를 사용하세요. 거부 및 폴백을 참조하세요.
high effort에서 시작: effort 매개변수의 기본값은 high로 유지됩니다. Claude Opus 4.8에서는 코딩 및 높은 자율성 작업에 대해 xhigh를 명시적으로 설정하는 것이 권장됩니다. claude-fable-5와 claude-mythos-5에서는 대부분의 작업에 high를 기본값으로 사용하고 가장 성능에 민감한 워크로드에만 xhigh를 사용하세요. 더 낮은 effort 설정도 여전히 잘 작동하며 종종 이전 모델의 xhigh 성능을 초과합니다. 작업이 완료되지만 필요 이상으로 오래 걸리는 경우 effort를 줄이세요. Claude Fable 5 프롬프팅을 참조하세요.
더 낮은 프롬프트 캐싱 최소값: claude-fable-5와 claude-mythos-5의 최소 캐시 가능 프롬프트 길이는 512 토큰으로, Claude Opus 4.8의 1,024 토큰보다 낮습니다. Claude Opus 4.8에서 캐시하기에 너무 짧았던 프롬프트가 이제 코드 변경 없이 캐시 항목을 생성할 수 있습니다. 모델별 최소값은 프롬프트 캐싱을 참조하세요.
claude-fable-5와 claude-mythos-5는 30일 데이터 보존이 필요합니다. Claude API에서 이 요구 사항을 충족하지 않는 claude-fable-5 요청은 400 invalid_request_error를 반환합니다. Claude Opus 4.8은 ZDR에서 계속 사용할 수 있습니다. 모델별 데이터 보존 요구 사항을 참조하세요.claude-opus-4-8에서 claude-fable-5(또는 claude-mythos-5)로 업데이트하세요.thinking: {type: "disabled"} 구성을 제거하세요. claude-fable-5와 claude-mythos-5에서 사고를 비활성화하면 오류가 반환되며, thinking 필드가 없는 요청은 적응형 사고와 함께 실행됩니다.claude-fable-5와 claude-mythos-5에서 계속 지원되지 않습니다.thinking 필드를 파싱하는 코드가 이를 표시 텍스트로만 처리하고 동일한 모델에서 계속할 때 사고 블록을 변경하지 않고 그대로 다시 전달하는지 확인하세요. thinking.display는 Claude Opus 4.8과 마찬가지로 claude-fable-5와 claude-mythos-5에서 기본값이 "omitted"입니다. 읽을 수 있는 요약을 받으려면 display: "summarized"를 설정하세요. Claude Fable 5 및 Claude Mythos 5의 사고 출력을 참조하세요.thinking 및 redacted_thinking 블록을 제거하세요. claude-fable-5와 claude-mythos-5의 사고 블록은 이를 생성한 모델에 연결되어 있으며, Claude Fable 5와 Claude Mythos 5 이외의 모델은 이를 조용히 무시합니다. 제거하면 모델 간 요청을 최소화하고 일관되게 유지할 수 있습니다. 예외는 폴백 크레딧을 사용하는 경우로, 해당 기능의 정확한 규칙에 따라 요청 본문을 그대로 반영해야 합니다.stop_reason: "refusal"을 처리하고 stop_details.category 필드를 읽으세요. 거부된 요청을 다른 모델에서 자동으로 다시 실행하려면 옵트인 fallbacks 매개변수(베타)를 고려하세요. 거부 및 폴백을 참조하세요.effort 설정을 다시 평가하세요. Claude Opus 4.8에서 xhigh로 실행했던 워크로드를 포함하여 대부분의 작업에서 high로 시작하세요.claude-opus-4-8에서 마이그레이션할 때 토큰 수는 거의 변경되지 않지만 토큰당 가격이 다릅니다.Claude Opus 5는 Claude Opus 4.8에 비해 단계적으로 크게 개선된 모델로, 심층 추론, 에이전트 및 장기 작업, 테스트 타임 컴퓨트 스케일링에 강점이 있습니다. 동작 차이점 및 모델별 프롬프팅 패턴은 Claude Opus 5 프롬프팅을 참조하세요.
Claude Opus 5는 입력 토큰 100만 개당 $5, 출력 토큰 100만 개당 $25의 동일한 가격으로 Claude Opus 4.8을 즉시 대체할 수 있는 업그레이드입니다. Claude 가격을 참조하세요. 이미 Claude Opus 4.8에서 실행 중인 코드에 대해 두 가지 호환성이 깨지는 변경 사항이 있으며, 아래 호환성이 깨지는 변경 사항에서 다룹니다. Claude Opus 5는 1M 토큰 컨텍스트 윈도우(베타 헤더 없이 기본값), 128k 최대 출력 토큰, 적응형 사고, 프롬프트 캐싱, 배치 처리, Files API, PDF 지원, 비전, 서버 측 및 클라이언트 측 도구를 포함하여 Claude Opus 4.8과 동일한 기능 세트를 지원하지만 두 가지 예외가 있습니다. 웹 가져오기는 Claude Opus 5에서 사용할 수 없으며, Priority Tier는 Claude Opus 5에서 지원되지 않습니다. 모델 가용성은 각 도구 페이지를 참조하세요.
# Opus 마이그레이션
model = "claude-opus-4-8" # Before
model = "claude-opus-5" # Afterclaude-opus-5는 날짜 접미사가 없는 고정 모델 ID로, claude-opus-4-8 및 claude-sonnet-5와 동일한 체계입니다.
사고가 기본적으로 켜짐: Claude Opus 4.8에서는 thinking 필드가 없는 요청이 사고 없이 실행되지만, Claude Opus 5에서는 동일한 요청이 적응형 사고와 함께 실행됩니다. max_tokens는 사고와 응답 텍스트를 합한 총 출력에 대한 하드 제한으로 유지되므로, Claude Opus 4.8에서 사고 없이 실행했던 워크로드의 경우 이를 다시 검토하세요. 이전 동작을 유지하려면 다음 항목의 effort 상한에 따라 thinking: {type: "disabled"}를 전달하세요. 단, 사고를 비활성화하면 모델이 때때로 도구 호출을 일반 텍스트로 내보내거나 내부 XML 태그를 표시되는 출력에 포함할 수 있으므로, 가능한 경우 사고를 활성화한 상태에서 더 낮은 effort 수준을 사용하는 것이 좋으며, 그럴 수 없는 경우 완화 방법은 사고를 비활성화한 상태로 실행을 참조하세요.
사고 비활성화는 high effort로 제한됨: thinking: {type: "disabled"}로 사고를 끌 수 있지만, effort 수준이 high 이하인 경우에만 가능합니다. thinking: {type: "disabled"}를 effort xhigh 또는 max와 결합한 요청은 400 오류를 반환합니다. Claude Opus 4.8은 이 조합을 허용하므로 마이그레이션 전에 사고를 비활성화하는 요청을 점검하세요.
이 검사는 각 요청에서 적용됩니다. 모든 요청의 effort 및 사고 구성은 독립적으로 검증되므로, 대화의 이전 요청이 허용되었더라도 사고가 비활성화된 상태에서 effort를 xhigh 또는 max로 높이는 요청은 거부됩니다.
이전 (Claude Opus 4.8에서 허용, Claude Opus 5에서 거부):
client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
thinking={"type": "disabled"},
output_config={"effort": "xhigh"},
messages=[{"role": "user", "content": "..."}],
)이후 (Claude Opus 5), thinking 필드를 제거하여 사고를 다시 활성화하거나:
client.messages.create(
model="claude-opus-5",
max_tokens=16000,
output_config={"effort": "xhigh"}, # thinking is on by default
messages=[{"role": "user", "content": "..."}],
)사고를 비활성화한 상태로 유지하고 effort를 낮추세요:
client.messages.create(
model="claude-opus-5",
max_tokens=16000,
thinking={"type": "disabled"},
output_config={"effort": "high"}, # or "medium", "low"
messages=[{"role": "user", "content": "..."}],
)다음은 필수는 아니지만 경험을 개선합니다:
성능이 중요한 작업에 max effort 테스트: Claude Opus 5는 전체 effort 수준 세트(low, medium, high, xhigh, max)를 지원합니다. 토큰 소비보다 최대 성능이 더 중요한 경우 max effort를 테스트하세요. 가장 까다로운 작업에서 이점을 제공할 수 있지만 토큰 사용량 증가에 따른 수익 감소를 보일 수 있으며 더 간단한 작업에서는 과도한 사고를 하는 경향이 있습니다. xhigh 또는 max effort로 실행하는 경우 모델이 사고하고 행동할 공간을 확보하도록 큰 max_tokens를 설정하세요. 64k 토큰에서 시작하여 조정하세요.
자동 폴백 고려: Claude Opus 5는 사이버 보안 안전 분류기와 함께 제공되며, 사이버 카테고리 거부는 Claude Opus 4.8로 폴백할 수 있습니다. 거부된 요청을 다른 모델에서 자동으로 다시 실행하려면 "default" 모드(fallbacks: "default")와 함께 fallbacks 매개변수를 고려하세요. 이는 수동으로 관리되는 모델 목록 대신 거부 카테고리를 기반으로 권장 폴백 모델을 선택합니다. 서버 측 폴백은 베타입니다. "default" 모드에는 server-side-fallback-2026-07-01 베타 헤더가 필요합니다. 거부 및 폴백을 참조하세요.
더 짧은 프롬프트 캐싱: Claude Opus 5의 최소 캐시 가능 프롬프트 길이는 512 토큰으로, Claude Opus 4.8의 1,024 토큰에서 감소했습니다. Claude Opus 4.8에서 캐시하기에 너무 짧았던 프롬프트가 이제 코드 변경 없이 캐시 항목을 생성할 수 있습니다. 모델별 최소값은 프롬프트 캐싱을 참조하세요.
대화 중 도구 변경(베타): 이전 턴의 프롬프트 캐시 적중을 무효화하지 않고 대화 턴 사이에 도구를 추가하거나 제거할 수 있습니다. 베타 헤더 mid-conversation-tool-changes-2026-07-01을 전송하세요. 이는 작업이 진행됨에 따라 도구를 점진적으로 노출하거나 종료하는 에이전트 워크로드에 유용합니다. 이 기능이 없으면 변경된 도구 목록이 캐시된 접두사를 무효화합니다.
길이 및 상세도 프롬프트 재조정: Claude Opus 5에서는 기본 표시 응답과 작성된 결과물이 Claude Opus 4.8보다 길게 실행되며, effort를 낮추면 사고 볼륨은 줄어들지만 표시되는 응답을 안정적으로 단축하지는 않습니다. 대신 간결함이나 목표 길이를 명시적으로 프롬프트하세요. 응답 길이 및 상세도 및 작성된 결과물 길이를 참조하세요.
이전 모델에서 가져온 검증 지침 제거 및 범위 제한: Claude Opus 5는 지시받지 않아도 자체 작업을 검증하므로, 이전 모델에 맞게 조정된 프롬프트에서 가져온 명시적 검증 또는 자체 점검 지침을 제거하세요. 그대로 두면 과도한 검증이 발생합니다. 좁은 작업의 경우 작업 범위를 명시적으로 제한하세요. 멀티 에이전트 프레임워크에서는 Claude Opus 5가 이전 모델보다 더 쉽게 위임하므로 어떤 시나리오에서 위임이 필요한지 명시적으로 안내하거나 서브에이전트 수를 제한하세요. 작업 범위 및 과도한 검증 및 서브에이전트 생성 제어를 참조하세요.
claude-opus-4-8에서 claude-opus-5로 업데이트하세요.thinking 필드 없이 실행했던 워크로드를 검토하세요. Claude Opus 5에서는 사고와 함께 실행됩니다. 총 출력(사고와 응답 텍스트 합계)에 대한 하드 제한으로 유지되는 max_tokens를 다시 검토하거나, 이전 동작을 유지하려면 effort high 이하에서 thinking: {type: "disabled"}를 전달하세요. 사고를 비활성화하는 경우 나타날 수 있는 출력 아티팩트와 프롬프팅 완화 방법은 사고를 비활성화한 상태로 실행을 검토하세요.xhigh 또는 max와 함께 thinking: {type: "disabled"}를 사용하면 각 요청에서 적용되는 400 오류가 반환됩니다. 사고를 다시 활성화하거나 effort를 high 이하로 낮추세요.effort 설정을 다시 평가하세요. 이전 모델에 맞게 조정된 설정을 그대로 가져오지 말고 자체 평가에서 새로운 effort 스윕을 실행하세요. low 및 medium effort는 비용 및 지연 시간 제어로 테스트할 가치가 있으며, 토큰 소비보다 최대 성능이 더 중요한 경우 max effort를 테스트하세요. xhigh 또는 max effort로 실행하는 경우 시작점으로 max_tokens를 최소 64k로 높이세요.stop_reason: "refusal"을 처리하고, 거부된 요청을 권장 폴백 모델에서 자동으로 다시 실행하려면 fallbacks: "default"(베타)를 고려하세요.Claude Opus 5는 기존 Claude Opus 4.7 프롬프트 및 평가에서 별도의 조정 없이도 강력한 성능을 발휘하며, 입력 토큰 100만 개당 $5, 출력 토큰 100만 개당 $25의 동일한 가격으로 제공됩니다. 1M 토큰 컨텍스트 윈도우, 128k 최대 출력 토큰, 적응형 사고, 프롬프트 캐싱, 배치 처리, Files API, PDF 지원, 비전, 서버 측 및 클라이언트 측 도구를 포함하여 Claude Opus 4.7과 동일한 기능 세트를 지원하지만, 두 가지 예외가 있습니다. 웹 가져오기는 Claude Opus 5에서 사용할 수 없으며, Priority Tier는 Claude Opus 5에서 지원되지 않습니다. 또한 대화 중 시스템 메시지가 추가되었으며 거부 중지 세부 정보가 공개적으로 문서화되었습니다.
# Opus 마이그레이션
model = "claude-opus-4-7" # Before
model = "claude-opus-5" # After사고가 기본적으로 활성화됨: Claude Opus 4.7에서는 thinking 필드가 없는 요청이 사고 없이 실행되지만, Claude Opus 5에서는 동일한 요청이 적응형 사고와 함께 실행됩니다. max_tokens는 사고와 응답 텍스트를 합한 총 출력에 대한 하드 제한으로 유지되므로, Claude Opus 4.7에서 사고 없이 실행되던 워크로드에 대해 이 값을 다시 검토하세요. 이전 동작을 유지하려면 다음 항목의 노력 수준 상한을 조건으로 thinking: {type: "disabled"}를 전달하세요. 사고가 비활성화된 경우 모델이 간혹 도구 호출을 일반 텍스트로 내보내거나 내부 XML 태그를 가시적 출력에 포함할 수 있으므로, 가능한 경우 사고를 활성화한 상태에서 더 낮은 노력 수준을 사용하는 것이 좋으며, 그럴 수 없는 경우의 완화 방법은 사고를 비활성화한 상태로 실행을 참조하세요.
사고 비활성화는 high 노력 수준까지만 허용됨: thinking: {type: "disabled"}로 사고를 끌 수 있지만, 노력 수준이 high 이하인 경우에만 가능합니다. thinking: {type: "disabled"}를 노력 수준 xhigh 또는 max와 결합한 요청은 400 오류를 반환합니다. Claude Opus 4.7은 이 조합을 허용하므로, 마이그레이션하기 전에 사고를 비활성화하는 요청을 점검하세요.
이 검사는 각 요청마다 적용됩니다. 모든 요청의 노력 및 사고 구성은 독립적으로 검증되므로, 대화의 이전 요청이 허용되었더라도 사고가 비활성화된 상태에서 노력 수준을 xhigh 또는 max로 높이는 요청은 거부됩니다.
이전 (Claude Opus 4.7에서는 허용, Claude Opus 5에서는 거부):
client.messages.create(
model="claude-opus-4-7",
max_tokens=16000,
thinking={"type": "disabled"},
output_config={"effort": "xhigh"},
messages=[{"role": "user", "content": "..."}],
)이후 (Claude Opus 5), thinking 필드를 제거하여 사고와 함께 실행하거나:
client.messages.create(
model="claude-opus-5",
max_tokens=16000,
output_config={"effort": "xhigh"}, # thinking is on by default
messages=[{"role": "user", "content": "..."}],
)사고를 비활성화한 상태로 유지하고 노력 수준을 낮추세요:
client.messages.create(
model="claude-opus-5",
max_tokens=16000,
thinking={"type": "disabled"},
output_config={"effort": "high"}, # or "medium", "low"
messages=[{"role": "user", "content": "..."}],
)다음 항목은 호환성이 깨지는 변경 사항이 아니며, 모델 ID를 교체한 후 확인할 가치가 있는 동작 차이를 설명합니다.
샘플링 매개변수 (변경 없음): temperature, top_p 또는 top_k를 기본값이 아닌 값으로 설정하면 Claude Opus 4.7과 마찬가지로 Claude Opus 5에서도 400 오류가 반환됩니다. SDK 요청 타입은 이전 모델과의 호환성을 위해 여전히 이러한 필드를 정의하므로 이를 설정하는 코드는 타입 검사를 통과하지만, API는 서버 측에서 요청을 거부합니다. Opus 4.7로 마이그레이션할 때 이러한 매개변수를 제거했다면 추가 변경이 필요하지 않습니다.
노력 기본값은 high: Claude Opus 5의 노력 매개변수 기본값은 Claude API 및 Claude Code에서 high입니다. 이미 노력 수준을 명시적으로 설정한 경우 해당 설정은 변경되지 않습니다.
노력 수준 재조정: 각 노력 수준에 할당되는 토큰이 Claude Opus 4.7과 비교하여 Claude Opus 5에서 변경되었으며, Claude Opus 5는 전체 노력 수준 세트(low, medium, high, xhigh, max)를 지원합니다. Claude Opus 4.7에 맞춰 조정된 설정을 그대로 가져오기보다는 자체 평가에서 새로운 노력 수준 스윕을 실행하세요. low 및 medium 노력 수준은 비용 및 지연 시간 제어 수단으로 테스트할 가치가 있으며, 토큰 소비보다 최대 성능이 더 중요한 경우 max 노력 수준을 테스트하세요. xhigh 또는 max 노력 수준으로 실행하는 경우, 모델이 사고하고 행동할 여유를 갖도록 큰 max_tokens를 설정하세요. 64k 토큰에서 시작하여 조정하세요. 노력을 참조하세요.
1M 컨텍스트 윈도우가 기본값: Claude Opus 5는 베타 헤더나 긴 컨텍스트 프리미엄 없이 기본적으로 전체 1M 토큰 컨텍스트 윈도우를 제공합니다. 클라이언트가 이전 모델과의 호환성을 위해 컨텍스트 윈도우 베타 헤더를 전달하는 경우, Claude Opus 5에서는 이를 제거할 수 있습니다.
대화 중 시스템 메시지: Claude Opus 5는 messages 배열에서 사용자 턴 바로 뒤에 role: "system" 메시지를 허용합니다(배치 규칙 적용). 처음부터 적용되는 지침에는 최상위 system 필드를 사용하세요. Claude Opus 4.7은 messages의 role: "system"을 400 오류로 거부합니다. 지침을 업데이트하기 위해 전체 메시지 기록을 재구성하는 코드 경로를 유지하고 있다면, 이를 단순화하고 이전 턴에 대한 프롬프트 캐시 적중을 유지할 수 있습니다.
거부 중지 세부 정보: 거부 응답의 stop_details 객체(Claude Opus 4.7부터 사용 가능)가 이제 공개적으로 문서화되었습니다. 모델이 요청을 거부할 때 기존 refusal 중지 이유에 더해 거부 카테고리를 식별합니다. 베타 헤더가 필요하지 않으며 옵트아웃도 없습니다. 중지 이유 처리를 참조하세요.
더 낮은 프롬프트 캐싱 최소값: Claude Opus 5에서 캐시 가능한 최소 프롬프트 길이는 512 토큰으로, Claude Opus 4.7보다 낮습니다. Claude Opus 4.7에서 캐시하기에 너무 짧았던 프롬프트가 이제 코드 변경 없이 캐시 항목을 생성할 수 있습니다. 모델별 최소값은 프롬프트 캐싱을 참조하세요.
빠른 모드: Claude Opus 5는 빠른 모드(연구 프리뷰)를 지원합니다. 빠른 모드는 Claude Opus 4.7에서 사용할 수 없으며, speed: "fast"가 포함된 요청은 오류를 반환합니다. speed: "fast" 매개변수와 fast-mode-2026-02-01 베타 헤더는 Claude Opus 5에서 변경 없이 작동합니다.
다음은 필수는 아니지만 경험을 개선할 수 있습니다.
자동 폴백 고려: Claude Opus 5는 사이버 보안 안전 분류기와 함께 제공되며, 사이버 카테고리 거부는 Claude Opus 4.8로 폴백될 수 있습니다. 거부된 요청을 다른 모델에서 자동으로 재실행하려면 "default" 모드(fallbacks: "default")와 함께 fallbacks 매개변수를 고려하세요. 이 모드는 수동으로 관리되는 모델 목록 대신 거부 카테고리를 기반으로 권장 폴백 모델을 선택합니다. 서버 측 폴백은 베타 상태이며, "default" 모드에는 server-side-fallback-2026-07-01 베타 헤더가 필요합니다. 거부 및 폴백을 참조하세요.
대화 중 도구 변경 (베타): 이전 턴에 대한 프롬프트 캐시 적중을 무효화하지 않고 대화 턴 사이에 도구를 추가하거나 제거할 수 있습니다. 베타 헤더 mid-conversation-tool-changes-2026-07-01을 전송하세요. 이는 작업이 진행됨에 따라 도구를 점진적으로 노출하거나 폐기하는 에이전트 워크로드에 유용합니다. 이 기능이 없으면 변경된 도구 목록이 캐시된 접두사를 무효화합니다.
길이 및 상세도 프롬프트 재조정: Claude Opus 5의 기본 가시적 응답 및 작성된 산출물은 이전 Opus 모델보다 더 길게 실행되며, 노력 수준을 낮추면 사고 분량은 줄어들지만 가시적 응답이 안정적으로 짧아지지는 않습니다. 대신 간결함이나 목표 길이를 명시적으로 프롬프트하세요. 응답 길이 및 상세도 및 작성된 산출물 길이를 참조하세요.
이전 모델에서 가져온 검증 지침 제거 및 범위 제한: Claude Opus 5는 지시받지 않아도 자체 작업을 검증하므로, 이전 모델에 맞춰 조정된 프롬프트에서 가져온 명시적 검증 또는 자체 점검 지침을 제거하세요. 이를 남겨두면 과도한 검증이 발생합니다. 좁은 범위의 작업에는 작업 범위를 명시적으로 제한하세요. 멀티 에이전트 프레임워크에서는 Claude Opus 5가 이전 모델보다 더 쉽게 위임하므로, 어떤 시나리오에서 위임이 필요한지 명시적으로 안내하거나 하위 에이전트 수를 제한하세요. 작업 범위 및 과도한 검증 및 하위 에이전트 생성 제어를 참조하세요.
claude-opus-4-7에서 claude-opus-5로 업데이트하세요(또는 별칭을 업데이트하세요).thinking 필드 없이 실행되던 워크로드를 검토하세요. Claude Opus 5에서는 사고와 함께 실행됩니다. 총 출력(사고 및 응답 텍스트)에 대한 하드 제한으로 유지되는 max_tokens를 다시 검토하거나, 이전 동작을 유지하려면 노력 수준 high 이하에서 thinking: {type: "disabled"}를 전달하세요. 사고를 비활성화하는 경우, 나타날 수 있는 출력 아티팩트와 이에 대한 프롬프트 완화 방법은 사고를 비활성화한 상태로 실행을 검토하세요.xhigh 또는 max와 함께 thinking: {type: "disabled"}를 사용하면 각 요청마다 적용되는 400 오류가 반환됩니다. 사고를 다시 활성화하거나 노력 수준을 high 이하로 낮추세요.effort 설정을 재평가하세요. Claude Opus 4.7에 맞춰 조정된 설정을 그대로 가져오기보다는 자체 평가에서 새로운 노력 스윕을 실행하세요. low 및 medium 노력 수준을 비용 및 지연 시간 제어 수단으로 테스트하고, 토큰 소비보다 최대 성능이 더 중요한 경우 max 노력 수준을 테스트하세요. xhigh 또는 max 노력 수준으로 실행하는 경우 max_tokens를 시작점으로 최소 64k로 높이세요.stop_details를 읽는지 확인하고(Claude Opus 4.7부터 사용 가능, 이제 공개적으로 문서화됨), 거부된 요청을 권장 폴백 모델에서 자동으로 재실행하려면 fallbacks: "default"(베타)를 고려하세요.speed: "fast" 및 fast-mode-2026-02-01 베타 헤더는 Claude Opus 5에서 변경 없이 작동합니다.Claude Opus 5는 기존 Claude Opus 4.6 프롬프트 및 평가에서 동일한 가격으로 즉시 사용 가능한 강력한 성능을 제공하지만, 마이그레이션 시 알아두어야 할 몇 가지 동작 및 API 변경 사항이 있습니다. 이러한 변경 사항 대부분은 Claude Opus 4.7에서 적용되었으며, 두 가지 추가 변경 사항(기본적으로 사고 활성화, 사고 비활성화 시 effort 상한)은 Claude Opus 5에서 적용됩니다. 이 모든 내용이 아래에 다루어져 있으므로, Claude Opus 4.6에서 바로 마이그레이션하는 코드의 경우 이 섹션만으로 충분합니다. Claude Opus 5는 다음을 포함하여 Claude Opus 4.6과 동일한 기능 세트를 지원합니다:
두 가지 예외: 웹 가져오기는 Claude Opus 5에서 사용할 수 없으며, Priority Tier는 Claude Opus 5에서 지원되지 않습니다.
# Opus 마이그레이션
model = "claude-opus-4-6" # Before
model = "claude-opus-5" # After확장 사고 제거: thinking: {type: "enabled", budget_tokens: N}은 Claude Opus 4.7 이상 모델에서 더 이상 지원되지 않으며 400 오류를 반환합니다. 적응형 사고(thinking: {type: "adaptive"})로 전환하고 effort 매개변수를 사용하여 사고 깊이를 제어하세요. Claude Opus 5에서는 적응형 사고가 기본적으로 활성화되어 있습니다: thinking: {type: "adaptive"}는 유효하며 thinking 필드를 완전히 생략하는 것과 동일합니다(다음 항목 참조).
이전 (Claude Opus 4.6):
client.messages.create(
model="claude-opus-4-6",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 10000},
messages=[{"role": "user", "content": "..."}],
)이후 (Claude Opus 5):
client.messages.create(
model="claude-opus-5",
max_tokens=16000,
thinking={"type": "adaptive"},
output_config={"effort": "high"}, # or "max", "xhigh", "medium", "low"
messages=[{"role": "user", "content": "..."}],
)적응형 사고는 프롬프팅과 effort 매개변수를 통해 조정할 수 있습니다. Effort 수준 선택하기를 참조하세요.
기본적으로 사고 활성화: Claude Opus 4.6 및 Claude Opus 4.7에서는 thinking 필드가 없는 요청이 사고 없이 실행되지만, Claude Opus 5에서는 동일한 요청이 적응형 사고와 함께 실행됩니다. max_tokens는 사고와 응답 텍스트를 합한 총 출력에 대한 하드 제한으로 유지되므로, 사고 없이 실행되던 워크로드에 대해 이 값을 다시 검토하세요. 이전 동작을 유지하려면 다음 항목의 effort 상한을 조건으로 thinking: {type: "disabled"}를 전달하세요. 사고가 비활성화된 경우 모델이 간혹 도구 호출을 일반 텍스트로 출력하거나 내부 XML 태그를 가시적 출력에 포함할 수 있으므로, 가능한 경우 사고를 활성화한 상태에서 낮은 effort 수준을 사용하는 것이 좋으며, 그렇지 못한 경우의 완화 방법은 사고를 비활성화한 상태로 실행하기를 참조하세요.
사고 비활성화는 high effort로 제한: thinking: {type: "disabled"}로 사고를 끌 수 있지만, effort 수준이 high 이하인 경우에만 가능합니다. thinking: {type: "disabled"}를 effort xhigh 또는 max와 함께 사용하는 요청은 Claude Opus 5에서 각 요청마다 400 오류를 반환합니다. 마이그레이션 전에 사고를 비활성화하는 요청을 점검하세요: 사고를 다시 활성화하거나 effort를 high 이하로 낮추세요.
샘플링 매개변수 제거: Claude Opus 5를 포함한 Claude Opus 4.7 이상 모델에서 temperature, top_p, top_k를 기본값이 아닌 값으로 설정하면 400 오류가 반환됩니다. 가장 안전한 마이그레이션 방법은 요청 페이로드에서 이러한 매개변수를 완전히 생략하는 것입니다. Claude Opus 5에서 모델 동작을 유도하는 권장 방법은 프롬프팅입니다. 결정론적 동작을 위해 temperature = 0을 사용했다면, 이전 모델에서도 동일한 출력을 보장한 적이 없다는 점에 유의하세요.
사고 콘텐츠 기본적으로 생략: Claude Opus 4.7 이상 모델에서 사고 블록은 여전히 응답 스트림에 나타나지만, 명시적으로 옵트인하지 않는 한 thinking 필드는 비어 있습니다. 이는 요약된 사고 텍스트를 반환하는 것이 기본값이었던 Claude Opus 4.6과 비교하여 조용히 변경된 사항입니다. 요약된 사고 콘텐츠를 복원하려면 thinking.display를 "summarized"로 설정하세요:
thinking = {
"type": "adaptive",
"display": "summarized",
}Claude Opus 4.7 이상 모델에서 기본값은 "omitted"입니다. 제품이 사용자에게 추론 과정을 스트리밍하는 경우, 새로운 기본값은 출력이 시작되기 전 긴 일시 정지로 나타납니다. 사고 중 가시적인 진행 상황을 복원하려면 display: "summarized"를 설정하세요. 자세한 내용은 사고 표시 제어하기를 참조하세요.
업데이트된 토큰 계산: Claude Opus 4.7은 새로운 토크나이저를 도입했으며, Claude Opus 5를 포함한 이후 Opus 모델도 이를 사용합니다. 이는 다양한 작업에서 성능 향상에 기여하며, Claude Opus 4.7 이전 모델과 비교하여 텍스트 처리 시 약 1배에서 1.35배 더 많은 토큰을 사용할 수 있습니다(콘텐츠에 따라 최대 약 35% 증가).
/v1/messages/count_tokens는 Claude Opus 5에 대해 Claude Opus 4.6과 다른 토큰 수를 반환합니다. 토큰 효율성은 워크로드 형태에 따라 달라질 수 있습니다.
프롬프팅 개입, task_budget, effort는 비용을 제어하고 적절한 토큰 사용을 보장하는 데 도움이 될 수 있습니다. 이러한 제어는 모델 지능과 트레이드오프 관계일 수 있습니다. 압축 트리거를 포함하여 추가 여유 공간을 확보하도록 max_tokens 매개변수를 업데이트하세요. Claude Opus 5는 장문 컨텍스트 프리미엄 없이 표준 API 가격으로 1M 컨텍스트 윈도우를 제공합니다.
프리필 제거 (Opus 4.6에서 이어짐): Claude Opus 5를 포함한 Claude Opus 4.7 이상 모델에서 어시스턴트 메시지를 프리필하면 400 오류가 반환됩니다. 대신 구조화된 출력, 시스템 프롬프트 지침, 또는 output_config.format을 사용하세요.
effort 매개변수를 사용하면 Claude의 지능과 토큰 소비 간의 균형을 조정하여, 더 빠른 속도와 낮은 비용을 위해 성능을 트레이드오프할 수 있습니다. Claude Opus 5는 전체 effort 수준 세트를 지원하며 기본값은 high입니다. 이전 모델에 맞춰 조정된 설정을 그대로 가져오기보다는 자체 평가에서 새로운 effort 스윕을 실행하세요:
max: 가장 까다로운 작업에서 성능 향상을 제공할 수 있지만, 토큰 사용량 증가로 인한 수익 체감이 나타날 수 있으며 더 간단한 작업에서는 과도한 사고로 이어질 수 있습니다. 토큰 소비보다 최대 성능이 더 중요한 경우에 테스트하세요.xhigh: 기본값보다 더 깊은 사고가 필요한 장기 실행 에이전트 및 코딩 작업을 위한 확장된 성능입니다.high: 기본값입니다. 대부분의 작업에서 토큰 사용량과 지능의 균형을 맞춥니다.medium: 기본값에서 한 단계 낮춘 비용 절감 옵션으로, 비용 및 지연 시간 제어를 위해 테스트해 볼 가치가 있습니다.low: 가장 효율적입니다. 짧고 범위가 제한된 작업 및 지연 시간에 민감한 워크로드에 사용하세요.xhigh 또는 max effort로 실행하는 경우, 모델이 사고하고 행동할 공간을 확보하도록 큰 max_tokens를 설정하세요. 64k 토큰에서 시작하여 조정하세요. Effort는 이전 어떤 Opus 모델보다 이 모델에서 더 중요합니다. 업그레이드 시 적극적으로 실험해 보세요.
Claude Opus 4.7은 API 주요 변경 사항은 아니지만 프롬프트 업데이트나 스캐폴딩 제거가 필요할 수 있는 여러 동작 차이를 Claude Opus 4.6과 비교하여 도입했습니다. 이러한 변경 사항은 아래에 명시된 조정 사항과 함께 Claude Opus 5로 이어집니다.
사용 사례에 따라 응답 길이가 달라짐: Claude Opus 4.7은 고정된 상세도를 기본값으로 사용하는 대신, 작업의 복잡성을 판단하여 응답 길이를 조정합니다. 이는 일반적으로 간단한 조회에서는 더 짧은 답변을, 개방형 분석에서는 훨씬 더 긴 답변을 의미합니다.
제품이 특정 스타일이나 출력 상세도에 의존하는 경우 프롬프트를 조정해야 할 수 있습니다. 예를 들어, 상세도를 줄이려면 다음을 추가하세요: "간결하고 집중된 응답을 제공하세요. 필수적이지 않은 맥락은 건너뛰고 예시는 최소화하세요." 특정 유형의 과도한 설명이 보이면 이를 방지하기 위한 대상 지침을 프롬프트에 추가하세요.
Claude가 적절한 수준의 간결함으로 소통하는 방법을 보여주는 긍정적 예시는 모델에게 하지 말아야 할 것을 알려주는 부정적 예시나 지침보다 더 효과적인 경향이 있습니다. Claude Opus 5에서는 기본 가시적 응답과 작성된 결과물이 이전 Opus 모델보다 더 길게 나오며, effort를 낮추면 사고량은 줄어들지만 가시적 응답이 안정적으로 짧아지지는 않습니다. 간결함이나 목표 길이를 명시적으로 프롬프트하세요. 응답 길이 및 상세도를 참조하세요.
더 문자 그대로의 지침 따르기: Claude Opus 4.7은 특히 낮은 effort 수준에서 Claude Opus 4.6보다 프롬프트를 더 문자 그대로, 명시적으로 해석합니다. 한 항목에 대한 지침을 다른 항목으로 조용히 일반화하지 않으며, 요청하지 않은 사항을 추론하지 않습니다. 이러한 문자 그대로의 해석의 장점은 정밀성과 혼란 감소입니다. 신중하게 조정된 프롬프트, 구조화된 추출, 예측 가능한 동작이 필요한 파이프라인이 있는 API 사용 사례에서 일반적으로 더 나은 성능을 보입니다. Claude Opus 5로 마이그레이션할 때 프롬프트 및 하네스 검토가 특히 도움이 될 수 있습니다.
더 직접적인 어조: 모든 새 모델과 마찬가지로 장문 작성의 산문 스타일이 달라질 수 있습니다. Claude Opus 4.7은 Claude Opus 4.6의 더 따뜻한 스타일에 비해 더 직접적이고 의견이 뚜렷하며, 검증 중심의 표현과 이모지가 적습니다. 제품이 특정 어조에 의존하는 경우 새로운 기준에 맞춰 스타일 프롬프트를 재평가하세요.
에이전트 트레이스에 내장된 진행 상황 업데이트: Claude Opus 4.7은 긴 에이전트 트레이스 전반에 걸쳐 사용자에게 더 정기적이고 고품질의 업데이트를 제공합니다. 중간 상태 메시지를 강제하기 위한 스캐폴딩("도구 호출 3회마다 진행 상황을 요약하세요")을 추가했다면 제거해 보세요. Claude Opus 4.7의 사용자 대상 업데이트의 길이나 내용이 사용 사례에 잘 맞지 않는다면, 프롬프트에서 이러한 업데이트가 어떻게 보여야 하는지 명시적으로 설명하고 예시를 제공하세요.
서브에이전트 생성 변경: Claude Opus 4.7은 기본적으로 Claude Opus 4.6보다 더 적은 서브에이전트를 생성하는 경향이 있는 반면, Claude Opus 5는 이전 모델보다 더 쉽게 서브에이전트에 위임합니다. 이 동작은 프롬프팅을 통해 양방향으로 조정할 수 있습니다. 서브에이전트가 바람직한 경우에 대한 명시적 지침을 제공하거나 서브에이전트 수를 제한하세요. 서브에이전트 생성 제어하기를 참조하세요.
더 엄격한 effort 보정: Claude Opus 4.6에서 의미 있게 변경되어, Claude Opus 4.7은 특히 낮은 수준에서 effort 수준을 엄격하게 준수합니다. low 및 medium에서 모델은 요청된 것 이상을 수행하기보다는 요청된 범위로 작업을 제한합니다.
이는 지연 시간과 비용에 좋지만, low effort로 실행되는 중간 정도 복잡한 작업에서는 사고 부족의 위험이 있습니다. 복잡한 문제에서 얕은 추론이 관찰되면 프롬프팅으로 우회하기보다는 effort를 high 또는 xhigh로 높이세요.
지연 시간 때문에 effort를 low로 유지해야 하는 경우 대상 지침을 추가하세요: "이 작업은 다단계 추론이 필요합니다. 응답하기 전에 문제를 신중하게 생각하세요." Claude Opus 4.7의 권장 effort 수준을 참조하세요.
기본적으로 더 적은 도구 호출: Claude Opus 4.7은 Claude Opus 4.6보다 도구를 덜 자주 사용하고 추론을 더 많이 사용하는 경향이 있습니다. 이는 대부분의 경우 더 나은 결과를 생성합니다.
도구 사용을 늘리려면 effort 설정을 높이세요. high 또는 xhigh effort 설정은 에이전트 검색 및 코딩에서 상당히 더 많은 도구 사용을 보여줍니다. 또한 모델에게 도구를 언제, 어떻게 적절히 사용해야 하는지 명시적으로 지시하도록 프롬프트를 조정할 수 있습니다.
실시간 사이버 보안 안전장치: Claude Opus 4.7에 새로 추가된 기능으로, 금지되거나 고위험 주제와 관련된 요청은 거부로 이어질 수 있습니다. 침투 테스트, 취약점 연구, 레드팀 활동과 같은 합법적인 보안 작업의 경우 Cyber Verification Program에 신청하여 제한 완화를 요청하세요. 배경 정보는 안전장치, 경고 및 이의 제기를 참조하세요.
고해상도 이미지 지원: Claude Opus 4.7은 고해상도 이미지를 지원하는 최초의 Claude 모델입니다. 최대 이미지 해상도는 긴 변 기준 2,576픽셀로, 이전 모델의 1,568픽셀에서 증가했습니다. 이는 비전 중심 워크로드에서 성능 향상을 제공하며 특히 컴퓨터 사용, 스크린샷 이해, 문서 분석에 유용합니다.
고해상도 지원은 자동으로 적용되며 베타 헤더나 클라이언트 측 옵트인이 필요하지 않습니다. 계획해야 할 두 가지 사항:
max_tokens 및 비용 예상치를 재조정하거나, 추가 정밀도가 필요하지 않은 경우 전송 전에 다운샘플링하세요.자세한 내용은 Claude Opus 4.7의 고해상도 이미지 지원을 참조하세요.
다음은 필수는 아니지만 경험을 개선합니다:
max_tokens 재평가: 동일한 텍스트가 Claude Opus 4.7 이상 모델에서 더 높은 토큰 수를 생성하므로, 압축 트리거를 포함하여 추가 여유 공간을 확보하도록 max_tokens 매개변수를 업데이트하세요. 프롬프팅 개입, task_budget, effort는 비용을 제어하고 적절한 토큰 사용을 보장하는 데 도움이 될 수 있습니다.
토큰 수 예상치 점검: 클라이언트 측에서 토큰을 추정하거나 고정된 토큰 대 문자 비율을 가정하는 모든 코드 경로는 Claude Opus 5에 대해 다시 테스트해야 합니다. 토큰 계산 엔드포인트를 사용하여 확인하세요.
작업 예산 도입 (베타): Claude Opus 4.7은 작업 예산을 도입했습니다. 이러한 예산을 통해 사고, 도구 호출, 도구 결과, 최종 출력을 포함한 전체 에이전트 루프에 사용할 수 있는 토큰 수를 Claude에게 알릴 수 있습니다. 모델은 실행 중인 카운트다운을 보고 이를 사용하여 작업의 우선순위를 정하고 예산이 소진됨에 따라 작업을 원활하게 마무리합니다. 사용하려면 베타 헤더 task-budgets-2026-03-13을 설정하고 출력 구성에 다음을 추가하세요:
output_config = {
"effort": "high",
"task_budget": {"type": "tokens", "total": 128000},
}사용 사례에 맞는 다양한 작업 예산을 실험해야 할 수 있습니다. 모델에 너무 제한적인 작업 예산이 주어지면 예산을 제약 조건으로 언급하면서 작업을 덜 철저하게 완료할 수 있습니다.
품질이 속도보다 더 중요한 개방형 에이전트 작업의 경우 작업 예산을 설정하지 마세요. 모델이 토큰 할당량에 맞춰 작업 범위를 조정해야 하는 워크로드에만 작업 예산을 사용하세요. 작업 예산의 최소값은 20k 토큰입니다.
작업 예산은 하드 상한이 아니라 모델이 인지하는 제안입니다. 이는 max_tokens와 다릅니다:
task_budget: 전체 에이전트 루프에 걸친 권고성 상한입니다. 모델이 이를 보고 스스로 속도를 조절하는 데 사용합니다.max_tokens: 생성된 토큰에 대한 요청당 하드 상한입니다. 모델에 전달되지 않으므로 모델은 이를 인지하지 못합니다.모델이 스스로 조절하기를 원할 때는 task_budget을 사용하고, 사용량을 제한하는 하드 상한으로는 max_tokens를 사용하세요.
max 또는 xhigh effort에서 큰 max_tokens 설정: Claude Opus 4.7 이상 모델을 max 또는 xhigh effort로 실행하는 경우, 모델이 서브에이전트와 도구 호출 전반에 걸쳐 사고하고 행동할 공간을 확보하도록 큰 최대 출력 토큰 예산을 설정하세요. 64k 토큰에서 시작하여 조정하세요.
고해상도가 불필요한 경우 이미지 다운샘플링: Claude Opus 4.7 이상 모델은 최대 2576px / 3.75MP 이미지를 지원합니다. 고해상도 이미지는 더 많은 토큰을 사용합니다. 추가 이미지 정밀도가 불필요한 경우 토큰 사용량 증가를 피하기 위해 Claude에 전송하기 전에 이미지를 다운샘플링하세요. 이미지 및 비전을 참조하세요.
자동 폴백 고려: Claude Opus 5는 사이버 보안 안전 분류기와 함께 제공되며, 사이버 카테고리 거부는 Claude Opus 4.8로 폴백할 수 있습니다. 거부된 요청을 다른 모델에서 자동으로 다시 실행하려면 "default" 모드(fallbacks: "default")와 함께 fallbacks 매개변수를 고려하세요. 이는 수동으로 관리되는 모델 목록 대신 거부 카테고리를 기반으로 권장 폴백 모델을 선택합니다. 서버 측 폴백은 베타 상태이며, "default" 모드는 server-side-fallback-2026-07-01 베타 헤더가 필요합니다. 거부 및 폴백을 참조하세요.
더 짧은 프롬프트 캐싱: Claude Opus 5에서 캐시 가능한 최소 프롬프트 길이는 512 토큰으로, 이전 Opus 모델보다 낮습니다. 캐시하기에 너무 짧았던 프롬프트가 이제 코드 변경 없이 캐시 항목을 생성할 수 있습니다. 모델별 최소값은 프롬프트 캐싱을 참조하세요.
대화 중 도구 변경 (베타): 이전 턴의 프롬프트 캐시 적중을 무효화하지 않고 대화 턴 사이에 도구를 추가하거나 제거할 수 있습니다. 베타 헤더 mid-conversation-tool-changes-2026-07-01을 전송하세요. 이는 작업이 진행됨에 따라 도구를 점진적으로 노출하거나 폐기하는 에이전트 워크로드에 유용합니다. 이 기능이 없으면 변경된 도구 목록이 캐시된 접두사를 무효화합니다.
이전 모델에서 가져온 검증 지침 제거 및 범위 제한: Claude Opus 5는 지시받지 않아도 자체 작업을 검증하므로, 이전 모델에 맞춰 조정된 프롬프트에서 가져온 명시적 검증 또는 자체 점검 지침을 제거하세요. 그대로 두면 과도한 검증이 발생합니다. 좁은 범위의 작업의 경우 작업 범위를 명시적으로 제한하세요. 작업 범위 및 과도한 검증을 참조하세요.
claude-opus-4-6에서 claude-opus-5로 업데이트하세요(또는 별칭을 업데이트하세요).temperature, top_p, top_k를 제거하세요.thinking: {type: "enabled", budget_tokens: N}을 thinking: {type: "adaptive"}와 effort 매개변수로 교체하거나 thinking 필드를 완전히 제거하세요. Claude Opus 5에서는 적응형 사고가 기본적으로 활성화되어 있습니다.thinking 필드 없이 실행되던 워크로드를 검토하세요: Claude Opus 5에서는 사고와 함께 실행됩니다. 총 출력(사고 및 응답 텍스트)에 대한 하드 제한으로 유지되는 max_tokens를 다시 검토하거나, 이전 동작을 유지하려면 effort high 이하에서 thinking: {type: "disabled"}를 전달하세요.xhigh 또는 max와 함께 thinking: {type: "disabled"}를 사용하면 각 요청마다 400 오류가 반환됩니다. 사고를 다시 활성화하거나 effort를 high 이하로 낮추세요.max_tokens를 다시 조정하세요.xhigh 또는 max effort를 사용하는 경우 시작점으로 max_tokens를 최소 64k로 높이세요.stop_reason: "refusal"을 처리하고, 거부된 요청을 권장 폴백 모델에서 자동으로 다시 실행하려면 fallbacks: "default"(베타)를 고려하세요.Claude Opus 4.5, Opus 4.1 또는 이전 모델에서 Claude Opus 5로 직접 마이그레이션하는 경우, 이 섹션 앞부분의 모든 변경 사항과 함께 Opus 4.5와 Opus 4.7 사이에 적용된 다음 누적 변경 사항을 적용하세요. Opus 4.6에서 마이그레이션하는 경우 이 섹션 앞부분의 변경 사항만으로 충분합니다.
# Opus 마이그레이션
model = "claude-opus-4-5" # Before
model = "claude-opus-5" # After프리필 제거는 Claude Opus 4.6에서 마이그레이션하기 위한 주요 변경 사항에서 다룹니다.
도구 매개변수 인용: Claude Opus 4.6 이상 모델은 도구 호출 인수에서 약간 다른 JSON 문자열 이스케이프를 생성할 수 있습니다(예: 유니코드 이스케이프 또는 슬래시 이스케이프의 다른 처리). 도구 호출 input을 JSON 파서를 사용하지 않고 원시 문자열로 파싱하는 경우 파싱 로직을 확인하세요. 표준 JSON 파서(json.loads() 또는 JSON.parse() 등)는 이러한 차이를 자동으로 처리합니다.
이러한 변경 사항은 Claude Opus 4.7 이상 모델에서의 경험을 개선합니다. (Opus 4.7에서 필수) 로 표시된 항목은 Opus 4.6 출시 당시 선택적 권장 사항이었지만 이제 필수입니다. 나머지는 계속 권장 사항입니다.
적응형 사고로 마이그레이션 (Opus 4.7에서 필수): thinking: {type: "enabled", budget_tokens: N}은 Claude Opus 4.7 이상 모델에서 400 오류를 반환합니다. thinking: {type: "adaptive"}로 전환하고 effort 매개변수를 사용하여 사고 깊이를 제어하세요. Claude Opus 5에서 thinking: {type: "adaptive"}는 thinking 필드를 생략하는 것과 동일하며, 기본적으로 적응형 사고와 함께 실행됩니다. 사고를 참조하세요.
response = client.beta.messages.create(
model="claude-opus-4-5",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 32000},
betas=["interleaved-thinking-2025-05-14"],
messages=[{"role": "user", "content": "Your prompt here"}],
)마이그레이션은 client.beta.messages.create에서 client.messages.create로도 이동한다는 점에 유의하세요. 적응형 사고와 effort는 GA 기능이며 베타 SDK 네임스페이스나 베타 헤더가 필요하지 않습니다.
effort 베타 헤더 제거: effort 매개변수는 이제 GA입니다. 요청에서 betas=["effort-2025-11-24"]를 제거하세요.
세분화된 도구 스트리밍 베타 헤더 제거: 세분화된 도구 스트리밍은 이제 GA입니다. 요청에서 betas=["fine-grained-tool-streaming-2025-05-14"]를 제거하세요.
인터리브 사고 베타 헤더 제거: 적응형 사고는 Claude Opus 4.7, Opus 4.6, Sonnet 4.6에서 인터리브 사고를 자동으로 활성화합니다. 요청에서 betas=["interleaved-thinking-2025-05-14"]를 제거하세요. 이 헤더는 수동 확장 사고를 사용하는 Sonnet 4.6에서 여전히 작동하지만 수동 모드는 지원 중단되었습니다.
output_config.format으로 마이그레이션: 구조화된 출력을 사용하는 경우 output_format={...}을 output_config={"format": {...}}으로 업데이트하세요. 이전 매개변수는 여전히 작동하지만 지원 중단되었으며 향후 모델 릴리스에서 제거될 예정입니다.
Opus 4.1 이하 모델에서 Claude Opus 5로 직접 마이그레이션하는 경우, 이 섹션 앞부분의 모든 변경 사항과 이 하위 섹션의 추가 변경 사항을 적용하세요.
# Opus 4.1에서
model = "claude-opus-4-1-20250805" # Before
model = "claude-opus-5" # After
# Sonnet 3.7에서
model = "claude-3-7-sonnet-20250219" # Before
model = "claude-opus-5" # After샘플링 매개변수 제거
Claude Opus 4.7부터 temperature, top_p, top_k를 기본값이 아닌 값으로 설정하면 400 오류가 반환됩니다. 가장 안전한 마이그레이션 방법은 요청에서 이러한 매개변수를 완전히 생략하고 프롬프팅을 사용하여 모델의 동작을 유도하는 것입니다. 결정론적 동작을 위해 temperature = 0을 사용했다면, 동일한 출력을 보장한 적이 없다는 점에 유의하세요.
# 이전 - Claude 4+ 모델에서는 오류가 발생합니다
response = client.messages.create(
model="claude-3-7-sonnet-20250219",
temperature=0.7,
top_p=0.9, # Non-default sampling params return 400 on Opus 4.7
# ...
)
# 이후
response = client.messages.create(
model="claude-opus-5",
# ...
)도구 버전 업데이트
최신 도구 버전으로 업데이트하세요. undo_edit 명령을 사용하는 모든 코드를 제거하세요.
# 이전
tools = [{"type": "text_editor_20250124", "name": "str_replace_editor"}]
# 이후
tools = [{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]text_editor_20250728 및 str_replace_based_edit_tool을 사용하세요. 자세한 내용은 텍스트 편집기 도구 문서를 참조하세요.code_execution_20260521로 업그레이드하세요. 마이그레이션 지침은 코드 실행 도구 문서를 참조하세요.refusal 중지 이유 처리
refusal 중지 이유를 처리하도록 애플리케이션을 업데이트하세요:
response = client.messages.create(...)
if response.stop_reason == "refusal":
# 거부를 적절히 처리합니다
passmodel_context_window_exceeded 중지 이유 처리
Claude 4.5+ 모델은 요청된 max_tokens 제한이 아니라 컨텍스트 윈도우 제한에 도달하여 생성이 중지될 때 model_context_window_exceeded 중지 이유를 반환합니다. 이 새로운 중지 이유를 처리하도록 애플리케이션을 업데이트하세요:
response = client.messages.create(...)
if response.stop_reason == "model_context_window_exceeded":
# 컨텍스트 윈도우 제한을 적절히 처리
pass도구 매개변수 처리 확인 (후행 줄바꿈)
Claude 4.5+ 모델은 이전에 제거되던 도구 호출 문자열 매개변수의 후행 줄바꿈을 보존합니다. 도구가 도구 호출 매개변수에 대한 정확한 문자열 일치에 의존하는 경우 로직이 후행 줄바꿈을 올바르게 처리하는지 확인하세요.
동작 변경에 맞춰 프롬프트 업데이트
Claude 4+ 모델은 더 간결하고 직접적인 커뮤니케이션 스타일을 가지며 명시적인 지시가 필요합니다. 최적화 지침은 프롬프팅 모범 사례를 검토하세요.
token-efficient-tools-2025-02-19 및 output-128k-2025-02-19를 제거하세요. 모든 Claude 4+ 모델은 토큰 효율적인 도구 사용이 내장되어 있으며 이러한 헤더는 효과가 없습니다.claude-opus-5로 업데이트하세요output_config.format을 사용하세요thinking: {type: "enabled", budget_tokens: N}을 thinking: {type: "adaptive"}와 effort 매개변수로 교체하세요(Opus 4.7에서 400 반환)effort-2025-11-24 베타 헤더를 제거하세요(effort는 이제 GA)fine-grained-tool-streaming-2025-05-14 베타 헤더를 제거하세요interleaved-thinking-2025-05-14 베타 헤더를 제거하세요(적응형 사고가 인터리브 사고를 자동으로 활성화)output_format을 output_config.format으로 마이그레이션하세요(해당하는 경우)temperature, top_p, top_k를 제거하세요(기본값이 아닌 값은 Opus 4.7에서 400 반환)text_editor_20250728, code_execution_20260521)refusal 중지 이유를 처리하세요model_context_window_exceeded 중지 이유를 처리하세요token-efficient-tools-2025-02-19, output-128k-2025-02-19)Claude Opus 5와 Claude Sonnet 5는 동일한 API 인터페이스를 공유합니다. 두 모델 모두 기본적으로 adaptive thinking(적응형 사고)이 활성화된 상태로 실행되며, Claude API와 Claude Code에서 effort 매개변수의 기본값이 high로 설정되어 있고, 기본적으로 1M 토큰 컨텍스트 윈도우와 128k 최대 출력 토큰을 제공하며, 두 모델 모두 Priority Tier를 지원하지 않습니다. 수동 확장 사고와 기본값이 아닌 샘플링 매개변수는 두 모델 모두에서 400 오류를 반환하며, 어시스턴트 프리필도 마찬가지입니다.
model = "claude-sonnet-5" # Before
model = "claude-opus-5" # After가격: Claude Opus 5는 입력 토큰 100만 개당 $5, 출력 토큰 100만 개당 $25로 책정되어 있습니다. Claude Sonnet 5는 입력/출력 토큰 100만 개당 $2/$10로 책정되어 있습니다. 전체 가격은 Claude 가격을 참조하세요.
사고 비활성화는 high effort로 제한됨: Claude Sonnet 5에서는 모든 effort 수준에서 thinking: {type: "disabled"}가 허용됩니다. Claude Opus 5에서는 effort 수준이 high 이하인 경우에만 허용되며, thinking: {type: "disabled"}를 effort xhigh 또는 max와 함께 사용하는 요청은 400 오류를 반환하고 이는 각 요청마다 적용됩니다. 마이그레이션하기 전에 사고를 비활성화하는 요청을 점검하세요.
대화 중간 시스템 메시지: Claude Opus 5는 messages 배열에서 사용자 턴 바로 뒤에 오는 role: "system" 메시지를 허용합니다(배치 규칙 적용). Claude Sonnet 5는 이를 허용하지 않습니다. 지침을 업데이트하기 위해 전체 메시지 기록을 재구성하는 코드 경로를 유지하고 있다면, 이를 단순화하고 이전 턴에 대한 프롬프트 캐시 적중을 유지할 수 있습니다.
Web fetch를 사용할 수 없음: web fetch 도구는 Claude Sonnet 5에서는 사용할 수 있지만 Claude Opus 5에서는 사용할 수 없습니다.
claude-sonnet-5에서 claude-opus-5로 업데이트하세요.xhigh 또는 max와 함께 thinking: {type: "disabled"}를 사용하면 Claude Opus 5에서 400 오류가 반환됩니다. 사고를 다시 활성화하거나 effort를 high 이하로 낮추세요.Claude Sonnet 5는 Claude 모델 제품군에서 속도와 지능의 최적 조합을 제공합니다. Claude Sonnet 4.6을 기반으로 구축되었습니다.
Claude Sonnet 5는 Claude Sonnet 4.6의 드롭인 업그레이드이며, 입력/출력 토큰 100만 개당 $2/$10 USD로 책정되어 있습니다. 자세한 내용은 가격을 참조하세요. Claude Sonnet 4.6에서 이미 실행 중인 코드에 대해 두 가지 호환성이 깨지는 API 변경 사항이 있습니다. 수동 확장 사고(thinking: {type: "enabled", budget_tokens: N})와 기본값이 아닌 값으로 설정된 샘플링 매개변수(temperature, top_p, top_k)는 더 이상 허용되지 않으며 400 오류를 반환합니다. 대신 effort 매개변수와 함께 adaptive thinking을 사용하세요. Claude Sonnet 5는 1M 토큰 컨텍스트 윈도우, adaptive thinking, 프롬프트 캐싱, 배치 처리, Files API, PDF 지원, 비전, 그리고 서버 측 및 클라이언트 측 도구 전체를 포함하여 Claude Sonnet 4.6과 동일한 기능 세트를 지원합니다. Priority Tier는 Claude Sonnet 5에서 사용할 수 없습니다. Claude Sonnet 5는 또한 새로운 토크나이저를 사용합니다.
# Sonnet 마이그레이션
model = "claude-sonnet-4-6" # Before
model = "claude-sonnet-5" # After다음 목록의 4번과 5번 항목은 호환성이 깨지는 변경 사항입니다. max_tokens는 총 출력(사고 및 응답 텍스트)에 대한 하드 제한으로 유지되므로, Claude Sonnet 4.6에서 사고 없이 실행되던 워크로드에 대해 이를 다시 검토하세요.
새로운 토크나이저: Claude Sonnet 5는 새로운 토크나이저를 사용합니다. 동일한 입력 텍스트가 Claude Sonnet 4.6보다 약 30% 더 많은 토큰을 생성합니다. 정확한 증가량은 콘텐츠에 따라 다릅니다. 요청, 응답 및 스트리밍 이벤트는 동일한 형태를 유지하며 코드 변경이 필요하지 않지만, 토큰 단위로 측정하거나 예산을 책정하는 모든 항목이 달라집니다. 동일한 텍스트에 대한 usage 필드와 토큰 카운팅 결과가 더 높아지고, 1M 토큰 컨텍스트 윈도우에 담을 수 있는 텍스트가 줄어들며, Claude Sonnet 4.6에 맞춰 조정된 max_tokens 제한이 동등한 출력을 잘라낼 수 있습니다. 토큰당 가격은 더 낮지만($2/$10 대 Claude Sonnet 4.6의 입력/출력 토큰 100만 개당 $3/$15), 동등한 요청의 비용이 정비례로 감소하지는 않습니다. 이전 모델에서 측정한 수치를 재사용하지 말고 Claude Sonnet 5를 대상으로 토큰 카운팅을 다시 실행하세요.
128k 최대 출력 토큰(변경 없음): Claude Sonnet 5는 Claude Sonnet 4.6과 동일하게 최대 128k 출력 토큰을 지원합니다. 기존 max_tokens 값은 유효합니다. 크기를 조정할 때 새로운 토크나이저를 고려하세요.
어시스턴트 메시지 프리필(변경 없음): 어시스턴트 메시지를 프리필하면 Claude Sonnet 4.6과 동일하게 Claude Sonnet 5에서 400 오류가 반환됩니다. Claude Sonnet 4.6으로 마이그레이션할 때 프리필을 제거했다면 추가 변경이 필요하지 않습니다. 대신 구조화된 출력, 시스템 프롬프트 지침 또는 output_config.format을 사용하세요.
Adaptive thinking이 기본적으로 활성화됨: Claude Sonnet 4.6에서는 thinking 필드가 없는 요청이 사고 없이 실행되지만, Claude Sonnet 5에서는 동일한 요청이 adaptive thinking으로 실행됩니다. 사고를 끄려면 thinking: {type: "disabled"}를 전달하세요. 수동 확장 사고(thinking: {type: "enabled", budget_tokens: N})는 지원되지 않으며 400 오류를 반환합니다. 사고 깊이를 제어하려면 effort 매개변수(기본값 high)를 사용하세요.
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-sonnet-5",
max_tokens=16000,
thinking={"type": "adaptive", "display": "summarized"},
output_config={"effort": "high"},
messages=[
{
"role": "user",
"content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
}
],
)
# 응답에는 요약된 사고 블록과 텍스트 블록이 포함됩니다
for block in response.content:
match block.type:
case "thinking":
print(f"\nThinking summary: {block.thinking}")
case "text":
print(f"\nResponse: {block.text}")샘플링 매개변수 제거됨: 기본값이 아닌 값으로 설정된 샘플링 매개변수(temperature, top_p, top_k)는 허용되지 않으며 400 오류를 반환합니다.
사이버 보안 안전장치: Claude Sonnet 5는 실시간 사이버 보안 안전장치를 갖춘 최초의 Sonnet 등급 모델입니다. 금지되거나 고위험 사이버 보안 주제와 관련된 요청은 거부될 수 있습니다. 거부는 오류가 아니라 stop_reason: "refusal"과 함께 성공적인 HTTP 200 응답으로 반환됩니다. 배경 정보는 안전장치, 경고 및 이의 제기를 참조하세요.
claude-sonnet-4-6에서 claude-sonnet-5로 업데이트하세요.max_tokens 제한을 다시 검토하고, 유용한 경우 128k 최대값(Claude Sonnet 4.6에서 변경 없음)까지 높이세요.thinking: {type: "enabled", budget_tokens: N} 구성을 제거하세요(400 오류 반환). Adaptive thinking이 기본적으로 활성화되어 있습니다. 끄려면 {type: "disabled"}를 전달하거나, 깊이를 제어하려면 effort 매개변수를 사용하세요.temperature, top_p, top_k 매개변수를 제거하세요(Claude Sonnet 5에서 400 오류 반환).stop_reason: "refusal"에 대한 처리를 추가하세요.max_tokens를 검토하세요.Claude Sonnet 4.5 또는 이전 Sonnet 모델에서 Claude Sonnet 5로 직접 마이그레이션하는 경우, Claude Sonnet 4.6에서 Claude Sonnet 5로 마이그레이션의 변경 사항과 이 섹션의 변경 사항을 함께 적용하세요.
어시스턴트 메시지 프리필이 더 이상 지원되지 않음
어시스턴트 메시지를 프리필하면 Claude Sonnet 4.6 이후 모델(Claude Sonnet 5 포함)에서 400 오류가 반환됩니다. 대신 구조화된 출력, 시스템 프롬프트 지침 또는 output_config.format을 사용하세요.
일반적인 프리필 사용 사례 및 마이그레이션:
출력 형식 제어(JSON/YAML 출력 강제): 분류 작업에는 구조화된 출력 또는 enum 필드가 있는 도구를 사용하세요.
서두 제거("Here is..." 문구 제거): 시스템 프롬프트에 직접적인 지침을 추가하세요. "서두 없이 직접 응답하세요. 'Here is...', 'Based on...' 등의 문구로 시작하지 마세요."
부적절한 거부 방지: Claude는 이제 적절한 거부를 훨씬 더 잘 수행합니다. 프리필 없이 사용자 메시지에서 명확한 프롬프트를 제공하는 것으로 충분합니다.
이어쓰기(중단된 응답 재개): 이어쓰기를 사용자 메시지로 이동하세요. "이전 응답이 중단되어 [previous_response]로 끝났습니다. 중단된 부분부터 계속하세요."
컨텍스트 주입 / 역할 일관성(긴 대화에서 컨텍스트 새로 고침): 이전에 프리필된 어시스턴트 리마인더였던 내용을 대신 사용자 턴에 삽입하세요.
도구 매개변수 JSON 이스케이프가 다를 수 있음
도구 매개변수의 JSON 문자열 이스케이프가 이전 모델과 다를 수 있습니다. 표준 JSON 파서는 이를 자동으로 처리하지만, 사용자 정의 문자열 기반 파싱은 업데이트가 필요할 수 있습니다.
확장 사고 변경 사항: Claude Sonnet 4.5의 budget_tokens 구성(thinking: {type: "enabled", budget_tokens: N})은 Claude Sonnet 5에서 지원되지 않으며 400 오류를 반환합니다. Adaptive thinking이 기본적으로 활성화되어 있으므로 대부분의 워크로드는 thinking 구성이 전혀 필요하지 않습니다. 사고 깊이를 제어하려면 effort 매개변수를 사용하세요. Claude Sonnet 4.5를 확장 사고 없이 실행했다면, 해당 동작을 유지하기 위해 thinking: {type: "disabled"}를 전달하세요.
샘플링 매개변수 제거
기본값이 아닌 값으로 설정된 샘플링 매개변수(temperature, top_p, top_k)는 Claude Sonnet 5에서 400 오류를 반환합니다. 요청에서 제거하고, 대신 프롬프트를 사용하여 모델의 동작을 유도하세요.
도구 버전 업데이트
최신 도구 버전(text_editor_20250728, code_execution_20260521)으로 업데이트하세요. undo_edit 명령을 사용하는 코드를 모두 제거하세요.
refusal stop reason 처리
애플리케이션을 업데이트하여 refusal stop reason을 처리하세요.
동작 변경에 맞게 프롬프트 업데이트
Claude 4 모델은 더 간결하고 직접적인 커뮤니케이션 스타일을 가지고 있습니다. 최적화 지침은 프롬프트 모범 사례를 검토하세요.
Claude Haiku 4.5와 Claude Sonnet 5는 동일 클래스 내 인접 모델보다 API 수준에서 더 많은 차이가 있습니다. Claude Haiku 4.5는 수동 확장 사고(기본적으로 비활성화), 200k 토큰 컨텍스트 윈도우, 최대 64k 출력 토큰을 사용하는 반면, Claude Sonnet 5는 기본적으로 adaptive thinking이 활성화된 상태로 실행되고, 기본적으로 1M 토큰 컨텍스트 윈도우를 제공하며, 최대 128k 출력 토큰을 지원합니다.
model = "claude-haiku-4-5-20251001" # Before
model = "claude-sonnet-5" # After사고 구성: Claude Haiku 4.5는 수동 확장 사고(thinking: {type: "enabled", budget_tokens: N})를 지원하고 thinking: {type: "adaptive"}를 거부합니다. Claude Sonnet 5에서는 지원이 반대입니다. adaptive thinking이 기본적으로 활성화되어 있고, 수동 확장 사고는 400 오류를 반환합니다. thinking: {type: "enabled", budget_tokens: N} 구성을 제거하고 기본값을 사용하거나, 사고를 끄려면 thinking: {type: "disabled"}를 전달하세요. budget_tokens에는 직접적인 대체 항목이 없습니다. 사고 깊이를 제어하려면 effort 매개변수를 사용하세요. Effort는 Claude Haiku 4.5에서 사용할 수 없으며 Claude Sonnet 5에서 기본값은 high입니다.
샘플링 매개변수 제거됨: temperature와 top_p는 Claude Haiku 4.5에서 작동합니다(한 번에 하나만, 둘 다는 아님). Claude Sonnet 5에서는 temperature, top_p 또는 top_k를 기본값이 아닌 값으로 설정하면 400 오류가 반환됩니다. 이러한 매개변수를 제거하고 프롬프트를 사용하여 모델의 동작을 유도하세요.
어시스턴트 프리필 제거됨: 어시스턴트 메시지 프리필은 Claude Haiku 4.5에서는 작동하지만 Claude Sonnet 5에서는 400 오류를 반환합니다. 대신 구조화된 출력, 시스템 프롬프트 지침 또는 output_config.format을 사용하세요.
더 큰 컨텍스트 윈도우 및 출력: Claude Sonnet 5는 Claude Haiku 4.5의 200k 토큰에서 증가한 1M 토큰 컨텍스트 윈도우를 기본적으로 제공하며, 64k에서 증가한 최대 128k 출력 토큰을 지원합니다. Claude Sonnet 5는 또한 다른 토크나이저를 사용하므로, Claude Haiku 4.5에서 측정한 수치를 재사용하지 말고 토큰 카운팅을 다시 실행하세요.
가격: Claude Haiku 4.5는 입력/출력 토큰 100만 개당 $1/$5로 책정되어 있습니다. Claude Sonnet 5는 입력/출력 토큰 100만 개당 $2/$10로 책정되어 있습니다. Claude 가격을 참조하세요.
사이버 보안 안전장치: Claude Sonnet 5는 실시간 사이버 보안 안전장치를 갖추고 있습니다. 금지되거나 고위험 사이버 보안 주제와 관련된 요청은 거부될 수 있으며, stop_reason: "refusal"과 함께 성공적인 HTTP 200 응답으로 반환됩니다. 배경 정보는 안전장치, 경고 및 이의 제기를 참조하세요.
claude-haiku-4-5-20251001(또는 claude-haiku-4-5 별칭)에서 claude-sonnet-5로 업데이트하세요.thinking: {type: "enabled", budget_tokens: N} 구성을 제거하세요(400 오류 반환). Adaptive thinking이 기본적으로 활성화되어 있습니다. 사고 없는 동작을 유지하려면 thinking: {type: "disabled"}를 전달하고, 사고 없이 실행되던 워크로드에 대해 max_tokens를 다시 검토하세요.high)를 사용하세요. Claude Haiku 4.5에서는 사용할 수 없으므로 기존 설정이 이전되지 않습니다.temperature 및 top_p 설정을 제거하세요(기본값이 아닌 값은 Claude Sonnet 5에서 400 오류 반환).max_tokens 제한을 다시 검토하세요.stop_reason: "refusal"에 대한 처리를 추가하세요.Claude Haiku 4.5는 최첨단에 가까운 성능을 갖춘 가장 빠르고 지능적인 Haiku 모델로, 대화형 애플리케이션과 대량 처리를 위한 프리미엄 모델 품질을 제공합니다.
기능에 대한 전체 개요는 모델 개요를 참조하세요.
모델 이름 업데이트:
# Haiku 3.5에서
model = "claude-3-5-haiku-20241022" # Before
model = "claude-haiku-4-5-20251001" # After새로운 속도 제한 검토: Haiku 4.5는 Haiku 3.5와 별도의 속도 제한을 가지고 있습니다. 자세한 내용은 속도 제한 문서를 참조하세요.
새로운 기능 탐색: 컨텍스트 인식, 증가된 출력 용량(64k 토큰), 더 높은 지능 및 향상된 속도에 대한 자세한 내용은 모델 개요를 참조하세요.
이러한 호환성이 깨지는 변경 사항은 Claude 3.x Haiku 모델에서 마이그레이션할 때 적용됩니다.
샘플링 매개변수 업데이트
temperature 또는 top_p 중 하나만 사용하고 둘 다 사용하지 마세요. 둘 다 설정하면 Claude Haiku 4.5에서 400 오류가 반환됩니다.
도구 버전 업데이트
최신 도구 버전(text_editor_20250728, code_execution_20250825)으로 업데이트하세요. undo_edit 명령을 사용하는 코드를 모두 제거하세요.
refusal stop reason 처리
애플리케이션을 업데이트하여 refusal stop reason을 처리하세요.
동작 변경에 맞게 프롬프트 업데이트
Claude 4 모델은 더 간결하고 직접적인 커뮤니케이션 스타일을 가지고 있습니다. 최적화 지침은 프롬프트 모범 사례를 검토하세요.
claude-haiku-4-5-20251001로 업데이트text_editor_20250728, code_execution_20250825)으로 업데이트. 레거시 버전은 지원되지 않음undo_edit 명령을 사용하는 코드를 모두 제거(해당하는 경우)temperature 또는 top_p 중 하나만 사용하도록 업데이트. 둘 다 설정하면 400 오류 반환refusal stop reason 처리Was this page helpful?