모델 및 가격

마이그레이션 가이드

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

Claude 4.6으로 마이그레이션

Claude Opus 4.6은 Claude 4.5의 거의 완벽한 대체 모델이지만, 알아두어야 할 몇 가지 호환성 변경 사항이 있습니다. 새로운 기능의 전체 목록은 Claude 4.6의 새로운 기능을 참조하세요.

모델 이름 업데이트

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

호환성 변경 사항

프리필 제거: Claude 4.6 모델에서 어시스턴트 메시지 프리필은 400 오류를 반환합니다. 대신 구조화된 출력, 시스템 프롬프트 지시사항 또는 output_config.format을 사용하세요.
도구 매개변수 따옴표 처리: Claude 4.6 모델은 도구 호출 인수에서 약간 다른 JSON 문자열 이스케이프를 생성할 수 있습니다(예: 유니코드 이스케이프 또는 슬래시 이스케이프의 다른 처리). JSON 파서 대신 원시 문자열로 도구 호출 input을 파싱하는 경우, 파싱 로직을 확인하세요. 표준 JSON 파서(json.loads() 또는 JSON.parse() 등)는 이러한 차이를 자동으로 처리합니다.

권장 변경 사항

필수는 아니지만 경험을 개선할 수 있습니다:

적응형 사고로 마이그레이션: thinking: {type: "enabled", budget_tokens: N}은 Claude 4.6 모델에서 더 이상 사용되지 않으며 향후 모델 릴리스에서 제거될 예정입니다. thinking: {type: "adaptive"}로 전환하고 effort 매개변수를 사용하여 사고 깊이를 제어하세요. 적응형 사고를 참조하세요.
```
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로의 전환도 포함합니다. 적응형 사고와 effort는 GA 기능이며 베타 SDK 네임스페이스나 베타 헤더가 필요하지 않습니다.
effort 베타 헤더 제거: effort 매개변수는 이제 GA입니다. 요청에서 betas=["effort-2025-11-24"]를 제거하세요.
세분화된 도구 스트리밍 베타 헤더 제거: 세분화된 도구 스트리밍은 이제 GA입니다. 요청에서 betas=["fine-grained-tool-streaming-2025-05-14"]를 제거하세요.
인터리브 사고 베타 헤더 제거 (Opus 4.6만 해당): 적응형 사고는 Opus 4.6에서 자동으로 인터리브 사고를 활성화합니다. Opus 4.6 요청에서 betas=["interleaved-thinking-2025-05-14"]를 제거하세요. 참고: Sonnet 4.6은 수동 확장 사고와 함께 이 베타 헤더를 계속 지원합니다.
output_config.format으로 마이그레이션: 구조화된 출력을 사용하는 경우, output_format={...}을 output_config={"format": {...}}로 업데이트하세요. 이전 매개변수는 계속 작동하지만 더 이상 사용되지 않으며 향후 모델 릴리스에서 제거될 예정입니다.

Claude 4.1 이하에서 Claude 4.6으로 마이그레이션

Opus 4.1, Sonnet 4 또는 이전 모델에서 직접 Claude 4.6으로 마이그레이션하는 경우, 위의 Claude 4.6 호환성 변경 사항과 이 섹션의 추가 변경 사항을 적용하세요.

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

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

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

추가 호환성 변경 사항

샘플링 매개변수 업데이트

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

temperature 또는 top_p 중 하나만 사용하세요. 둘 다 사용하지 마세요:

# 이전 - Claude 4+ 모델에서 오류 발생
response = client.messages.create(
    model="claude-3-7-sonnet-20250219",
    temperature=0.7,
    top_p=0.9,  # 둘 다 사용할 수 없음
    # ...
)

# 이후
response = client.messages.create(
    model="claude-opus-4-6",
    temperature=0.7,  # temperature 또는 top_p 중 하나만 사용
    # ...
)

도구 버전 업데이트

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 중지 사유를 처리하도록 애플리케이션을 업데이트하세요:

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

if response.stop_reason == "refusal":
    # 거부를 적절히 처리
    pass

model_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 4.6 마이그레이션 체크리스트

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 출력 강제): 분류 작업에는 구조화된 출력 또는 enum 필드가 있는 도구를 사용하세요.
- 서문 제거 ("Here is..." 문구 제거): 시스템 프롬프트에 직접 지시를 추가하세요: "서문 없이 직접 응답하세요. 'Here is...', 'Based on...' 등의 문구로 시작하지 마세요."
- 잘못된 거부 방지: Claude는 이제 적절한 거부를 훨씬 더 잘 처리합니다. 프리필 없이 사용자 메시지에서 명확한 프롬프팅으로 충분합니다.
- 연속 (중단된 응답 재개): 연속을 사용자 메시지로 이동하세요: "이전 응답이 중단되어 [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은 기본 effort 수준이 high이며, 이는 effort 매개변수가 없었던 Sonnet 4.5와 대조됩니다. Sonnet 4.5에서 Sonnet 4.6으로 마이그레이션할 때 effort 매개변수를 조정하는 것을 권장합니다. 명시적으로 설정하지 않으면 기본 effort 수준으로 인해 더 높은 지연 시간을 경험할 수 있습니다.

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

Sonnet 4.5에서 확장 사고를 사용하지 않는 경우, Sonnet 4.6에서도 사용하지 않고 계속할 수 있습니다. 사용 사례에 적합한 수준으로 effort를 명시적으로 설정해야 합니다. 사고가 비활성화된 low effort에서는 확장 사고가 없는 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에서 확장 사고를 사용하는 경우, Sonnet 4.6에서도 사고 구성을 변경할 필요 없이 계속 지원됩니다. 사고 예산을 약 16k 토큰으로 유지하는 것을 권장합니다. 실제로 대부분의 작업은 그만큼 사용하지 않지만, 토큰 사용량 폭주 위험 없이 어려운 문제에 대한 여유를 제공합니다.

코딩 및 에이전틱 사용 사례

에이전틱 코딩, 프론트엔드 디자인, 도구 중심 워크플로 및 복잡한 엔터프라이즈 워크플로의 경우, medium effort로 시작하는 것을 권장합니다. 지연 시간이 너무 높다면 effort를 low로 줄이는 것을 고려하세요. 더 높은 지능이 필요하다면 effort를 high로 높이거나 Opus 4.6으로 마이그레이션하는 것을 고려하세요.

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 effort로 시작하는 것을 권장합니다. 더 깊은 분석이 필요하면 effort를 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"}],
)

적응형 사고를 시도해야 할 때

위의 마이그레이션 경로는 예측 가능한 토큰 사용을 위해 budget_tokens와 함께 확장 사고를 사용합니다. 워크로드가 다음 패턴 중 하나에 해당하는 경우, 대신 적응형 사고를 시도해 보세요:

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

적응형 사고를 사용할 때는 작업에 대해 medium과 high effort를 평가하세요. 적절한 수준은 워크로드의 품질, 지연 시간 및 토큰 사용량 간의 트레이드오프에 따라 달라집니다.

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와 함께 확장 사고로 전환하세요. 이는 사고 비용에 상한을 두어 더 예측 가능한 결과를 제공합니다.

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 4.5는 Haiku 3.5와 별도의 속도 제한을 가집니다. 자세한 내용은 속도 제한 문서를 참조하세요.

코딩 및 추론 작업에서 상당한 성능 향상을 위해 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 4.6 모델로 마이그레이션하기 위한 가이드

Claude 4.6으로 마이그레이션

모델 이름 업데이트

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

호환성 변경 사항

프리필 제거: Claude 4.6 모델에서 어시스턴트 메시지 프리필은 400 오류를 반환합니다. 대신 구조화된 출력, 시스템 프롬프트 지시사항 또는 output_config.format을 사용하세요.
도구 매개변수 따옴표 처리: Claude 4.6 모델은 도구 호출 인수에서 약간 다른 JSON 문자열 이스케이프를 생성할 수 있습니다(예: 유니코드 이스케이프 또는 슬래시 이스케이프의 다른 처리). JSON 파서 대신 원시 문자열로 도구 호출 input을 파싱하는 경우, 파싱 로직을 확인하세요. 표준 JSON 파서(json.loads() 또는 JSON.parse() 등)는 이러한 차이를 자동으로 처리합니다.

권장 변경 사항

필수는 아니지만 경험을 개선할 수 있습니다:

적응형 사고로 마이그레이션: thinking: {type: "enabled", budget_tokens: N}은 Claude 4.6 모델에서 더 이상 사용되지 않으며 향후 모델 릴리스에서 제거될 예정입니다. thinking: {type: "adaptive"}로 전환하고 effort 매개변수를 사용하여 사고 깊이를 제어하세요. 적응형 사고를 참조하세요.
```
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로의 전환도 포함합니다. 적응형 사고와 effort는 GA 기능이며 베타 SDK 네임스페이스나 베타 헤더가 필요하지 않습니다.
effort 베타 헤더 제거: effort 매개변수는 이제 GA입니다. 요청에서 betas=["effort-2025-11-24"]를 제거하세요.
세분화된 도구 스트리밍 베타 헤더 제거: 세분화된 도구 스트리밍은 이제 GA입니다. 요청에서 betas=["fine-grained-tool-streaming-2025-05-14"]를 제거하세요.
인터리브 사고 베타 헤더 제거 (Opus 4.6만 해당): 적응형 사고는 Opus 4.6에서 자동으로 인터리브 사고를 활성화합니다. Opus 4.6 요청에서 betas=["interleaved-thinking-2025-05-14"]를 제거하세요. 참고: Sonnet 4.6은 수동 확장 사고와 함께 이 베타 헤더를 계속 지원합니다.
output_config.format으로 마이그레이션: 구조화된 출력을 사용하는 경우, output_format={...}을 output_config={"format": {...}}로 업데이트하세요. 이전 매개변수는 계속 작동하지만 더 이상 사용되지 않으며 향후 모델 릴리스에서 제거될 예정입니다.

Claude 4.1 이하에서 Claude 4.6으로 마이그레이션

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

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

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

추가 호환성 변경 사항

샘플링 매개변수 업데이트

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

temperature 또는 top_p 중 하나만 사용하세요. 둘 다 사용하지 마세요:

# 이전 - Claude 4+ 모델에서 오류 발생
response = client.messages.create(
    model="claude-3-7-sonnet-20250219",
    temperature=0.7,
    top_p=0.9,  # 둘 다 사용할 수 없음
    # ...
)

# 이후
response = client.messages.create(
    model="claude-opus-4-6",
    temperature=0.7,  # temperature 또는 top_p 중 하나만 사용
    # ...
)

도구 버전 업데이트

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 중지 사유를 처리하도록 애플리케이션을 업데이트하세요:

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

if response.stop_reason == "refusal":
    # 거부를 적절히 처리
    pass

model_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 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 출력 강제): 분류 작업에는 구조화된 출력 또는 enum 필드가 있는 도구를 사용하세요.
- 서문 제거 ("Here is..." 문구 제거): 시스템 프롬프트에 직접 지시를 추가하세요: "서문 없이 직접 응답하세요. 'Here is...', 'Based on...' 등의 문구로 시작하지 마세요."
- 잘못된 거부 방지: Claude는 이제 적절한 거부를 훨씬 더 잘 처리합니다. 프리필 없이 사용자 메시지에서 명확한 프롬프팅으로 충분합니다.
- 연속 (중단된 응답 재개): 연속을 사용자 메시지로 이동하세요: "이전 응답이 중단되어 [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으로 마이그레이션하는 것을 강력히 권장합니다. 동일한 가격대에서 더 높은 지능을 제공합니다.

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

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

확장 사고를 사용하는 경우

코딩 및 에이전틱 사용 사례

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"}],
)

적응형 사고를 시도해야 할 때

자율 다단계 에이전트: 요구사항을 작동하는 소프트웨어로 변환하는 코딩 에이전트, 데이터 분석 파이프라인, 모델이 여러 단계에 걸쳐 독립적으로 실행되는 버그 찾기. 적응형 사고는 모델이 단계별로 추론을 조정하여 더 긴 궤적에서 경로를 유지할 수 있게 합니다. 이러한 워크로드의 경우 high effort로 시작하세요. 지연 시간이나 토큰 사용량이 우려되면 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"}],
)

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 4.5는 Haiku 3.5와 별도의 속도 제한을 가집니다. 자세한 내용은 속도 제한 문서를 참조하세요.

코딩 및 추론 작업에서 상당한 성능 향상을 위해 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?