Claude Platform Docs
모델 및 가격Claude Haiku 5.5

Claude Haiku 5.5 마이그레이션 가이드

이 마이그레이션 가이드를 통해 이전 Haiku 모델에서 Claude Haiku 5.5로 전환하세요. Claude Haiku 5.5를 활성화하기 위한 안내에는 새 모델 ID, 오류를 반환하는 설정, 사고 관련 변경 사항, 그리고 시작 모델별 체크리스트가 포함되어 있습니다.

Claude Code

Claude Code가 코드를 대신 마이그레이션하도록 하세요

/claude-api migrate 이 프로젝트를 claude-haiku-5-5 모델로 마이그레이션해 줘

이 가이드는 Claude Haiku 4.5를 호출하는 코드를 Claude Haiku 5.5로 옮기는 방법을 다룹니다. Claude Haiku 3.5 또는 Claude Haiku 3을 호출하는 코드의 경우, Claude Haiku 3.5 및 이전 Haiku 모델에서 Claude Haiku 5.5로 마이그레이션의 변경 사항도 함께 적용하세요. 대신 Sonnet 또는 Opus 모델로 업그레이드하려면 마이그레이션 가이드를 참조하세요. Claude Haiku 4.5가 얼마나 오래 제공되는지는 모델 지원 중단을 참조하세요.

시작 모델별 마이그레이션 체크리스트

그룹을 위에서부터 차례로 진행하고, 현재 모델이 명시된 그룹까지 진행한 후 멈추세요. Claude Haiku 4.5를 사용 중이라면 첫 번째 그룹이 전체 목록입니다. 각 항목은 코드에서 수행해야 할 하나의 변경 사항입니다.

모든 시작 모델

  1. 모델 ID를 사용하는 플랫폼에 맞는 Claude Haiku 5.5 ID로 교체하세요. Claude Haiku 5.5 모델 ID 사용을 참조하세요.
  2. 동일한 텍스트가 더 많은 토큰으로 계산되고 큰 이미지는 더 많은 시각 토큰으로 계산되므로, 프롬프트의 토큰 수를 다시 세고 max_tokens 제한과 비용 추정치를 재검토하세요. 토큰 다시 세기를 참조하세요.
  3. 요청에서 thinking: {"type": "enabled", "budget_tokens": N}을 보내는 경우, thinking을 {"type": "adaptive"}로 변경하세요. 사고 구성을 참조하세요.
  4. 코드에서 첫 번째 콘텐츠 블록을 답변으로 읽는 경우, 대신 type으로 블록을 선택하세요. 사고 구성을 참조하세요.
  5. 요청에서 temperature, top_p, top_k를 제거하세요. 샘플링 매개변수 제거를 참조하세요.
  6. 모델이 이어서 작성하도록 요청의 messages를 어시스턴트 턴으로 끝내는 경우, 대신 사용자 턴으로 끝내세요. 어시스턴트 프리필 대체를 참조하세요.
  7. 컴퓨터 사용을 활용하는 경우, computer_20250124를 computer_toolset_20260801 도구 세트로 교체하세요. Amazon Bedrock에서는 computer_20251124도 작동합니다. 컴퓨터 사용을 도구 세트로 이전을 참조하세요.
  8. 저장된 대화를 다른 계정을 통해 재생하는 경우, 각 대화를 해당 대화를 생성한 계정을 통해 재생하세요. 사고 블록을 생성한 계정을 통해 재생을 참조하세요.
  9. 코드에서 대화 내 요청 간에 system, tools 또는 이전 messages를 변경하면서 사고 블록을 다시 보내는 경우, 대화를 추가 전용(append-only)으로 유지하세요. 이전 턴을 변경하지 않고 유지를 참조하세요.
  10. stop_reason: "refusal"을 처리하세요. Claude Haiku 5.5는 요청을 거절할 수 있는 안전 분류기를 실행하며, 서버 측 폴백이 없습니다. 안전장치 거절을 참조하세요.
  11. 프롬프트에서 모델에게 <thinking> 또는 <reasoning> 태그 등으로 응답에 추론 과정을 작성하도록 요청하는 경우, 해당 지시를 제거하세요. Claude Haiku 5.5는 이러한 지시가 포함된 요청을 거절하고 reasoning_extraction 카테고리를 반환할 수 있습니다. 안전장치 거부를 참조하세요.

조직에 Claude Haiku 4.5에 대한 Priority Tier 약정이 있다면 용량을 별도로 계획하세요. Claude Haiku 5.5에서는 Priority Tier가 지원되지 않습니다.

Claude Haiku 3.5 이하

  1. Claude Haiku 3.5 또는 Claude Haiku 3 모델 ID를 사용 중인 플랫폼의 Claude Haiku 5.5 ID로 교체하세요. Claude Haiku 3.5 및 이전 Haiku 모델에서 Claude Haiku 5.5로 마이그레이션을 참조하세요.
  2. code_execution_20250522 도구를 사용한다면 code_execution_20250825 이상으로 이전하세요.
  3. 텍스트 편집기 도구를 사용한다면 text_editor_20250728로 이전하세요.
  4. refusal 및 model_context_window_exceeded 중지 이유를 처리하세요.
  5. 코드가 도구 호출 문자열 매개변수를 정확히 일치시킨다면, 후행 줄바꿈을 허용하세요.
  6. 프롬프트를 검토하세요.

Claude Haiku 5.5 모델 ID 사용

Claude Haiku 4.5 모델 ID를 사용 중인 플랫폼의 Claude Haiku 5.5 ID로 교체하세요.

플랫폼Claude Haiku 4.5Claude Haiku 5.5
Claude APIclaude-haiku-4-5-20251001 또는 claude-haiku-4-5claude-haiku-5-5
Amazon Bedrockanthropic.claude-haiku-4-5anthropic.claude-haiku-5-5
Claude Platform on AWSclaude-haiku-4-5claude-haiku-5-5
Claude Models on Google Cloud (Anthropic managed)claude-haiku-4-5-20251001claude-haiku-5-5
Claude Models on Google Cloud (Google managed)claude-haiku-4-5@20251001claude-haiku-5-5
Microsoft Foundryclaude-haiku-4-5claude-haiku-5-5

claude-haiku-5-5는 날짜 접미사가 없고 별도의 별칭도 없는 고정 모델 ID입니다.

토큰 다시 세기

Claude Haiku 5.5는 Claude 4.7 이후 모델과 동일한 토크나이저를 사용합니다. 이 토크나이저를 사용하는 모든 모델과 마찬가지로, 동일한 입력 텍스트가 Claude Haiku 5.5에서는 Claude Haiku 4.5보다 약 30퍼센트 더 많은 토큰을 생성합니다. 정확한 증가량은 콘텐츠에 따라 다릅니다. 요청, 응답, 스트리밍 이벤트의 형태는 동일하게 유지됩니다. 달라지는 것은 토큰 단위로 측정하거나 예산을 책정하는 모든 것입니다:

  • usage 필드와 토큰 카운팅 결과가 동일한 텍스트에 대해 더 높게 나옵니다.
  • 주어진 토큰 수에 담기는 텍스트가 더 적습니다.
  • Claude Haiku 4.5에 맞춰 조정한 max_tokens 한도는 동등한 출력을 잘라낼 수 있습니다.
  • Claude Haiku 4.5의 토큰 수로 산출한 비용 추정치는 Claude Haiku 5.5의 토큰 수와 가격(긴 프롬프트에 대한 더 높은 가격 포함)으로 다시 계산해야 합니다. 가격 및 긴 컨텍스트 요금을 참조하세요.

큰 이미지도 더 많은 토큰이 소요될 수 있습니다. Claude Haiku 5.5는 고해상도 이미지 티어를 사용하며, 긴 변이 2,576픽셀 또는 4,784 시각 토큰을 초과하는 이미지를 축소합니다. Claude Haiku 4.5 및 이전 Haiku 모델은 표준 티어를 사용하며, 긴 변이 1,568픽셀 또는 1,568 시각 토큰을 초과하는 이미지를 축소합니다. 2,000 x 1,500픽셀 이미지는 Claude Haiku 5.5에서 Claude Haiku 4.5보다 약 2.5배 많은 시각 토큰이 소요됩니다. 해상도와 토큰 비용을 참조하세요.

Claude Haiku 4.5에서 측정한 토큰 수를 재사용하지 말고, model을 claude-haiku-5-5로 설정하여 프롬프트의 토큰 수를 세세요.

사고 구성

Claude Haiku 5.5는 Claude Haiku 4.5와 다른 방식으로 사고를 구성합니다. {"type": "enabled", "budget_tokens": N}의 thinking 값은 400 오류를 반환하므로, 이를 보내는 요청은 새로운 thinking 값이 필요합니다.

이전에는 Claude Haiku 4.5에 대한 요청이 토큰 예산과 함께 thinking을 enabled로 설정했습니다:

{
  "model": "claude-haiku-4-5",
  "max_tokens": 16000,
  "thinking": { "type": "enabled", "budget_tokens": 8000 },
  "messages": [{ "role": "user", "content": "..." }]
}

이후에는 Claude Haiku 5.5에 대한 동일한 요청이 적응형 사고를 사용합니다. thinking 값이 변경되고, output_config.effort가 모델이 얼마나 사고할지를 설정합니다:

{
  "model": "claude-haiku-5-5",
  "max_tokens": 16000,
  "thinking": { "type": "adaptive" },
  "output_config": { "effort": "medium" },
  "messages": [{ "role": "user", "content": "..." }]
}

“Adaptive thinking”(적응형 사고)은 기본적으로 켜져 있으므로, 요청에서 thinking을 설정하지 않더라도 응답이 하나 이상의 thinking 블록으로 시작할 수 있습니다. thinking을 설정하지 않거나 {"type": "adaptive"}로 설정하고, 노력 수준을 제어 수단으로 사용하세요. Claude Haiku 4.5에서 사고 없이 실행했거나 토큰을 절약하기 위해 작은 예산으로 실행했던 경우에는 더 낮은 노력 수준을 선택하세요. 낮은 수준에서는 모델이 사고를 덜 하며, 더 간단한 요청에서는 사고를 완전히 건너뛸 수 있습니다. 프롬프팅 안내는 노력 수준을 사용하여 사고 제어를 참조하세요. 콘텐츠 블록은 위치가 아닌 type 필드로 선택하고, thinking 블록은 도구 결과와 함께 수정하지 않은 채로 다시 전달하세요.

사고 토큰은 max_tokens에 포함되므로, max_tokens가 작은 요청은 thinking 블록 이후, 텍스트가 나오기 전에 stop_reason: "max_tokens"로 중지될 수 있습니다. Claude Haiku 4.5에 작은 max_tokens를 설정했다면, 사고를 위한 여유를 두도록 값을 늘리거나 더 낮은 노력 수준을 선택하세요.

이전 어시스턴트 턴의 사고 블록은 컨텍스트에 유지되며 입력 토큰으로 계산됩니다. 반면 Claude Haiku 4.5는 최신 턴의 사고 블록만 유지합니다. 따라서 멀티턴 대화는 토크나이저 변경만으로 설명되는 것보다 더 많은 입력 토큰을 포함합니다. 이전 블록을 제거하려면 사고 블록 지우기를 사용하세요. 모델별 사고 블록 보존을 참조하세요.

기본적으로 Claude Haiku 5.5는 각 thinking 블록을 빈 thinking 필드와 signature만 포함하여 반환합니다. 반면 Claude Haiku 4.5는 요약된 사고를 반환합니다. 요약된 사고를 받으려면 thinking: {"type": "adaptive", "display": "summarized"}를 설정하세요.

Claude Haiku 5.5는 강제 tool_choice(any 또는 이름이 지정된 도구)를 허용하지만, 응답은 도구 호출로 시작하며 thinking 블록이 없습니다. 모델이 도구를 호출하기 전에 사고하도록 하려면 tool_choice: {"type": "auto"}를 사용하고 프롬프트에서 도구를 언제 사용할지 명시하세요.

Claude Haiku 4.5에서 Claude Haiku 5.5로 전환한 대화는 추론을 유지합니다. 다른 전환의 경우에는 두 모델에 따라 달라집니다:

전환추론 유지 여부
Claude Haiku 4.5 이하, Claude Sonnet 5 이하, 또는 Claude Opus 4.8 이하에서 Claude Haiku 5.5로예
그 외 모든 모델에서 Claude Haiku 5.5로아니요. API는 오류 없이 해당 모델의 사고 블록을 제외합니다.
Claude Haiku 5.5에서 Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.2 또는 Claude Mythos 5.2로예, Claude API와 Claude Models on Google Cloud (Google managed)에서만 해당합니다
Claude Haiku 5.5에서 그 외 모든 모델로아니요

모델을 전환했다가 되돌아오기를 참조하세요. Claude Haiku 5.5가 관련되지 않은 전환에 대해서는 Claude API에서 추론을 유지하는 모델 전환을 참조하세요.

샘플링 매개변수 제거

Claude Haiku 5.5에서는 temperature, top_p, top_k를 생략하고 대신 프롬프트를 사용하여 모델의 동작을 안내하세요.

어시스턴트 프리필 대체

프리필은 모델이 이어서 작성하는 messages의 마지막 어시스턴트 턴입니다. Claude Haiku 4.5는 사고가 꺼져 있을 때 프리필을 허용합니다. Claude Haiku 5.5는 사고가 꺼져 있더라도 400 오류로 이를 거부합니다. messages를 사용자 턴으로 끝내고, 각 프리필을 그 용도에 따라 대체하세요:

  • 출력 형식: 구조화된 출력을 사용하거나, 분류에는 enum 필드가 있는 도구를 사용하세요.
  • 서두: 시스템 프롬프트에서 직접적인 답변을 요청하세요.
  • 이어쓰기: 사용자 메시지로 옮기세요. 예: "이전 응답이 중단되었으며 [previous_response]로 끝났습니다. 중단된 부분부터 계속하세요."
  • 컨텍스트 리마인더: 사용자 턴에 넣으세요.

컴퓨터 사용을 도구 세트로 이전

Claude Haiku 4.5는 computer-use-2025-01-24 베타 헤더와 함께 computer_20250124 도구를 통해 컴퓨터 사용을 지원합니다. Claude Haiku 5.5는 computer_toolset_20260801 도구 세트를 통해 컴퓨터 사용을 지원합니다. computer_20250124를 선언하는 Claude Haiku 5.5 요청은 400 오류를 반환합니다.

통합을 도구 세트로 이전하려면 computer-use-2025-01-24 베타 헤더를 제거하고 tools 항목을 {"type": "computer_toolset_20260801"}로 교체하세요. 그런 다음 computer_20251124에서 마이그레이션하기에 설명된 다른 요청 및 에이전트 루프 변경 사항을 적용하세요. input.action이 아닌 각 멤버 tool_use 블록의 name과 toolset_name을 기준으로 분기 처리하세요. 한 턴의 모든 해당 블록을 처리하고 결과에 toolset_name을 그대로 반환하세요. 도구 세트에서는 확대/축소(zoom)가 기본적으로 활성화되어 있습니다. 사용 환경에서 이를 구현하지 않는 경우 "configs": {"zoom": {"enabled": false}}를 추가하세요. fine-grained-tool-streaming-2025-05-14 베타 헤더를 보내는 경우 이를 제거하세요. 도구 세트 항목과 함께 사용하면 400 오류를 반환합니다.

Amazon Bedrock에서 Claude Haiku 5.5는 computer-use-2025-11-24 베타 헤더와 함께 computer_20251124 도구도 허용합니다.

Claude Haiku 5.5는 웹페이지 내 작업을 위한 브라우저 사용 도구(browser_toolset_20260801)를 지원합니다. Claude Haiku 4.5는 이를 지원하지 않습니다.

사고 블록을 생성한 계정을 통해 재생

Claude Haiku 5.5의 사고 블록(thinking block)은 해당 블록을 생성한 계정 또는 그 계정에 연결된 계정에서만 작동합니다. 다른 계정이 이러한 블록을 보내면 API는 모델이 블록을 받기 전에 해당 블록을 제외하며, 요청은 그 추론 없이 성공합니다. 이는 대화를 저장한 후 다른 계정을 통해 다시 재생하는 코드에 영향을 미칩니다. 예를 들어 하나의 대화 저장소에서 여러 고객에게 서비스를 제공하는 서비스가 이에 해당합니다. 각 대화는 해당 대화를 생성한 계정을 통해 재생하세요. 계정 및 클라우드 플랫폼을 참조하세요.

이전 턴을 변경하지 않고 유지

대화는 추가 전용(append-only)으로 유지하세요. Claude Haiku 5.5 사고 블록은 그 앞에 전송된 모든 내용, 즉 system 프롬프트, tools, 그리고 이전의 모든 메시지가 변경되지 않은 동안에만 유효합니다.

“prefix check”(접두사 검사)를 통과하지 못하면 400 오류가 발생할 수도 있고 발생하지 않을 수도 있습니다. 두 경우를 모두 식별하고 처리하려면 사고 블록에 대한 접두사 검사를 참조하세요.

오류를 유발하는 변경 사항과 대신 수행해야 할 작업에 대해서는 코드가 시스템 프롬프트, 도구 또는 기록을 변경하는 경우를 참조하세요.

Claude Haiku 3.5 및 이전 Haiku 모델에서 Claude Haiku 5.5로 마이그레이션

Claude Haiku 3.5는 Claude API, Amazon Bedrock, Claude Models on Google Cloud (Google managed)에서 종료되었습니다. Claude Haiku 3은 Claude API와 Claude Models on Google Cloud (Google managed)에서 종료되었습니다. 모델 지원 중단을 참조하세요.

두 모델 중 어느 것에서 시작하든, 먼저 앞의 모든 섹션을 적용한 다음 아래 변경 사항을 적용하세요:

  • 모델 ID: claude-3-5-haiku-20241022, 그 별칭인 claude-3-5-haiku-latest, 또는 claude-3-haiku-20240307을 claude-haiku-5-5로 교체하세요. Claude Models on Google Cloud (Google managed)에서는 claude-3-5-haiku@20241022를 claude-haiku-5-5로 교체하세요. Amazon Bedrock에서는 Claude Haiku 5.5 모델 ID 사용에 있는 Claude Haiku 5.5 ID를 사용하세요.
  • 코드 실행: Claude Haiku 5.5는 code_execution_20250825 및 이후 버전을 허용합니다. Python 전용 code_execution_20250522를 사용한다면 그중 하나로 이전하세요. 최신 도구 버전으로 업그레이드를 참조하세요.
  • 텍스트 편집기: 텍스트 편집기 도구를 사용한다면 undo_edit 명령이 없는 text_editor_20250728(도구 이름 str_replace_based_edit_tool)로 이전하세요. 텍스트 편집기 도구를 참조하세요.
  • 중지 이유: refusal과 model_context_window_exceeded를 처리하세요. 중지 이유 및 폴백을 참조하세요.
  • 후행 줄바꿈: Claude 4.5 이후 모델은 도구 호출 문자열 매개변수의 후행 줄바꿈을 유지합니다. 코드가 이러한 문자열을 정확히 일치시킨다면, 후행 줄바꿈을 허용하세요.
  • 프롬프트: Claude 4 이후 모델은 더 간결하고 직접적인 커뮤니케이션 스타일을 가지며 명시적인 지시가 필요합니다. Claude Haiku 5.5 프롬프팅과 프롬프팅 모범 사례를 기준으로 프롬프트를 검토하세요.

이 페이지가 도움이 되었나요?