Claude Haiku 5.5로의 마이그레이션: Haiku 4.5에서 변경되는 6가지와 단가 5배 조건
요약
Claude Haiku 4.5에서 5.5로 마이그레이션 시 변경되는 주요 기능과 단가 변화를 분석했습니다. 특히 'thinking' 및 'temperature' 같은 기존 파라미터는 더 이상 지원되지 않으며, 사고량은 이제 `effort` 설정으로 제어됩니다. 또한, 대화 기록 편집이나 특정 조직 경계 처리 등 새로운 규칙들이 추가되어 개발 시 주의가 필요합니다.
핵심 포인트
- Haiku 5.5 출시로 'thinking' 및 'temperature' 파라미터 사용 불가
- 사고량(Thinking)은 이제 `effort`(`low`~`max`) 설정으로 제어됨
- 프롬프트가 10만 토큰 초과 시 단가가 5배 부과되는 최초의 모델
- 대화 기록 편집 및 조직 경계 처리 등 새로운 API 규칙을 숙지해야 함
2026년 10월 7일에 Claude Haiku 5.5(claude-haiku-5-5)가 출시되었습니다. Haiku 계열 모델 중 처음으로 adaptive thinking과 effort를 갖추었으며, 1M 컨텍스트와 128K 출력을 지원합니다. API 형태는 Opus 5.5 / Sonnet 5.5에 맞춰져 있습니다. 단가는 $0.10 / $0.50로 Haiku 4.5의 1/10 수준이지만, 프롬프트가 10만 토큰을 초과할 경우 5배가 되는 최초의 모델이기도 합니다.
Haiku 4.5는 budget_tokens, temperature, 프리필(prefill) 등 모든 기능을 사용할 수 있었던 마지막 세대였기 때문에, 단순히 model ID만 변경해도 다른 5.5 계열보다 더 많은 부분이 깨질 수 있습니다. 공식 마이그레이션 가이드(2026년 10월 12일 기준)를 바탕으로, 400 에러가 발생하는 6가지 항목과 조용히 변경되는 사항들을 정리했습니다.
직접 확인한 내용
2026년 10월 12일에 실제 API로 첫 번째와 두 번째 항목, 그리고 disabled effort 제한을 테스트했습니다. 모두 max_tokens: 64의 짧은 요청으로도 400 에러가 발생하지 않았습니다.
1) thinking: {type: "enabled", budget_tokens: 2000}
HTTP 400 "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.
2) temperature: 0.2
...
네 번째 항목에서 disabled가 low일 때 통과하는 것을 확인했으며, usage.output_tokens_details.thinking_tokens이 0으로 반환되는 것도 보였습니다. 세 번째부터 여섯 번째 항목(프리필, computer_20250124, 히스토리 편집, 조직 경계)은 공식 마이그레이션 가이드에 언급되어 있지만, 실제 API에서는 테스트하지 않았습니다.
제 코드의 경우 Haiku 4.5를 사용하는 부분은 순환 에이전트 워커 하나뿐이었고, thinking이나 temperature를 전달하고 있지 않아 모델 ID만 변경하면 되었습니다.
400 에러가 발생하는 6가지 항목
budget_tokens가 400인 경우
Haiku 4.5
thinking={"type": "enabled", "budget_tokens": 8000}
Haiku 5.5
...
사고량은 `effort`(`low` ~ `max`)로 결정합니다. 기본값은 `medium`입니다. 사고를 비활성화하는 `thinking: {
### 5. 대화 기록을 편집하면 400
Haiku 4.5에는 없던 검사입니다. `system`
・`tools`
・과거 턴을 변경한 후에 사고 블록(thinking block)을 다시 보내면 400 (2026년 8월 31일 이후에 생성된 계정에서는 기본으로 검사되며, 그 이전에는 `prefix_mismatch_behavior`를 보냈을 때만). 기록은 추가만 하고, 지시 변경은 대화 도중의 `role: "system"` 메시지로 합니다. 자세한 내용은 별도 기사(Invalid signature in thinking block)에 작성했습니다.
### 6. 사고 블록은 만든 조직에서만 읽을 수 있다
다른 조직에서 보내면, 에러가 나지 않고 **조용히 버려지며** 추론 없이 답변합니다. 여러 고객의 대화를 하나의 스토어에서 돌리는 서비스는, 생성한 조직에서 재생해 주세요.
## 에러가 나지 않게 변하는 것들
-
**사고(thinking)가 기본으로 켜짐.** `thinking`을 작성하지 않은 코드는 Haiku 5.5에서 사고를 시작하고, `max_tokens`는 사고 + 본문의 총 상한이므로, 작은 값은 `thinking` 블록만으로 잘려서 본문이 비게 됩니다. `content[0].text`가 아니라 `type`으로 선택합니다. `display`의 기본값은 `omitted`입니다.
- **토큰이 약 30% 증가한다.** 4.7 이후와 동일한 새 토크나이저를 사용합니다. 이미지도 고해상도 티어(2000×1500으로 약 2.5배). `count_tokens`로 다시 측정하세요.
- **모든 턴의 사고 블록이 입력에 남는다.** Haiku 4.5는 직전 턴분만 했습니다. 멀티 턴 입력은 30% 이상 늘어납니다. 지우려면 context editing의 thinking block clearing (직접 줄 경우 5번에 해당)을 사용하세요.
- **캐시 최소가 512 토큰** (4.5는 4,096). 포기했던 짧은 프롬프트도 효과를 볼 수 있습니다.
- **거절이 발생했다.** `cyber` / `frontier_llm` / `bio` / `general_harms`. HTTP 200에 `stop_reason: "refusal"`입니다. **서버 측 폴백(fallback)은 없으므로** 직접 처리해야 합니다. 재전송해도 대부분 다시 거절됩니다.
- **Priority Tier 미지원.** 컨텍스트 인식 태그도 주입되지 않습니다 (예산은 task budgets로). -
**강제** Opus 5.5 / Sonnet 5.5와 달리 400이 되지 않는 `tool_choice`는 사용할 수 있습니다.
## 단가가 5배가 되는 조건
| 프롬프트 길이 | 입력 | 출력 | 캐시 읽기 | 배치(Batch) |
|---|---|---|---| :---: |
| 10만 토큰 이하 | $0.10 | $0.50 | $0.01 | $0.05 / $0.25 |
| 10만 토큰 초과 | $0.50 | $2.50 | $0.05 | $0.25 / $1.25 |
'프롬프트 길이'는 **1 요청의 입력 토큰 총합으로, 캐시 읽기와 쓰기를 포함합니다**. 캐시가 적용되어 저렴해졌더라도, 합계가 임계값을 넘으면 해당 요청은 높은 단가의 단가를 따릅니다. 판정은 요청별로 이루어지며, 이전 요청의 청구액에는 영향을 주지 않습니다.
즉, 긴 대화를 Haiku 5.5로 계속하는 에이전트는, 입력이 10만 토큰에 가까워졌을 때 compaction으로 줄이거나, 길이 때문에 단가가 변하지 않는 Sonnet 5.5 ($2 / $10)와 비교할 필요가 있습니다. 10만 토큰 초과의 Haiku 5.5 ($0.50 / $2.50)는 Sonnet 5.5의 1/4이므로, 여전히 저렴한 경우가 많지만, 'Haiku는 1/20'이라는 전제에서는 견적이 틀릴 수 있습니다.
## effort의 시작점
공식적인 기준은, 대부분의 작업(에이전트적 코딩 포함)이 `medium`이고, 채팅・짧은 도구 작업・단순한 대량 처리가 `low`이며, 지식 작업・긴 에이전트 작업・엄격한 지시 추종이 `high`입니다. `low`에서는 긴 에이전트 작업을 할 때 검색을 건너뛰거나・빨리 멈추거나・검사를 건너뛰는 경우가 늘어납니다. 프롬프트로
보내는 것(날짜를 넘기면 최신 턴에 작성).
## 정적으로 찾기
`model`
을 변경하기 전에, 해당 부분을 file:line으로 출력하는 도구를 업데이트했습니다. Haiku 5.5용 판별은 `--target haiku-5-5`입니다.
git clone https://github.com/volvox-ltd/claude5-migration-kit
python claude5-migration-kit/scan.py path/to/your/app --target haiku-5-5
## 요약
| # | 증상 | 해결 방법 |
|---|---|---|
| 1 | `budget_tokens`에서 400 | `adaptive` + `effort` |
| 2 | `temperature`에서 400 | 삭제 |
| 3 | 프리필(Prefill)에서 400 | 구조화 출력 (Bedrock은 자체 검증) |
| 4 | `computer_20250124`에서 400 | 도구 세트, Bedrock은 `computer_20251124` |
| 5 | 히스토리 편집에서 400 | 추가만 가능 |
| 6 | 다른 조직에서 생각이 사라짐 | 생성한 조직에서 재생
Opus 5.5 / Sonnet 5.5의 변경 사항(`disabled` 불가, 강제 도구 불가 등)은 별도 글로, 모델별 체크리스트와 가격표는 Zenn의 책 『Claude 5 세대 이행 가이드』 제7장(10월 12일에 Haiku 5.5 부분 추가)에 정리되어 있습니다. 제1~2장은 무료입니다.
공식: https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide / https://platform.claude.com/docs/en/about-claude/pricing
### 토론

AI 자동 생성 콘텐츠
본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기