모델 및 가격모델

마이그레이션 가이드

이전 Claude 버전에서 Claude Opus 4.7 및 Claude 4.6 모델로 마이그레이션하기 위한 가이드

이 가이드는 Messages API 코드 마이그레이션을 다룹니다. Claude Managed Agents를 사용하는 경우 모델 이름 업데이트 외에는 변경이 필요하지 않습니다.

Claude Opus 4.7로 마이그레이션

Claude Opus 4.7은 현재까지 가장 강력한 일반 공개 모델입니다. 매우 자율적이며 장기 에이전트 작업, 지식 작업, 비전 작업 및 메모리 작업에서 뛰어난 성능을 발휘합니다. Claude Opus 4.7은 기존 Claude Opus 4.6 프롬프트 및 평가에서 동일한 $5 / $25 per MTok 가격으로 강력한 기본 성능을 제공해야 하지만, 마이그레이션할 때 알아야 할 몇 가지 동작 및 API 변경 사항이 있습니다. Claude Opus 4.6과 동일한 기능 세트를 지원하며, 여기에는 표준 API 가격으로 장기 컨텍스트 프리미엄이 없는 1M 토큰 컨텍스트 윈도우, 128k 최대 출력 토큰, 적응형 사고, 프롬프트 캐싱, 배치 처리, Files API, PDF 지원, 비전 및 전체 서버 측 및 클라이언트 측 도구(bash, 코드 실행, 컴퓨터 사용, 텍스트 편집기, 웹 검색, 웹 페치, MCP 커넥터, 메모리)가 포함됩니다.

Claude API 스킬로 이 마이그레이션을 자동화하세요. Claude Code에서 /claude-api migrate를 실행하여 번들된 Claude API 스킬을 호출하세요:

/claude-api migrate this project to claude-opus-4-7

이 스킬은 모델 ID 스왑, 주요 매개변수 변경, 프리필 교체 및 아래에 설명된 노력 보정을 코드베이스 전체에 적용한 다음 수동으로 확인할 항목의 체크리스트를 생성합니다. 파일을 편집하기 전에 마이그레이션 범위(전체 작업 디렉토리, 하위 디렉토리 또는 특정 파일 목록)를 확인하도록 요청합니다.

모델 이름 업데이트

# Opus 마이그레이션
model = "claude-opus-4-6"  # 이전
model = "claude-opus-4-7"  # 이후

주요 변경 사항

확장된 사고 제거됨: thinking: {type: "enabled", budget_tokens: N}은 더 이상 Claude Opus 4.7 이상 모델에서 지원되지 않으며 400 오류를 반환합니다. 적응형 사고(thinking: {type: "adaptive"})로 전환하고 노력 매개변수를 사용하여 사고 깊이를 제어하세요. 적응형 사고는 Claude Opus 4.7에서 기본적으로 비활성화됨: thinking 필드가 없는 요청은 사고 없이 실행되며, Opus 4.6 동작과 일치합니다. thinking: {type: "adaptive"}를 명시적으로 설정하여 활성화하세요.

이전 (Claude Opus 4.6):
```
client.messages.create(
    model="claude-opus-4-6",
    max_tokens=64000,
    thinking={"type": "enabled", "budget_tokens": 32000},
    messages=[{"role": "user", "content": "..."}],
)
```
이후 (Claude Opus 4.7):
```
client.messages.create(
    model="claude-opus-4-7",
    max_tokens=64000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # 또는 "max", "xhigh", "medium", "low"
    messages=[{"role": "user", "content": "..."}],
)
```
적응형 사고는 프롬프팅을 통해 조정 가능합니다. 모델이 과도하게 생각하거나 부족하게 생각할 때 조정하는 방법에 대한 지침은 노력 및 사고 깊이 보정을 참조하세요.
샘플링 매개변수 제거됨: Claude Opus 4.7에서 temperature, top_p 또는 top_k를 기본값이 아닌 값으로 설정하면 400 오류가 반환됩니다. 가장 안전한 마이그레이션 경로는 요청 페이로드에서 이러한 매개변수를 완전히 생략하는 것입니다. 프롬프팅은 Claude Opus 4.7에서 모델 동작을 안내하는 권장 방법입니다. 결정론을 위해 temperature = 0을 사용하고 있었다면, 이전 모델에서 동일한 출력을 보장하지 않았다는 점을 유의하세요.
사고 콘텐츠 기본적으로 생략됨: 사고 블록은 여전히 Claude Opus 4.7의 응답 스트림에 나타나지만, 명시적으로 옵트인하지 않는 한 thinking 필드는 비어 있습니다. 이는 기본값이 요약된 사고 텍스트를 반환하는 Claude Opus 4.6의 자동 변경입니다. Claude Opus 4.7에서 요약된 사고 콘텐츠를 복원하려면 thinking.display를 "summarized"로 설정하세요:
```
thinking = {
    "type": "adaptive",
    "display": "summarized",
}
```
Claude Opus 4.7의 기본값은 "omitted"입니다. 제품이 사용자에게 추론을 스트리밍하는 경우, 새로운 기본값은 출력이 시작되기 전에 긴 일시 중지로 나타납니다. display: "summarized"를 설정하여 사고 중에 표시되는 진행 상황을 복원하세요. 자세한 내용은 확장된 사고를 참조하세요.
업데이트된 토큰 계산: Claude Opus 4.7은 새로운 토크나이저를 사용하여 광범위한 작업에서 성능 향상에 기여합니다. 이 새로운 토크나이저는 이전 모델과 비교하여 텍스트를 처리할 때 대략 1배에서 1.35배의 토큰을 사용할 수 있으며(최대 ~35% 더 많음, 콘텐츠에 따라 다름), /v1/messages/count_tokens은 Claude Opus 4.6과 다른 Claude Opus 4.7의 토큰 수를 반환합니다. Claude Opus 4.7의 토큰 효율성은 워크로드 형태에 따라 다를 수 있습니다. 프롬프팅 개입, task_budget 및 effort는 비용을 제어하고 적절한 토큰 사용을 보장하는 데 도움이 될 수 있습니다. 이러한 제어가 모델 지능을 트레이드오프할 수 있다는 점을 염두에 두세요. max_tokens 매개변수를 업데이트하여 압축 트리거를 포함한 추가 여유를 제공하는 것을 제안합니다. Claude Opus 4.7은 표준 API 가격으로 장기 컨텍스트 프리미엄이 없는 1M 컨텍스트 윈도우를 제공합니다.
프리필 제거 (Opus 4.6에서 이월됨): Claude Opus 4.7에서 어시스턴트 메시지를 프리필하면 400 오류가 반환됩니다. 대신 구조화된 출력, 시스템 프롬프트 지침 또는 output_config.format을 사용하세요.

노력 수준 선택

노력 매개변수를 사용하면 Claude의 지능 대 토큰 지출을 조정하여 더 빠른 속도와 낮은 비용을 위해 기능을 트레이드오프할 수 있습니다. 코딩 및 에이전트 사용 사례의 경우 새로운 xhigh 노력 수준으로 시작하고, 대부분의 지능 민감 사용 사례의 경우 최소 high 노력을 사용하세요. 다른 노력 수준을 실험하여 토큰 사용 및 지능을 추가로 조정하세요:

max: 최대 노력은 일부 사용 사례에서 성능 향상을 제공할 수 있지만, 증가된 토큰 사용으로 인한 수익 감소를 보일 수 있습니다. 이 설정은 때때로 과도한 사고에 취약할 수 있습니다. 지능 요구 작업에 대해 최대 노력을 테스트하는 것을 권장합니다.
xhigh (신규): 초고 노력은 대부분의 코딩 및 에이전트 사용 사례에 가장 좋은 설정입니다.
high: 이 설정은 토큰 사용과 지능의 균형을 맞춥니다. 대부분의 지능 민감 사용 사례의 경우, 최소 high 노력을 권장합니다.
medium: 지능을 트레이드오프하면서 토큰 사용을 줄여야 하는 비용 민감 사용 사례에 적합합니다.
low: 짧고 범위가 지정된 작업 및 지능 민감하지 않은 지연 시간 민감 워크로드를 위해 예약하세요.

이 모델의 경우 노력이 이전의 모든 Opus보다 더 중요할 것으로 예상되며, 업그레이드할 때 적극적으로 실험하는 것을 권장합니다.

동작 변경 사항

Claude Opus 4.7은 Claude Opus 4.6과 몇 가지 동작 차이가 있으며, 이는 API 주요 변경 사항은 아니지만 프롬프트 업데이트 또는 스캐폴딩 제거가 필요할 수 있습니다.

응답 길이는 사용 사례에 따라 다름: Claude Opus 4.7은 고정된 장황함으로 기본값을 설정하는 대신 작업이 얼마나 복잡한지에 따라 응답 길이를 보정합니다. 이는 일반적으로 간단한 조회에서는 더 짧은 답변을, 개방형 분석에서는 훨씬 더 긴 답변을 의미합니다. 제품이 특정 스타일이나 출력 장황함에 의존하는 경우, 프롬프트를 조정해야 할 수 있습니다. 예를 들어, 장황함을 줄이려면 다음을 추가할 수 있습니다: "간결하고 집중된 응답을 제공하세요. 필수적이지 않은 컨텍스트를 건너뛰고 예제를 최소한으로 유지하세요." 특정 장황함 유형(예: 과도한 설명)을 보면 프롬프트에 추가 지침을 추가하여 방지할 수 있습니다. 긍정적인 예제는 Claude가 적절한 수준의 간결함으로 의사소통할 수 있는 방법을 보여주는 것이 부정적인 예제나 모델에게 하지 말아야 할 것을 알려주는 지침보다 더 효과적입니다.
더 문자 그대로의 지침 따르기: Claude Opus 4.7은 특히 낮은 노력 수준에서 Claude Opus 4.6보다 프롬프트를 더 문자 그대로 명시적으로 해석합니다. 한 항목에서 다른 항목으로 지침을 자동으로 일반화하지 않으며, 하지 않은 요청을 추론하지 않습니다. 이 문자 그대로의 해석의 장점은 정확성과 더 적은 혼란입니다. 일반적으로 신중하게 조정된 프롬프트, 구조화된 추출 및 예측 가능한 동작을 원하는 파이프라인이 있는 API 사용 사례에 더 잘 수행됩니다. 프롬프트 및 하네스 검토는 Claude Opus 4.7로의 마이그레이션에 특히 도움이 될 수 있습니다.
더 직접적인 톤: 모든 새로운 모델과 마찬가지로, 장문 작성의 산문 스타일이 변할 수 있습니다. Claude Opus 4.7은 더 직접적이고 의견이 있으며, Claude Opus 4.6의 더 따뜻한 스타일보다 검증 중심 표현과 이모지가 적습니다. 제품이 특정 음성에 의존하는 경우, 새로운 기준선에 대해 스타일 프롬프트를 다시 평가하세요.
에이전트 추적에서 기본 제공 진행 상황 업데이트: Claude Opus 4.7은 긴 에이전트 추적 전체에서 더 정기적이고 높은 품질의 사용자 업데이트를 제공합니다. 임시 상태 메시지를 강제하기 위해 스캐폴딩을 추가한 경우("모든 3개의 도구 호출 후 진행 상황 요약"), 제거를 시도하세요. Claude Opus 4.7의 사용자 대면 업데이트의 길이 또는 내용이 사용 사례에 잘 보정되지 않은 경우, 프롬프트에서 이러한 업데이트가 어떻게 보여야 하는지 명시적으로 설명하고 예제를 제공하세요.
기본적으로 생성되는 서브에이전트 감소: Claude Opus 4.7은 기본적으로 더 적은 서브에이전트를 생성하는 경향이 있습니다. 그러나 이 동작은 프롬프팅을 통해 조정 가능합니다. Claude Opus 4.7에 서브에이전트가 바람직한 시기에 대한 명시적 지침을 제공하세요.
더 엄격한 노력 보정: Claude Opus 4.6과 의미 있게 변경되어, Claude Opus 4.7은 노력 수준을 엄격하게 준수하며, 특히 낮은 수준에서 그렇습니다. low 및 medium에서 모델은 요청된 것 이상으로 가지 않고 요청된 것으로 작업 범위를 지정합니다. 이는 지연 시간과 비용에 좋지만, low 노력으로 실행되는 중간 정도로 복잡한 작업에서는 과소 사고의 위험이 있습니다. 복잡한 문제에서 얕은 추론을 관찰하면, 프롬프팅 대신 노력을 high 또는 xhigh로 올리세요. 지연 시간을 위해 노력을 low로 유지해야 하는 경우, 대상 지침을 추가하세요: "이 작업은 다단계 추론을 포함합니다. 응답하기 전에 문제를 신중하게 생각해보세요." Claude Opus 4.7의 권장 노력 수준을 참조하세요.
기본적으로 도구 호출 감소: Claude Opus 4.7은 Claude Opus 4.6보다 도구를 덜 자주 사용하고 추론을 더 많이 사용하는 경향이 있습니다. 이는 대부분의 경우 더 나은 결과를 생성합니다. 그러나 노력 설정을 높이는 것은 도구 사용 수준을 높이는 데 유용한 레버입니다, 특히 지식 작업에서. high 또는 xhigh 노력 설정은 에이전트 검색 및 코딩에서 실질적으로 더 많은 도구 사용을 보여줍니다. 더 많은 도구 사용을 원하는 시나리오의 경우, 프롬프트를 조정하여 모델에 도구를 언제 어떻게 올바르게 사용할지에 대해 명시적으로 지시할 수도 있습니다.
실시간 사이버 보안 보호: Claude Opus 4.7에 새로 추가된 금지되거나 높은 위험의 주제와 관련된 요청은 거부로 이어질 수 있습니다. 침투 테스트, 취약점 연구 또는 레드 팀 작업과 같은 합법적인 보안 작업의 경우, 사이버 검증 프로그램에 신청하여 사이버 콘텐츠에 대한 제한 감소를 요청하세요. 배경은 보호 장치, 경고 및 항소를 참조하세요.
고해상도 이미지 지원: Claude Opus 4.7은 고해상도 이미지 지원을 갖춘 첫 번째 Claude 모델이며, 긴 모서리에서 최대 이미지 해상도는 2576 픽셀입니다(이전 모델의 1568 픽셀에서 증가). 이는 비전 집약적 워크로드에서 이득을 잠금 해제하며 컴퓨터 사용, 스크린샷 이해 및 문서 분석에 특히 가치가 있습니다. 고해상도 지원은 자동이며 베타 헤더나 클라이언트 측 옵트인이 필요하지 않습니다. 전체 해상도 이미지는 이전 모델보다 최대 약 3배 더 많은 이미지 토큰을 사용할 수 있습니다(이미지당 최대 4,784 토큰, 이전 대략 1,600 토큰 상한과 비교), 따라서 이미지 집약적 워크로드에 대해 max_tokens 및 비용 예상을 다시 예산하거나, 추가 충실도가 필요하지 않은 경우 전송 전에 다운샘플하세요. 모델에서 반환된 포인팅 및 경계 상자 좌표는 Claude Opus 4.7의 실제 이미지 픽셀과 1
, 따라서 스케일 팩터 변환이 필요하지 않습니다. 자세한 내용은 Claude Opus 4.7의 고해상도 이미지 지원을 참조하세요.

권장 변경 사항

이는 필수는 아니지만 경험을 개선합니다:

max_tokens 다시 평가: 동일한 텍스트가 Claude Opus 4.7에서 더 높은 토큰 수를 생성하기 때문에, 압축 트리거를 포함한 추가 여유를 제공하도록 max_tokens 매개변수를 업데이트하는 것을 제안합니다. 프롬프팅 개입, task_budget 및 effort는 비용을 제어하고 적절한 토큰 사용을 보장하는 데 도움이 될 수 있습니다.
토큰 계산 예상 감사: 클라이언트 측에서 토큰을 추정하거나 고정된 토큰 대 문자 비율을 가정하는 모든 코드 경로는 Claude Opus 4.7에 대해 다시 테스트되어야 합니다. 토큰 계산 엔드포인트를 사용하여 확인하세요.
작업 예산 (베타) 채택: Claude Opus 4.7은 작업 예산을 도입합니다. 이러한 예산을 통해 Claude에 사고, 도구 호출, 도구 결과 및 최종 출력을 포함한 전체 에이전트 루프에 대해 얼마나 많은 토큰이 있는지 알릴 수 있습니다. 모델은 실시간 카운트다운을 보고 이를 사용하여 작업의 우선순위를 정하고 예산이 소비될 때 작업을 우아하게 완료합니다. 사용하려면 베타 헤더 task-budgets-2026-03-13을 설정하고 출력 구성에 다음을 추가하세요:
```
output_config = {
    "effort": "high",
    "task_budget": {"type": "tokens", "total": 128000},
}
```
사용 사례에 대해 다양한 작업 예산을 실험해야 할 수 있습니다. 모델에 주어진 작업 예산이 주어진 작업에 대해 너무 제한적인 경우, 예산을 제약으로 참조하면서 작업을 덜 철저하게 완료할 수 있습니다. 품질이 속도보다 중요한 개방형 에이전트 작업의 경우, 작업 예산을 설정하지 마세요. 작업 예산을 토큰 허용량으로 범위를 지정해야 하는 워크로드를 위해 예약하세요. 작업 예산의 최소값은 20k 토큰입니다.

이는 하드 캡이 아닙니다. 모델이 인식하는 제안입니다. 이는 생성된 토큰에 대한 하드 요청당 상한인 max_tokens와 다릅니다(max_tokens는 모델에 전달되지 않으며 모델은 이를 인식하지 못함), task_budget은 전체 에이전트 루프 전체에 걸친 자문 상한입니다. 모델이 자체 조절하기를 원할 때 task_budget을 사용하고, 사용을 제한하기 위한 하드 요청당 상한으로 max_tokens를 사용하세요.
max 또는 xhigh 노력에서 큰 max_tokens 설정: Claude Opus 4.7을 max 또는 xhigh 노력으로 실행하는 경우, 모델이 서브에이전트 및 도구 호출 전체에서 생각하고 행동할 수 있는 공간을 가질 수 있도록 큰 최대 출력 토큰 예산을 설정하세요. 64k 토큰에서 시작하고 거기서 조정하는 것을 권장합니다.
고해상도가 불필요한 경우 이미지 다운샘플: Claude Opus 4.7은 최대 2576px / 3.75MP의 이미지를 지원합니다. 고해상도 이미지는 더 많은 토큰을 사용합니다. 추가 이미지 충실도가 불필요한 경우, 토큰 사용 증가를 피하기 위해 Claude에 전송하기 전에 이미지를 다운샘플하세요. 이미지 및 비전을 참조하세요.

마이그레이션 체크리스트

Opus 4.5 이상에서 Claude Opus 4.7로 마이그레이션

Claude Opus 4.5, Opus 4.1 또는 이전 모델에서 Claude Opus 4.7로 직접 마이그레이션하는 경우, 위의 Opus 4.7 변경 사항 모두 더하기 Opus 4.5와 Opus 4.7 사이에 적용된 이 섹션의 누적 변경 사항을 적용하세요. Opus 4.6에서 마이그레이션하는 경우, 위의 Opus 4.7 섹션만 필요합니다.

모델 이름 업데이트

# Opus 마이그레이션
model = "claude-opus-4-5"  # 이전
model = "claude-opus-4-7"  # 이후

주요 변경 사항

프리필 제거는 위의 Opus 4.7 주요 변경 사항에서 다룹니다.
도구 매개변수 인용: Claude Opus 4.6 이상 모델은 도구 호출 인수에서 약간 다른 JSON 문자열 이스케이프를 생성할 수 있습니다(예: Unicode 이스케이프 또는 슬래시 이스케이프의 다른 처리). 도구 호출 input을 JSON 파서를 사용하지 않고 원시 문자열로 구문 분석하는 경우, 구문 분석 논리를 확인하세요. 표준 JSON 파서(예: json.loads() 또는 JSON.parse())는 이러한 차이를 자동으로 처리합니다.

권장 변경 사항

이러한 변경 사항은 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"}로 전환하고 노력 매개변수를 사용하여 사고 깊이를 제어하세요. 적응형 사고를 참조하세요.
```
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=[...],
)
```
마이그레이션은 또한 client.beta.messages.create에서 client.messages.create로 이동합니다. 적응형 사고 및 노력은 GA 기능이며 베타 SDK 네임스페이스나 베타 헤더가 필요하지 않습니다.
노력 베타 헤더 제거: 노력 매개변수는 이제 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": {...}}로 업데이트하세요. 이전 매개변수는 여전히 기능하지만 더 이상 사용되지 않으며 향후 모델 릴리스에서 제거될 것입니다.

Claude 4.1 이상에서 마이그레이션

Opus 4.1, Sonnet 4(더 이상 사용되지 않음) 또는 이전 모델에서 Claude Opus 4.7로 직접 마이그레이션하는 경우, 이 가이드의 맨 위에 있는 Claude Opus 4.7 변경 사항과 위의 누적 변경 사항 더하기 이 섹션의 추가 변경 사항을 적용하세요.

# Opus 4.1에서
model = "claude-opus-4-1-20250805"  # 이전
model = "claude-opus-4-7"  # 이후

# Sonnet 4에서
model = "claude-sonnet-4-20250514"  # 이전
model = "claude-opus-4-7"  # 이후

# Sonnet 3.7에서
model = "claude-3-7-sonnet-20250219"  # 이전
model = "claude-opus-4-7"  # 이후

추가 주요 변경 사항

샘플링 매개변수 제거

이는 Claude 3.x 모델에서 마이그레이션할 때 주요 변경 사항입니다.

Claude Opus 4.7부터 temperature, top_p 또는 top_k를 기본값이 아닌 값으로 설정하면 400 오류가 반환됩니다. 가장 안전한 마이그레이션 경로는 요청에서 이러한 매개변수를 완전히 생략하고 프롬프팅을 사용하여 모델의 동작을 안내하는 것입니다. 결정론을 위해 temperature = 0을 사용하고 있었다면, 이전에 동일한 출력을 보장하지 않았다는 점을 유의하세요.
Python
```
# 이전 - 이는 Claude 4+ 모델에서 오류가 발생합니다
response = client.messages.create(
    model="claude-3-7-sonnet-20250219",
    temperature=0.7,
    top_p=0.9,  # 기본값이 아닌 샘플링 매개변수는 Opus 4.7에서 400을 반환합니다
    # ...
)

# 이후
response = client.messages.create(
    model="claude-opus-4-7",
    # ...
)
```
도구 버전 업데이트

이는 Claude 3.x 모델에서 마이그레이션할 때 주요 변경 사항입니다.

최신 도구 버전으로 업데이트하세요. 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_20250825로 업그레이드하세요. 마이그레이션 지침은 코드 실행 도구 설명서를 참조하세요.

refusal 중지 이유 처리

응용 프로그램을 업데이트하여 refusal 중지 이유를 처리하세요:

Python

response = client.messages.create(...)

if response.stop_reason == "refusal":
    # 거부를 적절하게 처리합니다
    pass

model_context_window_exceeded 중지 이유 처리

Claude 4.5+ 모델은 요청된 max_tokens 제한이 아닌 컨텍스트 윈도우 제한에 도달하여 생성이 중지될 때 model_context_window_exceeded 중지 이유를 반환합니다. 이 새로운 중지 이유를 처리하도록 응용 프로그램을 업데이트하세요:
Python
```
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+ 모델에는 기본 제공 토큰 효율적 도구 사용이 있으며 이러한 헤더는 효과가 없습니다.

마이그레이션 체크리스트 (Opus 4.5 이상에서)

Claude Sonnet 4.6으로 마이그레이션

Claude Sonnet 4.6은 강력한 지능과 빠른 성능을 결합하며, 개선된 에이전트 검색 기능과 웹 검색 또는 웹 페치와 함께 사용할 때 무료 코드 실행을 제공합니다. 일상적인 코딩, 분석 및 콘텐츠 작업에 이상적입니다.

기능의 전체 개요는 모델 개요를 참조하세요.

Sonnet 4.6 가격은 입력 토큰당 $3, 출력 토큰당 $15입니다. 자세한 내용은 Claude 가격을 참조하세요.

모델 이름 업데이트:

# Sonnet 4.5에서
model = "claude-sonnet-4-5"  # 이전
model = "claude-sonnet-4-6"  # 이후

# Sonnet 4에서
model = "claude-sonnet-4-20250514"  # 이전
model = "claude-sonnet-4-6"  # 이후

주요 변경 사항

Sonnet 4.5에서 마이그레이션할 때

어시스턴트 메시지 프리필링은 더 이상 지원되지 않습니다

Sonnet 4.5 이전 버전에서 마이그레이션할 때 주요 변경 사항입니다.

어시스턴트 메시지 프리필링은 Sonnet 4.6에서 400 오류를 반환합니다. 대신 구조화된 출력, 시스템 프롬프트 지시사항 또는 output_config.format을 사용하세요.

일반적인 프리필 사용 사례 및 마이그레이션:
- 출력 형식 제어 (JSON/YAML 출력 강제): 구조화된 출력 또는 분류 작업을 위한 열거형 필드가 있는 도구를 사용하세요.
- 전문(preamble) 제거 ("Here is..." 구문 제거): 시스템 프롬프트에 직접 지시사항을 추가하세요: "전문 없이 직접 응답하세요. 'Here is...', 'Based on...' 등의 구문으로 시작하지 마세요."
- 나쁜 거부 방지: Claude는 이제 적절한 거부에 훨씬 더 능숙합니다. 프리필 없이 사용자 메시지에서 명확한 프롬프팅으로 충분해야 합니다.
- 연속(continuations) (중단된 응답 재개): 연속을 사용자 메시지로 이동하세요: "이전 응답이 중단되었고 [previous_response]로 끝났습니다. 중단된 부분부터 계속하세요."
- 컨텍스트 하이드레이션 / 역할 일관성 (긴 대화에서 컨텍스트 새로고침): 이전에 프리필된 어시스턴트 알림을 사용자 턴으로 주입하세요.
도구 매개변수 JSON 이스케이핑이 다를 수 있습니다

Sonnet 4.5 이전 버전에서 마이그레이션할 때 주요 변경 사항입니다.

도구 매개변수의 JSON 문자열 이스케이핑이 이전 모델과 다를 수 있습니다. 표준 JSON 파서는 이를 자동으로 처리하지만, 사용자 정의 문자열 기반 파싱은 업데이트가 필요할 수 있습니다.

Claude 3.x에서 마이그레이션할 때

샘플링 매개변수 업데이트

Claude 3.x 모델에서 마이그레이션할 때 주요 변경 사항입니다.

temperature 또는 top_p 중 하나만 사용하고, 둘 다 사용하지 마세요.
도구 버전 업데이트

Claude 3.x 모델에서 마이그레이션할 때 주요 변경 사항입니다.

최신 도구 버전(text_editor_20250728, code_execution_20250825)으로 업데이트하세요. undo_edit 명령을 사용하는 모든 코드를 제거하세요.
refusal 중지 이유 처리

refusal 중지 이유를 처리하도록 애플리케이션을 업데이트하세요.
동작 변경에 대한 프롬프트 업데이트

Claude 4 모델은 더 간결하고 직접적인 통신 스타일을 가지고 있습니다. 최적화 지침을 위해 프롬프팅 모범 사례를 검토하세요.

권장 변경 사항

fine-grained-tool-streaming-2025-05-14 베타 헤더 제거: 세분화된 도구 스트리밍은 이제 Sonnet 4.6에서 GA이며 더 이상 베타 헤더가 필요하지 않습니다.
output_format을 output_config.format으로 마이그레이션: output_format 매개변수는 더 이상 사용되지 않습니다. 대신 output_config.format을 사용하세요.

Sonnet 4.5에서 마이그레이션

Sonnet 4.5에서 Sonnet 4.6으로 마이그레이션을 고려하세요. Sonnet 4.6은 동일한 가격으로 더 높은 지능을 제공합니다.

Sonnet 4.6은 기본적으로 high의 노력 수준으로 설정되며, Sonnet 4.5는 노력 매개변수가 없었습니다. Sonnet 4.5에서 Sonnet 4.6으로 마이그레이션할 때 노력 매개변수를 조정하는 것을 고려하세요. 명시적으로 설정하지 않으면 기본 노력 수준으로 인해 더 높은 지연 시간이 발생할 수 있습니다.

확장 사고를 사용하지 않는 경우

Sonnet 4.5에서 확장 사고를 사용하지 않는 경우, Sonnet 4.6에서도 계속 사용하지 않을 수 있습니다. 사용 사례에 적합한 수준으로 노력을 명시적으로 설정해야 합니다. 사고가 비활성화된 low 노력에서는 확장 사고가 없는 Sonnet 4.5에 비해 유사하거나 더 나은 성능을 기대할 수 있습니다.

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=8192,
    output_config={"effort": "low"},
    messages=[{"role": "user", "content": "Your prompt here"}],
)

확장 사고를 사용하는 경우

Sonnet 4.5에서 budget_tokens를 사용하여 확장 사고를 사용하는 경우, Sonnet 4.6에서도 여전히 작동하지만 더 이상 사용되지 않습니다. 적응형 사고로 노력 매개변수를 사용하여 마이그레이션하세요.

적응형 사고로 마이그레이션

적응형 사고는 Sonnet 4.6에서 budget_tokens의 권장 대체입니다. 다음 워크로드 패턴에 특히 적합합니다:

자율 다단계 에이전트: 요구사항을 작동하는 소프트웨어로 변환하는 코딩 에이전트, 데이터 분석 파이프라인, 모델이 많은 단계에서 독립적으로 실행되는 버그 찾기. 적응형 사고를 사용하면 모델이 각 단계마다 추론을 조정하여 더 긴 궤적에서 경로를 유지할 수 있습니다. 이러한 워크로드의 경우 high 노력으로 시작하세요. 지연 시간이나 토큰 사용량이 문제가 되면 medium으로 축소하세요.
컴퓨터 사용 에이전트: Sonnet 4.6은 적응형 모드를 사용하여 컴퓨터 사용 평가에서 최고 수준의 정확도를 달성했습니다.
이중 모드 워크로드: 적응형이 간단한 쿼리에서 사고를 건너뛰고 복잡한 쿼리에서 깊이 있게 추론하는 쉬운 작업과 어려운 작업의 혼합.

적응형 사고를 사용할 때 작업에서 medium 및 high 노력을 평가하세요. 올바른 수준은 워크로드의 품질, 지연 시간 및 토큰 사용량 간의 트레이드오프에 따라 달라집니다.

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=64000,
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "Your prompt here"}],
)

적응형 사고에서 일관성 없는 동작이나 품질 저하가 보이면 노력 설정을 낮추거나 먼저 max_tokens을 하드 제한으로 사용해 보세요. budget_tokens를 사용한 확장 사고는 Sonnet 4.6에서 여전히 작동하지만 더 이상 사용되지 않으며 더 이상 권장되지 않습니다.

마이그레이션 중 budget_tokens 유지

마이그레이션 중 budget_tokens를 임시로 유지해야 하는 경우, 약 16k 토큰의 예산은 더 어려운 문제에 대한 여유를 제공하면서 토큰 사용량 폭발의 위험이 없습니다. 이 구성은 더 이상 사용되지 않으며 향후 모델 릴리스에서 제거될 예정입니다.

코딩 및 에이전트 사용 사례

에이전트 코딩, 프론트엔드 설계, 도구 집약적 워크플로우 및 복잡한 엔터프라이즈 워크플로우의 경우 medium 노력으로 시작하세요. 지연 시간이 너무 높으면 노력을 low로 줄이는 것을 고려하세요. 더 높은 지능이 필요하면 노력을 high로 늘리거나 Opus 4.7로 마이그레이션하는 것을 고려하세요.

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16384,
    thinking={"type": "enabled", "budget_tokens": 16384},
    output_config={"effort": "medium"},
    betas=["interleaved-thinking-2025-05-14"],
    messages=[{"role": "user", "content": "Your prompt here"}],
)

채팅 및 비코딩 사용 사례

채팅, 콘텐츠 생성, 검색, 분류 및 기타 비코딩 작업의 경우 확장 사고를 사용하여 low 노력으로 시작하세요. 더 깊이가 필요하면 노력을 medium으로 늘리세요.

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=8192,
    thinking={"type": "enabled", "budget_tokens": 16384},
    output_config={"effort": "low"},
    betas=["interleaved-thinking-2025-05-14"],
    messages=[{"role": "user", "content": "Your prompt here"}],
)

Sonnet 4.6 마이그레이션 체크리스트

Claude Sonnet 4.5로 마이그레이션

Claude Sonnet 4.5는 강력한 지능과 빠른 성능을 결합하여 일상적인 코딩, 분석 및 콘텐츠 작업에 이상적입니다.

기능의 전체 개요는 모델 개요를 참조하세요.

Sonnet 4.5 가격은 입력 토큰당 $3/백만, 출력 토큰당 $15/백만입니다. 자세한 내용은 Claude 가격을 참조하세요.

모델 이름 업데이트:

# Sonnet 4에서
model = "claude-sonnet-4-20250514"  # 이전
model = "claude-sonnet-4-5-20250929"  # 이후

# Sonnet 3.7에서
model = "claude-3-7-sonnet-20250219"  # 이전
model = "claude-sonnet-4-5-20250929"  # 이후

주요 변경 사항

이러한 주요 변경 사항은 Claude 3.x Sonnet 모델에서 마이그레이션할 때 적용됩니다.

샘플링 매개변수 업데이트

Claude 3.x 모델에서 마이그레이션할 때 주요 변경 사항입니다.

temperature 또는 top_p 중 하나만 사용하고, 둘 다 사용하지 마세요.
도구 버전 업데이트

Claude 3.x 모델에서 마이그레이션할 때 주요 변경 사항입니다.

최신 도구 버전(text_editor_20250728, code_execution_20250825)으로 업데이트하세요. undo_edit 명령을 사용하는 모든 코드를 제거하세요.
refusal 중지 이유 처리

``refusal` 중지 이유를 처리하도록 애플리케이션을 업데이트하세요.
동작 변경에 대한 프롬프트 업데이트

Claude 4 모델은 더 간결하고 직접적인 통신 스타일을 가지고 있습니다. 최적화 지침을 위해 프롬프팅 모범 사례를 검토하세요.

Sonnet 4.5 마이그레이션 체크리스트

모델 ID를 claude-sonnet-4-5-20250929로 업데이트
주요 변경: 도구 버전을 최신(text_editor_20250728, code_execution_20250825)으로 업데이트; 레거시 버전은 지원되지 않음 (3.x에서 마이그레이션하는 경우)
주요 변경: undo_edit 명령을 사용하는 모든 코드 제거 (해당하는 경우)
주요 변경: 샘플링 매개변수를 temperature 또는 top_p 중 하나만 사용하도록 업데이트, 둘 다 사용하지 않음 (3.x에서 마이그레이션하는 경우)
애플리케이션에서 새로운 refusal 중지 이유 처리
프롬프팅 모범 사례에 따라 프롬프트 검토 및 업데이트
복잡한 추론 작업을 위해 확장 사고 활성화 고려
프로덕션 배포 전에 개발 환경에서 테스트

Claude Haiku 4.5로 마이그레이션

Claude Haiku 4.5는 가장 빠르고 가장 지능적인 Haiku 모델로 거의 최첨단 성능을 제공하며 대화형 애플리케이션 및 대량 처리를 위한 프리미엄 모델 품질을 제공합니다.

기능의 전체 개요는 모델 개요를 참조하세요.

Haiku 4.5 가격은 입력 토큰당 $1/백만, 출력 토큰당 $5/백만입니다. 자세한 내용은 Claude 가격을 참조하세요.

모델 이름 업데이트:

# Haiku 3.5에서
model = "claude-3-5-haiku-20241022"  # 이전
model = "claude-haiku-4-5-20251001"  # 이후

# Haiku 3에서
model = "claude-3-haiku-20240307"  # 이전
model = "claude-haiku-4-5-20251001"  # 이후

새로운 속도 제한 검토: Haiku 4.5는 Haiku 3.5 및 Haiku 3과 별도의 속도 제한을 가지고 있습니다. 자세한 내용은 속도 제한 문서를 참조하세요.

코딩 및 추론 작업에서 상당한 성능 개선을 위해 thinking: {type: "enabled", budget_tokens: N}을 사용하여 확장 사고를 활성화하는 것을 고려하세요.

확장 사고는 프롬프트 캐싱 효율성에 영향을 미칩니다.

확장 사고는 Claude 4.6 이상의 모델에서 더 이상 사용되지 않습니다. 더 새로운 모델을 사용하는 경우 대신 적응형 사고를 사용하세요.

새로운 기능 탐색: 컨텍스트 인식, 증가된 출력 용량(64k 토큰), 더 높은 지능 및 개선된 속도에 대한 자세한 내용은 모델 개요를 참조하세요.

주요 변경 사항

이러한 주요 변경 사항은 Claude 3.x Haiku 모델에서 마이그레이션할 때 적용됩니다.

샘플링 매개변수 업데이트

Claude 3.x 모델에서 마이그레이션할 때 주요 변경 사항입니다.

temperature 또는 top_p 중 하나만 사용하고, 둘 다 사용하지 마세요.
도구 버전 업데이트

Claude 3.x 모델에서 마이그레이션할 때 주요 변경 사항입니다.

최신 도구 버전(text_editor_20250728, code_execution_20250825)으로 업데이트하세요. undo_edit 명령을 사용하는 모든 코드를 제거하세요.
refusal 중지 이유 처리

``refusal` 중지 이유를 처리하도록 애플리케이션을 업데이트하세요.
동작 변경에 대한 프롬프트 업데이트

Claude 4 모델은 더 간결하고 직접적인 통신 스타일을 가지고 있습니다. 최적화 지침을 위해 프롬프팅 모범 사례를 검토하세요.

Haiku 4.5 마이그레이션 체크리스트

모델 ID를 claude-haiku-4-5-20251001로 업데이트
주요 변경: 도구 버전을 최신(text_editor_20250728, code_execution_20250825)으로 업데이트; 레거시 버전은 지원되지 않음
주요 변경: undo_edit 명령을 사용하는 모든 코드 제거 (해당하는 경우)
주요 변경: 샘플링 매개변수를 temperature 또는 top_p 중 하나만 사용하도록 업데이트, 둘 다 사용하지 않음
애플리케이션에서 새로운 refusal 중지 이유 처리
새로운 속도 제한에 대해 검토 및 조정 (Haiku 3.5와 별도)
프롬프팅 모범 사례에 따라 프롬프트 검토 및 업데이트
복잡한 추론 작업을 위해 확장 사고 활성화 고려
프로덕션 배포 전에 개발 환경에서 테스트

도움말 받기

API 문서에서 자세한 사양 확인
모델 기능에서 성능 비교 검토
API 릴리스 노트에서 API 업데이트 검토
마이그레이션 중 문제가 발생하면 지원팀에 문의

Was this page helpful?

모델 및 가격모델

마이그레이션 가이드

이전 Claude 버전에서 Claude Opus 4.7 및 Claude 4.6 모델로 마이그레이션하기 위한 가이드

이 가이드는 Messages API 코드 마이그레이션을 다룹니다. Claude Managed Agents를 사용하는 경우 모델 이름 업데이트 외에는 변경이 필요하지 않습니다.

Claude Opus 4.7로 마이그레이션

Claude API 스킬로 이 마이그레이션을 자동화하세요. Claude Code에서 /claude-api migrate를 실행하여 번들된 Claude API 스킬을 호출하세요:

/claude-api migrate this project to claude-opus-4-7

모델 이름 업데이트

# Opus 마이그레이션
model = "claude-opus-4-6"  # 이전
model = "claude-opus-4-7"  # 이후

주요 변경 사항

확장된 사고 제거됨: thinking: {type: "enabled", budget_tokens: N}은 더 이상 Claude Opus 4.7 이상 모델에서 지원되지 않으며 400 오류를 반환합니다. 적응형 사고(thinking: {type: "adaptive"})로 전환하고 노력 매개변수를 사용하여 사고 깊이를 제어하세요. 적응형 사고는 Claude Opus 4.7에서 기본적으로 비활성화됨: thinking 필드가 없는 요청은 사고 없이 실행되며, Opus 4.6 동작과 일치합니다. thinking: {type: "adaptive"}를 명시적으로 설정하여 활성화하세요.

이전 (Claude Opus 4.6):
```
client.messages.create(
    model="claude-opus-4-6",
    max_tokens=64000,
    thinking={"type": "enabled", "budget_tokens": 32000},
    messages=[{"role": "user", "content": "..."}],
)
```
이후 (Claude Opus 4.7):
```
client.messages.create(
    model="claude-opus-4-7",
    max_tokens=64000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # 또는 "max", "xhigh", "medium", "low"
    messages=[{"role": "user", "content": "..."}],
)
```
적응형 사고는 프롬프팅을 통해 조정 가능합니다. 모델이 과도하게 생각하거나 부족하게 생각할 때 조정하는 방법에 대한 지침은 노력 및 사고 깊이 보정을 참조하세요.
샘플링 매개변수 제거됨: Claude Opus 4.7에서 temperature, top_p 또는 top_k를 기본값이 아닌 값으로 설정하면 400 오류가 반환됩니다. 가장 안전한 마이그레이션 경로는 요청 페이로드에서 이러한 매개변수를 완전히 생략하는 것입니다. 프롬프팅은 Claude Opus 4.7에서 모델 동작을 안내하는 권장 방법입니다. 결정론을 위해 temperature = 0을 사용하고 있었다면, 이전 모델에서 동일한 출력을 보장하지 않았다는 점을 유의하세요.
사고 콘텐츠 기본적으로 생략됨: 사고 블록은 여전히 Claude Opus 4.7의 응답 스트림에 나타나지만, 명시적으로 옵트인하지 않는 한 thinking 필드는 비어 있습니다. 이는 기본값이 요약된 사고 텍스트를 반환하는 Claude Opus 4.6의 자동 변경입니다. Claude Opus 4.7에서 요약된 사고 콘텐츠를 복원하려면 thinking.display를 "summarized"로 설정하세요:
```
thinking = {
    "type": "adaptive",
    "display": "summarized",
}
```
Claude Opus 4.7의 기본값은 "omitted"입니다. 제품이 사용자에게 추론을 스트리밍하는 경우, 새로운 기본값은 출력이 시작되기 전에 긴 일시 중지로 나타납니다. display: "summarized"를 설정하여 사고 중에 표시되는 진행 상황을 복원하세요. 자세한 내용은 확장된 사고를 참조하세요.
업데이트된 토큰 계산: Claude Opus 4.7은 새로운 토크나이저를 사용하여 광범위한 작업에서 성능 향상에 기여합니다. 이 새로운 토크나이저는 이전 모델과 비교하여 텍스트를 처리할 때 대략 1배에서 1.35배의 토큰을 사용할 수 있으며(최대 ~35% 더 많음, 콘텐츠에 따라 다름), /v1/messages/count_tokens은 Claude Opus 4.6과 다른 Claude Opus 4.7의 토큰 수를 반환합니다. Claude Opus 4.7의 토큰 효율성은 워크로드 형태에 따라 다를 수 있습니다. 프롬프팅 개입, task_budget 및 effort는 비용을 제어하고 적절한 토큰 사용을 보장하는 데 도움이 될 수 있습니다. 이러한 제어가 모델 지능을 트레이드오프할 수 있다는 점을 염두에 두세요. max_tokens 매개변수를 업데이트하여 압축 트리거를 포함한 추가 여유를 제공하는 것을 제안합니다. Claude Opus 4.7은 표준 API 가격으로 장기 컨텍스트 프리미엄이 없는 1M 컨텍스트 윈도우를 제공합니다.
프리필 제거 (Opus 4.6에서 이월됨): Claude Opus 4.7에서 어시스턴트 메시지를 프리필하면 400 오류가 반환됩니다. 대신 구조화된 출력, 시스템 프롬프트 지침 또는 output_config.format을 사용하세요.

노력 수준 선택

max: 최대 노력은 일부 사용 사례에서 성능 향상을 제공할 수 있지만, 증가된 토큰 사용으로 인한 수익 감소를 보일 수 있습니다. 이 설정은 때때로 과도한 사고에 취약할 수 있습니다. 지능 요구 작업에 대해 최대 노력을 테스트하는 것을 권장합니다.
xhigh (신규): 초고 노력은 대부분의 코딩 및 에이전트 사용 사례에 가장 좋은 설정입니다.
high: 이 설정은 토큰 사용과 지능의 균형을 맞춥니다. 대부분의 지능 민감 사용 사례의 경우, 최소 high 노력을 권장합니다.
medium: 지능을 트레이드오프하면서 토큰 사용을 줄여야 하는 비용 민감 사용 사례에 적합합니다.
low: 짧고 범위가 지정된 작업 및 지능 민감하지 않은 지연 시간 민감 워크로드를 위해 예약하세요.

이 모델의 경우 노력이 이전의 모든 Opus보다 더 중요할 것으로 예상되며, 업그레이드할 때 적극적으로 실험하는 것을 권장합니다.

동작 변경 사항

응답 길이는 사용 사례에 따라 다름: Claude Opus 4.7은 고정된 장황함으로 기본값을 설정하는 대신 작업이 얼마나 복잡한지에 따라 응답 길이를 보정합니다. 이는 일반적으로 간단한 조회에서는 더 짧은 답변을, 개방형 분석에서는 훨씬 더 긴 답변을 의미합니다. 제품이 특정 스타일이나 출력 장황함에 의존하는 경우, 프롬프트를 조정해야 할 수 있습니다. 예를 들어, 장황함을 줄이려면 다음을 추가할 수 있습니다: "간결하고 집중된 응답을 제공하세요. 필수적이지 않은 컨텍스트를 건너뛰고 예제를 최소한으로 유지하세요." 특정 장황함 유형(예: 과도한 설명)을 보면 프롬프트에 추가 지침을 추가하여 방지할 수 있습니다. 긍정적인 예제는 Claude가 적절한 수준의 간결함으로 의사소통할 수 있는 방법을 보여주는 것이 부정적인 예제나 모델에게 하지 말아야 할 것을 알려주는 지침보다 더 효과적입니다.
더 문자 그대로의 지침 따르기: Claude Opus 4.7은 특히 낮은 노력 수준에서 Claude Opus 4.6보다 프롬프트를 더 문자 그대로 명시적으로 해석합니다. 한 항목에서 다른 항목으로 지침을 자동으로 일반화하지 않으며, 하지 않은 요청을 추론하지 않습니다. 이 문자 그대로의 해석의 장점은 정확성과 더 적은 혼란입니다. 일반적으로 신중하게 조정된 프롬프트, 구조화된 추출 및 예측 가능한 동작을 원하는 파이프라인이 있는 API 사용 사례에 더 잘 수행됩니다. 프롬프트 및 하네스 검토는 Claude Opus 4.7로의 마이그레이션에 특히 도움이 될 수 있습니다.
더 직접적인 톤: 모든 새로운 모델과 마찬가지로, 장문 작성의 산문 스타일이 변할 수 있습니다. Claude Opus 4.7은 더 직접적이고 의견이 있으며, Claude Opus 4.6의 더 따뜻한 스타일보다 검증 중심 표현과 이모지가 적습니다. 제품이 특정 음성에 의존하는 경우, 새로운 기준선에 대해 스타일 프롬프트를 다시 평가하세요.
에이전트 추적에서 기본 제공 진행 상황 업데이트: Claude Opus 4.7은 긴 에이전트 추적 전체에서 더 정기적이고 높은 품질의 사용자 업데이트를 제공합니다. 임시 상태 메시지를 강제하기 위해 스캐폴딩을 추가한 경우("모든 3개의 도구 호출 후 진행 상황 요약"), 제거를 시도하세요. Claude Opus 4.7의 사용자 대면 업데이트의 길이 또는 내용이 사용 사례에 잘 보정되지 않은 경우, 프롬프트에서 이러한 업데이트가 어떻게 보여야 하는지 명시적으로 설명하고 예제를 제공하세요.
기본적으로 생성되는 서브에이전트 감소: Claude Opus 4.7은 기본적으로 더 적은 서브에이전트를 생성하는 경향이 있습니다. 그러나 이 동작은 프롬프팅을 통해 조정 가능합니다. Claude Opus 4.7에 서브에이전트가 바람직한 시기에 대한 명시적 지침을 제공하세요.
더 엄격한 노력 보정: Claude Opus 4.6과 의미 있게 변경되어, Claude Opus 4.7은 노력 수준을 엄격하게 준수하며, 특히 낮은 수준에서 그렇습니다. low 및 medium에서 모델은 요청된 것 이상으로 가지 않고 요청된 것으로 작업 범위를 지정합니다. 이는 지연 시간과 비용에 좋지만, low 노력으로 실행되는 중간 정도로 복잡한 작업에서는 과소 사고의 위험이 있습니다. 복잡한 문제에서 얕은 추론을 관찰하면, 프롬프팅 대신 노력을 high 또는 xhigh로 올리세요. 지연 시간을 위해 노력을 low로 유지해야 하는 경우, 대상 지침을 추가하세요: "이 작업은 다단계 추론을 포함합니다. 응답하기 전에 문제를 신중하게 생각해보세요." Claude Opus 4.7의 권장 노력 수준을 참조하세요.
기본적으로 도구 호출 감소: Claude Opus 4.7은 Claude Opus 4.6보다 도구를 덜 자주 사용하고 추론을 더 많이 사용하는 경향이 있습니다. 이는 대부분의 경우 더 나은 결과를 생성합니다. 그러나 노력 설정을 높이는 것은 도구 사용 수준을 높이는 데 유용한 레버입니다, 특히 지식 작업에서. high 또는 xhigh 노력 설정은 에이전트 검색 및 코딩에서 실질적으로 더 많은 도구 사용을 보여줍니다. 더 많은 도구 사용을 원하는 시나리오의 경우, 프롬프트를 조정하여 모델에 도구를 언제 어떻게 올바르게 사용할지에 대해 명시적으로 지시할 수도 있습니다.
실시간 사이버 보안 보호: Claude Opus 4.7에 새로 추가된 금지되거나 높은 위험의 주제와 관련된 요청은 거부로 이어질 수 있습니다. 침투 테스트, 취약점 연구 또는 레드 팀 작업과 같은 합법적인 보안 작업의 경우, 사이버 검증 프로그램에 신청하여 사이버 콘텐츠에 대한 제한 감소를 요청하세요. 배경은 보호 장치, 경고 및 항소를 참조하세요.
고해상도 이미지 지원: Claude Opus 4.7은 고해상도 이미지 지원을 갖춘 첫 번째 Claude 모델이며, 긴 모서리에서 최대 이미지 해상도는 2576 픽셀입니다(이전 모델의 1568 픽셀에서 증가). 이는 비전 집약적 워크로드에서 이득을 잠금 해제하며 컴퓨터 사용, 스크린샷 이해 및 문서 분석에 특히 가치가 있습니다. 고해상도 지원은 자동이며 베타 헤더나 클라이언트 측 옵트인이 필요하지 않습니다. 전체 해상도 이미지는 이전 모델보다 최대 약 3배 더 많은 이미지 토큰을 사용할 수 있습니다(이미지당 최대 4,784 토큰, 이전 대략 1,600 토큰 상한과 비교), 따라서 이미지 집약적 워크로드에 대해 max_tokens 및 비용 예상을 다시 예산하거나, 추가 충실도가 필요하지 않은 경우 전송 전에 다운샘플하세요. 모델에서 반환된 포인팅 및 경계 상자 좌표는 Claude Opus 4.7의 실제 이미지 픽셀과 1
, 따라서 스케일 팩터 변환이 필요하지 않습니다. 자세한 내용은 Claude Opus 4.7의 고해상도 이미지 지원을 참조하세요.

권장 변경 사항

이는 필수는 아니지만 경험을 개선합니다:

max_tokens 다시 평가: 동일한 텍스트가 Claude Opus 4.7에서 더 높은 토큰 수를 생성하기 때문에, 압축 트리거를 포함한 추가 여유를 제공하도록 max_tokens 매개변수를 업데이트하는 것을 제안합니다. 프롬프팅 개입, task_budget 및 effort는 비용을 제어하고 적절한 토큰 사용을 보장하는 데 도움이 될 수 있습니다.
토큰 계산 예상 감사: 클라이언트 측에서 토큰을 추정하거나 고정된 토큰 대 문자 비율을 가정하는 모든 코드 경로는 Claude Opus 4.7에 대해 다시 테스트되어야 합니다. 토큰 계산 엔드포인트를 사용하여 확인하세요.
작업 예산 (베타) 채택: Claude Opus 4.7은 작업 예산을 도입합니다. 이러한 예산을 통해 Claude에 사고, 도구 호출, 도구 결과 및 최종 출력을 포함한 전체 에이전트 루프에 대해 얼마나 많은 토큰이 있는지 알릴 수 있습니다. 모델은 실시간 카운트다운을 보고 이를 사용하여 작업의 우선순위를 정하고 예산이 소비될 때 작업을 우아하게 완료합니다. 사용하려면 베타 헤더 task-budgets-2026-03-13을 설정하고 출력 구성에 다음을 추가하세요:
```
output_config = {
    "effort": "high",
    "task_budget": {"type": "tokens", "total": 128000},
}
```
사용 사례에 대해 다양한 작업 예산을 실험해야 할 수 있습니다. 모델에 주어진 작업 예산이 주어진 작업에 대해 너무 제한적인 경우, 예산을 제약으로 참조하면서 작업을 덜 철저하게 완료할 수 있습니다. 품질이 속도보다 중요한 개방형 에이전트 작업의 경우, 작업 예산을 설정하지 마세요. 작업 예산을 토큰 허용량으로 범위를 지정해야 하는 워크로드를 위해 예약하세요. 작업 예산의 최소값은 20k 토큰입니다.

이는 하드 캡이 아닙니다. 모델이 인식하는 제안입니다. 이는 생성된 토큰에 대한 하드 요청당 상한인 max_tokens와 다릅니다(max_tokens는 모델에 전달되지 않으며 모델은 이를 인식하지 못함), task_budget은 전체 에이전트 루프 전체에 걸친 자문 상한입니다. 모델이 자체 조절하기를 원할 때 task_budget을 사용하고, 사용을 제한하기 위한 하드 요청당 상한으로 max_tokens를 사용하세요.
max 또는 xhigh 노력에서 큰 max_tokens 설정: Claude Opus 4.7을 max 또는 xhigh 노력으로 실행하는 경우, 모델이 서브에이전트 및 도구 호출 전체에서 생각하고 행동할 수 있는 공간을 가질 수 있도록 큰 최대 출력 토큰 예산을 설정하세요. 64k 토큰에서 시작하고 거기서 조정하는 것을 권장합니다.
고해상도가 불필요한 경우 이미지 다운샘플: Claude Opus 4.7은 최대 2576px / 3.75MP의 이미지를 지원합니다. 고해상도 이미지는 더 많은 토큰을 사용합니다. 추가 이미지 충실도가 불필요한 경우, 토큰 사용 증가를 피하기 위해 Claude에 전송하기 전에 이미지를 다운샘플하세요. 이미지 및 비전을 참조하세요.

마이그레이션 체크리스트

Opus 4.5 이상에서 Claude Opus 4.7로 마이그레이션

모델 이름 업데이트

# Opus 마이그레이션
model = "claude-opus-4-5"  # 이전
model = "claude-opus-4-7"  # 이후

주요 변경 사항

프리필 제거는 위의 Opus 4.7 주요 변경 사항에서 다룹니다.
도구 매개변수 인용: Claude Opus 4.6 이상 모델은 도구 호출 인수에서 약간 다른 JSON 문자열 이스케이프를 생성할 수 있습니다(예: Unicode 이스케이프 또는 슬래시 이스케이프의 다른 처리). 도구 호출 input을 JSON 파서를 사용하지 않고 원시 문자열로 구문 분석하는 경우, 구문 분석 논리를 확인하세요. 표준 JSON 파서(예: json.loads() 또는 JSON.parse())는 이러한 차이를 자동으로 처리합니다.

권장 변경 사항

적응형 사고로 마이그레이션 (Opus 4.7에서 필수): thinking: {type: "enabled", budget_tokens: N}은 Claude Opus 4.7에서 400 오류를 반환합니다. thinking: {type: "adaptive"}로 전환하고 노력 매개변수를 사용하여 사고 깊이를 제어하세요. 적응형 사고를 참조하세요.
```
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=[...],
)
```
마이그레이션은 또한 client.beta.messages.create에서 client.messages.create로 이동합니다. 적응형 사고 및 노력은 GA 기능이며 베타 SDK 네임스페이스나 베타 헤더가 필요하지 않습니다.
노력 베타 헤더 제거: 노력 매개변수는 이제 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": {...}}로 업데이트하세요. 이전 매개변수는 여전히 기능하지만 더 이상 사용되지 않으며 향후 모델 릴리스에서 제거될 것입니다.

Claude 4.1 이상에서 마이그레이션

# Opus 4.1에서
model = "claude-opus-4-1-20250805"  # 이전
model = "claude-opus-4-7"  # 이후

# Sonnet 4에서
model = "claude-sonnet-4-20250514"  # 이전
model = "claude-opus-4-7"  # 이후

# Sonnet 3.7에서
model = "claude-3-7-sonnet-20250219"  # 이전
model = "claude-opus-4-7"  # 이후

추가 주요 변경 사항

샘플링 매개변수 제거

이는 Claude 3.x 모델에서 마이그레이션할 때 주요 변경 사항입니다.

Claude Opus 4.7부터 temperature, top_p 또는 top_k를 기본값이 아닌 값으로 설정하면 400 오류가 반환됩니다. 가장 안전한 마이그레이션 경로는 요청에서 이러한 매개변수를 완전히 생략하고 프롬프팅을 사용하여 모델의 동작을 안내하는 것입니다. 결정론을 위해 temperature = 0을 사용하고 있었다면, 이전에 동일한 출력을 보장하지 않았다는 점을 유의하세요.
Python
```
# 이전 - 이는 Claude 4+ 모델에서 오류가 발생합니다
response = client.messages.create(
    model="claude-3-7-sonnet-20250219",
    temperature=0.7,
    top_p=0.9,  # 기본값이 아닌 샘플링 매개변수는 Opus 4.7에서 400을 반환합니다
    # ...
)

# 이후
response = client.messages.create(
    model="claude-opus-4-7",
    # ...
)
```
도구 버전 업데이트

이는 Claude 3.x 모델에서 마이그레이션할 때 주요 변경 사항입니다.

최신 도구 버전으로 업데이트하세요. 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_20250825로 업그레이드하세요. 마이그레이션 지침은 코드 실행 도구 설명서를 참조하세요.

refusal 중지 이유 처리

응용 프로그램을 업데이트하여 refusal 중지 이유를 처리하세요:

Python

response = client.messages.create(...)

if response.stop_reason == "refusal":
    # 거부를 적절하게 처리합니다
    pass

model_context_window_exceeded 중지 이유 처리

Claude 4.5+ 모델은 요청된 max_tokens 제한이 아닌 컨텍스트 윈도우 제한에 도달하여 생성이 중지될 때 model_context_window_exceeded 중지 이유를 반환합니다. 이 새로운 중지 이유를 처리하도록 응용 프로그램을 업데이트하세요:
Python
```
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+ 모델에는 기본 제공 토큰 효율적 도구 사용이 있으며 이러한 헤더는 효과가 없습니다.

마이그레이션 체크리스트 (Opus 4.5 이상에서)

Claude Sonnet 4.6으로 마이그레이션

기능의 전체 개요는 모델 개요를 참조하세요.

Sonnet 4.6 가격은 입력 토큰당 $3, 출력 토큰당 $15입니다. 자세한 내용은 Claude 가격을 참조하세요.

모델 이름 업데이트:

# Sonnet 4.5에서
model = "claude-sonnet-4-5"  # 이전
model = "claude-sonnet-4-6"  # 이후

# Sonnet 4에서
model = "claude-sonnet-4-20250514"  # 이전
model = "claude-sonnet-4-6"  # 이후

주요 변경 사항

Sonnet 4.5에서 마이그레이션할 때

어시스턴트 메시지 프리필링은 더 이상 지원되지 않습니다

Sonnet 4.5 이전 버전에서 마이그레이션할 때 주요 변경 사항입니다.

어시스턴트 메시지 프리필링은 Sonnet 4.6에서 400 오류를 반환합니다. 대신 구조화된 출력, 시스템 프롬프트 지시사항 또는 output_config.format을 사용하세요.

일반적인 프리필 사용 사례 및 마이그레이션:
- 출력 형식 제어 (JSON/YAML 출력 강제): 구조화된 출력 또는 분류 작업을 위한 열거형 필드가 있는 도구를 사용하세요.
- 전문(preamble) 제거 ("Here is..." 구문 제거): 시스템 프롬프트에 직접 지시사항을 추가하세요: "전문 없이 직접 응답하세요. 'Here is...', 'Based on...' 등의 구문으로 시작하지 마세요."
- 나쁜 거부 방지: Claude는 이제 적절한 거부에 훨씬 더 능숙합니다. 프리필 없이 사용자 메시지에서 명확한 프롬프팅으로 충분해야 합니다.
- 연속(continuations) (중단된 응답 재개): 연속을 사용자 메시지로 이동하세요: "이전 응답이 중단되었고 [previous_response]로 끝났습니다. 중단된 부분부터 계속하세요."
- 컨텍스트 하이드레이션 / 역할 일관성 (긴 대화에서 컨텍스트 새로고침): 이전에 프리필된 어시스턴트 알림을 사용자 턴으로 주입하세요.
도구 매개변수 JSON 이스케이핑이 다를 수 있습니다

Sonnet 4.5 이전 버전에서 마이그레이션할 때 주요 변경 사항입니다.

도구 매개변수의 JSON 문자열 이스케이핑이 이전 모델과 다를 수 있습니다. 표준 JSON 파서는 이를 자동으로 처리하지만, 사용자 정의 문자열 기반 파싱은 업데이트가 필요할 수 있습니다.

Claude 3.x에서 마이그레이션할 때

샘플링 매개변수 업데이트

Claude 3.x 모델에서 마이그레이션할 때 주요 변경 사항입니다.

temperature 또는 top_p 중 하나만 사용하고, 둘 다 사용하지 마세요.
도구 버전 업데이트

Claude 3.x 모델에서 마이그레이션할 때 주요 변경 사항입니다.

최신 도구 버전(text_editor_20250728, code_execution_20250825)으로 업데이트하세요. undo_edit 명령을 사용하는 모든 코드를 제거하세요.
refusal 중지 이유 처리

refusal 중지 이유를 처리하도록 애플리케이션을 업데이트하세요.
동작 변경에 대한 프롬프트 업데이트

Claude 4 모델은 더 간결하고 직접적인 통신 스타일을 가지고 있습니다. 최적화 지침을 위해 프롬프팅 모범 사례를 검토하세요.

권장 변경 사항

fine-grained-tool-streaming-2025-05-14 베타 헤더 제거: 세분화된 도구 스트리밍은 이제 Sonnet 4.6에서 GA이며 더 이상 베타 헤더가 필요하지 않습니다.
output_format을 output_config.format으로 마이그레이션: output_format 매개변수는 더 이상 사용되지 않습니다. 대신 output_config.format을 사용하세요.

Sonnet 4.5에서 마이그레이션

Sonnet 4.5에서 Sonnet 4.6으로 마이그레이션을 고려하세요. Sonnet 4.6은 동일한 가격으로 더 높은 지능을 제공합니다.

확장 사고를 사용하지 않는 경우

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=8192,
    output_config={"effort": "low"},
    messages=[{"role": "user", "content": "Your prompt here"}],
)

확장 사고를 사용하는 경우

적응형 사고로 마이그레이션

적응형 사고는 Sonnet 4.6에서 budget_tokens의 권장 대체입니다. 다음 워크로드 패턴에 특히 적합합니다:

자율 다단계 에이전트: 요구사항을 작동하는 소프트웨어로 변환하는 코딩 에이전트, 데이터 분석 파이프라인, 모델이 많은 단계에서 독립적으로 실행되는 버그 찾기. 적응형 사고를 사용하면 모델이 각 단계마다 추론을 조정하여 더 긴 궤적에서 경로를 유지할 수 있습니다. 이러한 워크로드의 경우 high 노력으로 시작하세요. 지연 시간이나 토큰 사용량이 문제가 되면 medium으로 축소하세요.
컴퓨터 사용 에이전트: Sonnet 4.6은 적응형 모드를 사용하여 컴퓨터 사용 평가에서 최고 수준의 정확도를 달성했습니다.
이중 모드 워크로드: 적응형이 간단한 쿼리에서 사고를 건너뛰고 복잡한 쿼리에서 깊이 있게 추론하는 쉬운 작업과 어려운 작업의 혼합.

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=64000,
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "Your prompt here"}],
)

마이그레이션 중 budget_tokens 유지

코딩 및 에이전트 사용 사례

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16384,
    thinking={"type": "enabled", "budget_tokens": 16384},
    output_config={"effort": "medium"},
    betas=["interleaved-thinking-2025-05-14"],
    messages=[{"role": "user", "content": "Your prompt here"}],
)

채팅 및 비코딩 사용 사례

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=8192,
    thinking={"type": "enabled", "budget_tokens": 16384},
    output_config={"effort": "low"},
    betas=["interleaved-thinking-2025-05-14"],
    messages=[{"role": "user", "content": "Your prompt here"}],
)

Sonnet 4.6 마이그레이션 체크리스트

Claude Sonnet 4.5로 마이그레이션

Claude Sonnet 4.5는 강력한 지능과 빠른 성능을 결합하여 일상적인 코딩, 분석 및 콘텐츠 작업에 이상적입니다.

기능의 전체 개요는 모델 개요를 참조하세요.

Sonnet 4.5 가격은 입력 토큰당 $3/백만, 출력 토큰당 $15/백만입니다. 자세한 내용은 Claude 가격을 참조하세요.

모델 이름 업데이트:

# Sonnet 4에서
model = "claude-sonnet-4-20250514"  # 이전
model = "claude-sonnet-4-5-20250929"  # 이후

# Sonnet 3.7에서
model = "claude-3-7-sonnet-20250219"  # 이전
model = "claude-sonnet-4-5-20250929"  # 이후

주요 변경 사항

이러한 주요 변경 사항은 Claude 3.x Sonnet 모델에서 마이그레이션할 때 적용됩니다.

샘플링 매개변수 업데이트

Claude 3.x 모델에서 마이그레이션할 때 주요 변경 사항입니다.

temperature 또는 top_p 중 하나만 사용하고, 둘 다 사용하지 마세요.
도구 버전 업데이트

Claude 3.x 모델에서 마이그레이션할 때 주요 변경 사항입니다.

최신 도구 버전(text_editor_20250728, code_execution_20250825)으로 업데이트하세요. undo_edit 명령을 사용하는 모든 코드를 제거하세요.
refusal 중지 이유 처리

``refusal` 중지 이유를 처리하도록 애플리케이션을 업데이트하세요.
동작 변경에 대한 프롬프트 업데이트

Claude 4 모델은 더 간결하고 직접적인 통신 스타일을 가지고 있습니다. 최적화 지침을 위해 프롬프팅 모범 사례를 검토하세요.

Sonnet 4.5 마이그레이션 체크리스트

모델 ID를 claude-sonnet-4-5-20250929로 업데이트
주요 변경: 도구 버전을 최신(text_editor_20250728, code_execution_20250825)으로 업데이트; 레거시 버전은 지원되지 않음 (3.x에서 마이그레이션하는 경우)
주요 변경: undo_edit 명령을 사용하는 모든 코드 제거 (해당하는 경우)
주요 변경: 샘플링 매개변수를 temperature 또는 top_p 중 하나만 사용하도록 업데이트, 둘 다 사용하지 않음 (3.x에서 마이그레이션하는 경우)
애플리케이션에서 새로운 refusal 중지 이유 처리
프롬프팅 모범 사례에 따라 프롬프트 검토 및 업데이트
복잡한 추론 작업을 위해 확장 사고 활성화 고려
프로덕션 배포 전에 개발 환경에서 테스트

Claude Haiku 4.5로 마이그레이션

기능의 전체 개요는 모델 개요를 참조하세요.

Haiku 4.5 가격은 입력 토큰당 $1/백만, 출력 토큰당 $5/백만입니다. 자세한 내용은 Claude 가격을 참조하세요.

모델 이름 업데이트:

# Haiku 3.5에서
model = "claude-3-5-haiku-20241022"  # 이전
model = "claude-haiku-4-5-20251001"  # 이후

# Haiku 3에서
model = "claude-3-haiku-20240307"  # 이전
model = "claude-haiku-4-5-20251001"  # 이후

새로운 속도 제한 검토: Haiku 4.5는 Haiku 3.5 및 Haiku 3과 별도의 속도 제한을 가지고 있습니다. 자세한 내용은 속도 제한 문서를 참조하세요.

코딩 및 추론 작업에서 상당한 성능 개선을 위해 thinking: {type: "enabled", budget_tokens: N}을 사용하여 확장 사고를 활성화하는 것을 고려하세요.

확장 사고는 프롬프트 캐싱 효율성에 영향을 미칩니다.

확장 사고는 Claude 4.6 이상의 모델에서 더 이상 사용되지 않습니다. 더 새로운 모델을 사용하는 경우 대신 적응형 사고를 사용하세요.

새로운 기능 탐색: 컨텍스트 인식, 증가된 출력 용량(64k 토큰), 더 높은 지능 및 개선된 속도에 대한 자세한 내용은 모델 개요를 참조하세요.

주요 변경 사항

이러한 주요 변경 사항은 Claude 3.x Haiku 모델에서 마이그레이션할 때 적용됩니다.

샘플링 매개변수 업데이트

Claude 3.x 모델에서 마이그레이션할 때 주요 변경 사항입니다.

temperature 또는 top_p 중 하나만 사용하고, 둘 다 사용하지 마세요.
도구 버전 업데이트

Claude 3.x 모델에서 마이그레이션할 때 주요 변경 사항입니다.

최신 도구 버전(text_editor_20250728, code_execution_20250825)으로 업데이트하세요. undo_edit 명령을 사용하는 모든 코드를 제거하세요.
refusal 중지 이유 처리

``refusal` 중지 이유를 처리하도록 애플리케이션을 업데이트하세요.
동작 변경에 대한 프롬프트 업데이트

Claude 4 모델은 더 간결하고 직접적인 통신 스타일을 가지고 있습니다. 최적화 지침을 위해 프롬프팅 모범 사례를 검토하세요.

Haiku 4.5 마이그레이션 체크리스트

모델 ID를 claude-haiku-4-5-20251001로 업데이트
주요 변경: 도구 버전을 최신(text_editor_20250728, code_execution_20250825)으로 업데이트; 레거시 버전은 지원되지 않음
주요 변경: undo_edit 명령을 사용하는 모든 코드 제거 (해당하는 경우)
주요 변경: 샘플링 매개변수를 temperature 또는 top_p 중 하나만 사용하도록 업데이트, 둘 다 사용하지 않음
애플리케이션에서 새로운 refusal 중지 이유 처리
새로운 속도 제한에 대해 검토 및 조정 (Haiku 3.5와 별도)
프롬프팅 모범 사례에 따라 프롬프트 검토 및 업데이트
복잡한 추론 작업을 위해 확장 사고 활성화 고려
프로덕션 배포 전에 개발 환경에서 테스트

도움말 받기

API 문서에서 자세한 사양 확인
모델 기능에서 성능 비교 검토
API 릴리스 노트에서 API 업데이트 검토
마이그레이션 중 문제가 발생하면 지원팀에 문의

Was this page helpful?