이 페이지는 Claude 3.7 모델에서 Claude 4 모델(Opus 4 및 Sonnet 4)로 마이그레이션하는 방법에 대한 가이드를 제공합니다. 대부분의 경우 최소한의 변경으로 Claude 4 모델로 전환할 수 있습니다:
  1. 모델 이름을 업데이트하세요:
    • 기존: claude-3-7-sonnet-20250219
    • 변경: claude-sonnet-4-20250514 또는 claude-opus-4-20250514
  2. 기존 API 호출은 수정 없이 계속 작동해야 하지만, Claude 4 모델에서는 API 동작이 약간 변경되었습니다(자세한 내용은 API 릴리스 노트 참조).

​
Claude 4의 새로운 기능

​
새로운 거부 중단 이유

Claude 4 모델은 Claude 4 모델의 향상된 지능으로 인해 모델이 안전상의 이유로 생성을 거부하는 콘텐츠에 대한 새로운 refusal 중단 이유를 도입합니다: 
{"id":"msg_014XEDjypDjFzgKVWdFUXxZP",
"type":"message",
"role":"assistant",
"model":"claude-sonnet-4-20250514",
"content":[{"type":"text","text":"I would be happy to assist you. You can "}],
"stop_reason":"refusal",
"stop_sequence":null,
"usage":{"input_tokens":564,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":22}
}
Claude 4로 마이그레이션할 때는 refusal 중단 이유를 처리하도록 애플리케이션을 업데이트해야 합니다.

​
요약된 사고

확장 사고가 활성화된 상태에서 Claude 4 모델의 Messages API는 Claude의 전체 사고 과정에 대한 요약을 반환합니다. 요약된 사고는 확장 사고의 완전한 지능적 이점을 제공하면서 오용을 방지합니다. API는 Claude 3.7과 4 모델에서 일관되지만, 확장 사고에 대한 스트리밍 응답은 스트리밍 이벤트 간에 지연이 있을 수 있는 “청크” 전달 패턴으로 반환될 수 있습니다.
요약은 요청에서 대상으로 지정한 모델과 다른 모델에 의해 처리됩니다. 사고 모델은 요약된 출력을 보지 않습니다.
자세한 정보는 확장 사고 문서를 참조하세요.

​
인터리브 사고

Claude 4 모델은 도구 사용과 확장 사고의 인터리빙을 지원하여 도구 사용과 응답이 일반 메시지와 혼합될 수 있는 더 자연스러운 대화를 가능하게 합니다.
인터리브 사고는 베타 버전입니다. 인터리브 사고를 활성화하려면 API 요청에 베타 헤더 interleaved-thinking-2025-05-14를 추가하세요.
자세한 정보는 확장 사고 문서를 참조하세요.

​
업데이트된 텍스트 편집기 도구

텍스트 편집기 도구가 Claude 4 모델에 대해 다음과 같은 변경 사항으로 업데이트되었습니다:
  • 도구 유형: text_editor_20250728
  • 도구 이름: str_replace_based_edit_tool
  • undo_edit 명령은 Claude 4 모델에서 더 이상 지원되지 않습니다.
str_replace_editor 텍스트 편집기 도구는 Claude Sonnet 3.7에서 동일하게 유지됩니다.
Claude Sonnet 3.7에서 마이그레이션하고 텍스트 편집기 도구를 사용하는 경우: 
# Claude Sonnet 3.7
tools=[
    {
        "type": "text_editor_20250124",
        "name": "str_replace_editor"
    }
]

# Claude 4
tools=[
    {
        "type": "text_editor_20250728",
        "name": "str_replace_based_edit_tool"
    }
]
자세한 정보는 텍스트 편집기 도구 문서를 참조하세요.

​
토큰 효율적 도구 사용 더 이상 지원되지 않음

토큰 효율적 도구 사용은 Claude Sonnet 3.7에서만 사용할 수 있습니다. Claude Sonnet 3.7에서 마이그레이션하고 토큰 효율적 도구 사용을 사용하는 경우, 요청에서 token-efficient-tools-2025-02-19 베타 헤더를 제거하는 것을 권장합니다. token-efficient-tools-2025-02-19 베타 헤더는 Claude 4 요청에 여전히 포함될 수 있지만 효과가 없습니다.

​
확장 출력 더 이상 지원되지 않음

확장 출력을 위한 output-128k-2025-02-19 베타 헤더는 Claude Sonnet 3.7에서만 사용할 수 있습니다. Claude Sonnet 3.7에서 마이그레이션하는 경우, 요청에서 output-128k-2025-02-19를 제거하는 것을 권장합니다. output-128k-2025-02-19 베타 헤더는 Claude 4 요청에 여전히 포함될 수 있지만 효과가 없습니다.

​
성능 고려사항

​
Claude Sonnet 4

  • Claude Sonnet 3.7에 비해 향상된 추론 및 지능 능력
  • 향상된 도구 사용 정확도

​
Claude Opus 4

  • 뛰어난 추론과 지능을 가진 가장 능력 있는 모델
  • Sonnet 모델보다 느림
  • 깊은 분석이 필요한 복잡한 작업에 최적

​
마이그레이션 체크리스트

  • API 호출에서 모델 ID 업데이트
  • 기존 요청 테스트 (변경 없이 작동해야 함)
  • 해당하는 경우 token-efficient-tools-2025-02-19 베타 헤더 제거
  • 해당하는 경우 output-128k-2025-02-19 베타 헤더 제거
  • 새로운 refusal 중단 이유 처리
  • 사용하는 경우 텍스트 편집기 도구 유형 및 이름 업데이트
  • undo_edit 명령을 사용하는 모든 코드 제거
  • 확장 사고와 함께 새로운 도구 인터리빙 기능 탐색
  • 최적의 결과를 위해 Claude 4 프롬프트 엔지니어링 모범 사례 검토
  • 프로덕션 배포 전 개발 환경에서 테스트

​
도움이 필요하신가요?

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