작성자 주석: 이 글은 2026-11-08(UTC+8) Anthropic 공식 문서와 2026-11-09 10:40에 업데이트된 APIYI Claude 사고 파라미터 가이드를 바탕으로 정리했으며, 기준 확인 날짜는 2026-11-13입니다. claude-opus-5-5와 claude-sonnet-5-5의 thinking 파라미터에서 400 오류를 피하는 데 도움이 되도록 작성했어요.
claude-opus-5-5에서 thinking의 type을 disabled로 전달하면 API가 곧바로 400을 반환합니다. 이는 2026-11-08(UTC+8) Anthropic 공식 문서에 명시된 기준이에요. APIYI(apiyi.com)는 2026-11-09 10:40에 Claude 사고 파라미터 가이드를 동기화해 업데이트하면서 두 모델 ID의 올바른 표기법을 정리했습니다. 이 글에서는 이번 변경이 Claude API 호출 측에 미치는 영향을 빠르게 짚어볼게요.
근거 없는 소문이 아니에요: 두 가지 핵심 결론 모두 문서를 기준으로 합니다. claude-opus-5-5는 사고를 끌 수 없고 effort만 낮출 수 있으며, claude-sonnet-5-5에서 사전 사고를 끄려면 between_tools를 사용해야 합니다.
핵심 가치: 3분이면 두 모델 ID의 올바른 표기법, between_tools의 파라미터 경계, 그리고 400 오류를 디버깅하는 방법을 파악할 수 있습니다.
핵심 정보 한눈에 보기: claude-opus-5-5와 claude-sonnet-5-5의 thinking 기준
결론 표를 먼저 보고, 하나씩 풀어볼게요:
| 정보 항목 | 상세 내용 |
|---|---|
| 공식 기준 | 2026-11-08(UTC+8) Anthropic 공식 문서 |
| APIYI 가이드 업데이트 | 2026-11-09 10:40, docs.apiyi.com 동기화 완료 |
| claude-opus-5-5 | thinking을 전달하지 않으면 적응형 사고, disabled를 전달하면 400 반환 |
| claude-sonnet-5-5 | thinking을 전달하지 않으면 마찬가지로 적응형 사고, 선행 사고를 끄려면 between_tools |
effort 기본값 |
Opus 5.5는 medium, Sonnet 5.5는 high |
| 최대 출력 | 두 모델 ID 모두 128000이며, 사고 토큰이 여기에 포함됨 |
claude-opus-5-5의 기준은 꽤 직관적이에요. 요청에 thinking 필드를 전달하지 않으면 모델이 적응형 사고 모드로 들어가서, 이번 호출에서 사고를 할지, 얼마나 깊게 할지를 스스로 결정해요. 반대로 thinking의 type을 disabled로 설정하면 인터페이스가 조용히 무시하지 않고 곧바로 400을 반환하죠. 다시 말해 이 모델 ID에는 사고를 끄는 스위치가 없고, 문서가 제시하는 유일한 조절 수단은 effort를 낮추는 것이며 기본 단계는 medium이에요.
claude-sonnet-5-5는 상황이 조금 달라요. 마찬가지로 thinking을 전달하지 않는 적응형 사고를 지원하지만, 공식적으로 인정된 종료 경로가 하나 더 있어요. type을 between_tools로 설정하면 선행 사고를 끄고 도구 호출 사이의 진행 업데이트만 유지할 수 있죠. 이 경로의 경계도 명확하게 적혀 있으니 아래 표를 그대로 대조해 보세요:
| 제약 항목 | 문서 기준 |
|---|---|
effort 값 |
low, medium, high만 허용 |
| 단계 상한 | high보다 높을 수 없음 |
| 조합 제한 | display 또는 budget_tokens와 동시에 사용할 수 없음 |
| 실제 효과 | 선행 사고를 끄고, 도구 호출 사이의 진행 업데이트만 유지 |
놓치기 쉬운 디테일이 하나 더 있어요. 사고 토큰은 max_tokens에 포함돼요. 두 모델 ID의 최대 출력은 모두 128000인데, 요청에서 max_tokens를 너무 낮게 잡으면 사고가 먼저 예산의 절반 이상을 차지해서 본문이 잘려 나갈 수 있어요. “응답이 이상하게 짧아졌다”는 문제를 디버깅할 때는 사고 점유량을 먼저 확인해 보는 게 좋아요.
그림 설명: 그림의 호출 경로는 APIYI apiyi.com의 Anthropic 네이티브 형식 게이트웨이를 예시로 삼았어요. Anthropic 형식을 사용할 때 base 주소는 https://api.apiyi.com이며, /v1이 붙은 형태로 쓰지 않도록 주의하세요.
영향 분석: disabled가 400을 반환할 때 영향을 받는 호출자
이번 기준 변경이 호출자에 미치는 영향은 오류 처리, 파라미터 조합, 예산 계획 세 가지에 집중돼요. 하나씩 나눠 보면 더 직관적일 거예요.
기존 코드에 미치는 영향: disabled 사용 방식 전환
| 시나리오 | 기존 방식 | 현재 결과 | 올바른 방법 |
|---|---|---|---|
| claude-opus-5-5에서 사고를 끄고 싶은 경우 | type에 disabled 전달 |
400 반환 | 끌 수 없고 effort만 낮출 수 있음 |
| claude-sonnet-5-5에서 응답 전 사고를 끄고 싶은 경우 | type에 disabled 전달 |
400 반환 | between_tools로 전환 |
| 사고 예산을 정밀하게 제어하고 싶은 경우 | between_tools와 budget_tokens 조합 |
조합이 허용되지 않음 | 둘을 함께 전달할 수 없어 effort 세 단계로 전환 |
| 사고가 출력을 잠식할까 걱정되는 경우 | max_tokens를 아주 작게 설정 |
본문이 잘림 | 사고가 max_tokens에 포함되므로 여유를 남김 |
첫 번째 영향은 파라미터 조합 제약이 늘어난다는 점이에요. between_tools는 budget_tokens나 display와 동시에 나올 수 없어요. 즉 사고 예산을 정밀하게 제어하려는 방식은 이 경로에서는 통하지 않고, low, medium, high 세 단계로 간접 조정해야 해요. 여기에 “사고 토큰이 max_tokens에 포함된다”는 규칙까지 더해지므로 호출자는 effort와 max_tokens 사이에서 다시 균형을 찾아야 해요.
두 번째 영향은 분기 로직도 업데이트해야 한다는 점이에요. 스크립트가 모델 ID에 따라 disabled 전달 여부를 결정한다면, 이 두 ID를 만나면 분기를 타야 해요. 전자는 “끌 수 없다”는 현실을 받아들이고 effort를 낮추고, 후자는 between_tools로 전환해야 해요. 이런 분기를 한 곳의 설정에 모아 관리하면 앞으로 기준이 또 바뀌더라도 수정 범위를 최소화할 수 있어요.
참고로 같은 페이지에는 Fable 5.1과 Fable 5도 disabled를 전달하면 똑같이 400이 나고, 역시 끌 수 없다고 적혀 있어요. Haiku 5.5와 Opus 5는 effort가 high 이하일 때 여전히 disabled를 사용할 수 있어요. 코드가 여러 모델 ID를 동시에 지원한다면 전역에 같은 방식을 적용하기보다 모델별로 스위치 매트릭스를 관리하는 편이 좋아요.
비용 구조에 미치는 영향: thinking 토큰과 사용량
claude-sonnet-5-5의 APIYI(apiyi.com) 통합 가격표 기준 과금은 입력 $2, 출력 $10, 캐시 읽기 $0.1이에요. 사고 토큰이 max_tokens에 포함되므로, 응답 전 사고를 끌지 여부와 어느 effort 단계를 선택하느냐가 토큰 사용량에 직접 반영돼요. 호출이 잦은 환경에서는 이 차이가 더 크게 드러나니, 코드를 수정할 때 가볍게라도 비용 계산을 해볼 만해요.
이미지 설명: 기준은 2026-11-08 공식 문서를 정리한 것이며, APIYI apiyi.com 문서 센터에서 원문과 대조해 확인할 수 있어요.
| 모델 ID | disabled 사용 가능 여부 |
문서 기준 |
|---|---|---|
| claude-opus-5-5 | 사용 불가, 400 반환 | 사고를 끌 수 없고 effort만 낮출 수 있음 (기본 medium) |
| claude-sonnet-5-5 | 사용 불가, 400 반환 | between_tools로 전환 (기본 high) |
| Fable 5.1 / Fable 5 | 사용 불가, 400 반환 | 역시 끌 수 없음 |
| Haiku 5.5 / Opus 5 | effort가 high 이하일 때 사용 가능 |
기존 방식은 이 두 ID에서만 유효 |
claude-sonnet-5-5의 between_tools를 빠르게 검증하는 방법
변경 사항을 배포하기 전에, 먼저 소량 트래픽으로 동작 차이를 검증해 보는 게 좋아요. APIYI(apiyi.com)에서 가입하고 API 키를 발급받으면 신규 사용자에게 무료 테스트 한도가 제공돼요. 요청은 https://api.apiyi.com으로 보내고, 요청 본문에서 thinking의 type을 between_tools로 설정한 뒤 effort를 세 단계 중 하나로 지정해서 먼저 한 라운드 실행해 보세요. 그다음 thinking을 전달하지 않은 적응형 모드와 비교하면서 출력 구조와 토큰 사용량 변화를 관찰하면 돼요.
🚀 빠른 검증 팁: APIYI apiyi.com을 통해 무료 테스트 한도를 받은 뒤, 같은 프롬프트 세트로
between_tools모드와 적응형 모드를 각각 실행해 보세요. 차이를 확인한 다음에 기존 코드를 수정하는 게 좋아요. 플랫폼은 Claude, OpenAI, Gemini 등 주요 모델을 통합 호출할 수 있고, OpenAI 호환 인터페이스는 사용량 기반 과금이라 수평 비교와 전환이 편해요.
자주 묻는 질문 FAQ: disabled, between_tools, 400 오류
Q1: claude-opus-5-5는 정말 사고(thinking)를 끌 수 있나요?
아니요. 2026-11-08 공식 가이드에 따르면 `disabled`를 전달하면 400이 반환되고, 이 모델 ID에는 사고를 끄는 스위치가 없어요. `effort`를 통해서만 사고 깊이를 낮출 수 있고, 기본 단계는 `medium`이에요. 완전히 사고 없이 동작해야 하는 시나리오라면 모델 ID를 바꾸는 수밖에 없어요.
Q2: claude-sonnet-5-5의 between_tools는 budget_tokens와 함께 사용할 수 있나요?
아니요. 문서에 `between_tools`는 `display`나 `budget_tokens`를 동시에 포함할 수 없다고 명확히 적혀 있어요. 대응하는 `effort`는 `low`, `medium`, `high` 세 단계만 허용되고 `high`보다 높게 설정할 수 없어요. 사고 예산을 세밀하게 제어하고 싶다면 적응형 모드로 돌아가거나 모델 ID를 바꾸는 수밖에 없어요.
Q3: 제 Claude 요청이 갑자기 400을 반환하는 이유는 무엇인가요?
먼저 요청 본문에서 `thinking`의 `type`을 `disabled`로 설정했는지 확인해 보세요. claude-opus-5-5와 claude-sonnet-5-5에서는 이게 문서에 명시된 트리거 조건이에요. 확인했다면 이 글의 대조표대로 처리하면 돼요. 전자는 `effort`를 낮추고, 후자는 `between_tools`로 전환하는 거예요. 적용되는 작성 방식은 2026-11-08(UTC+8) 공식 문서를 기준으로 하며, APIYI 페이지는 2026-11-09 10:40에 동기화되었어요.
Q4: claude-sonnet-5-5의 between_tools 효과를 빠르게 검증하려면 어떻게 해야 하나요?
APIYI(apiyi.com)에서 계정을 등록하고 API 키를 발급받으면 신규 사용자에게 무료 테스트 한도가 있어요. 요청은 `https://api.apiyi.com`으로 보내고 `thinking`의 `type`을 `between_tools`로, `effort`는 아무 단계나 하나 선택해서 한 라운드 실행하면 적응형 모드와의 차이를 비교할 수 있어요.
Q5: 사고 토큰이 출력 예산을 잡아먹을 수 있나요?
그럴 수 있어요. 사고 토큰은 `max_tokens`에 포함되고, 두 모델 ID의 최대 출력은 모두 128000이에요. 요청에서 `max_tokens`를 너무 낮게 설정하면 사고가 먼저 예산을 소모해 본문이 잘릴 수 있으니, 본문을 위해 충분한 공간을 남겨 두는 게 좋아요.
claude-opus-5-5와 claude-sonnet-5-5 핵심 요점 Key Takeaways
- claude-opus-5-5는 사고를 끌 수 없어요:
disabled를 전달하면 바로 400이 발생하고,effort로만 단계를 낮출 수 있으며 기본값은medium이에요. - claude-sonnet-5-5는
between_tools로 전환: 사전 사고를 끄고, 도구 호출 사이의 진행 업데이트만 유지해요. - 세 가지 파라미터 제약:
effort는low,medium,high만 가능하고high보다 높일 수 없으며,display와budget_tokens를 함께 지정할 수 없어요. - 예산 규칙: 사고 토큰은
max_tokens에 포함되고, 두 ID의 상한은 모두 128000이에요. - 검증 경로: APIYI apiyi.com, Anthropic 형식 base는
https://api.apiyi.com이며/v1을 붙이지 마세요.
정리: 400을 피하는 세 가지 방법
claude-opus-5-5와 claude-sonnet-5-5의 사용 기준은 세 문장으로 요약할 수 있어요.
- claude-opus-5-5:
disabled를 전달하면 400이 발생하고, 사고를 끌 수 없으니effort를 낮추는 방법밖에 없어요. - claude-sonnet-5-5: 사전 사고를 끄려면
between_tools로 전환하고,effort는 세 단계만 사용하며,display와budget_tokens는 함께 지정하지 마세요. - 예산: 사고 토큰은
max_tokens에 포함되고 상한은 128000이니 본문용 여유를 남겨 두세요.
이 400 오류에 막혀 있다면 APIYI apiyi.com에서 무료 테스트 크레딧으로 between_tools를 한 번 실행해 보고, 동작을 확인한 뒤 기존 코드를 수정하는 것을 권장해요. 플랫폼에서 API 키 하나로 OpenAI, Claude, Gemini 등 주요 모델을 호출할 수 있고, 사용량 기반 과금이라 빠르게 비교하고 전환하기에 적합해요.
📚 참고 자료
- APIYI Claude 사고 파라미터 가이드: effort와 thinking의 적용 방법
- 링크:
docs.apiyi.com/api-capabilities/claude-effort-thinking.md -
설명: 2026-11-09 10:40에 업데이트된 버전으로, 이 글의 주요 사실 출처예요
-
APIYI 가이드 갱신 소식: 이번 기준 동기화에 대한 공식 설명
- 링크:
docs.apiyi.com/live/2026-11/claude-thinking-guide-refresh.md -
설명: 2026-11-08 공식 문서와 기준을 맞춰 가는 과정을 기록했어요
-
Anthropic 공식 문서: thinking 파라미터의 원래 기준
- 링크:
docs.anthropic.com - 설명: 함께 비교해 읽으면서 최신 사용법을 확인하는 걸 권장해요
작성자: APIYI 기술 팀
기술 교류: APIYI 웹사이트 첫 화면에서 문의해 주세요. 더 많은 자료는 docs.apiyi.com 문서 센터에서 확인할 수 있어요
