클로드 하이쿠 5.5 API 사용 방법

Claude Haiku 5.5 API를 사용하려면 `https://api.anthropic.com/v1/messages`로 POST 요청을 보내십시오. 이때 `"model": "claude-haiku-5-5"`를 포함하고, `x-api-key` 헤더에 키를, `anthropic-version: 2023-06-01`을 명시해야 합니다. 최대 10만 토큰 프롬프트의 경우 백만 입력/출력 토큰당 $0.10/$0.50의 비용이 들며(그 이상은 $0.50/$2.50), 최대 100만 토큰의 컨텍스트를 읽고, 12만 8천 토큰까지 작성하며, 적응형 사고(adaptive thinking)가 켜진 상태에서 기본적으로 `medium` 노력을 사용합니다.

Anthropic은 2026년 10월 7일 Haiku 5.5를 출시했으며, 이는 노력 수준(effort levels)을 갖춘 최초의 Haiku입니다(Claude Haiku 5.5란 무엇인가에서 사양 및 포지셔닝을 다룹니다). 이 가이드는 curl, Python, TypeScript에서의 첫 호출, 이어서 노력(effort), 사고(thinking), 캐싱(caching), 배치(batch), 거부(refusals) 및 에이전트 툴셋(agent toolsets)에 대해 다룹니다. 아래의 모든 요청은 Apidog에 저장하고 검증할 수 있습니다.

버튼

Claude Haiku 5.5 API 한눈에 보기

매개변수	Haiku 5.5 동작
모델 ID	`claude-haiku-5-5` (Bedrock: `anthropic.claude-haiku-5-5`); 별도 별칭 없음
MTok당 가격, 최대 10만 토큰 프롬프트	입력 $0.10, 출력 $0.50, 캐시 읽기 $0.01
MTok당 가격, 10만 토큰 초과 프롬프트	입력 $0.50, 출력 $2.50, 캐시 읽기 $0.05
컨텍스트 / 최대 출력	100만 / 12만 8천; `output-300k-2026-03-24` 베타 헤더가 있는 배치(Batch)에서는 30만
`output_config.effort`	`low`, `medium` (기본값), `high`, `xhigh`, `max`
`thinking`	기본적으로 `adaptive`; `high` 노력 이하에서만 `disabled`
`thinking.display`	기본적으로 비어있는 `thinking` 필드; `summarized`는 가독성 있는 텍스트 반환
`temperature`, `top_p`, `top_k`	기본값이 아닌 값은 400 반환
어시스턴트 사전 채우기	사고(thinking)가 꺼져 있어도 400 반환
최소 캐시 가능 프롬프트	512 토큰 (Haiku 4.5에서는 4,096)

출처: Haiku 5.5 모델 페이지 및 Claude API 가격 책정 문서.

첫 Claude Haiku 5.5 API 호출

Claude 콘솔에서 키를 생성하고(Anthropic API 키 가이드 참조), `ANTHROPIC_API_KEY`로 내보내십시오. 키를 코드에 직접 붙여넣지 마십시오. 그런 다음 다음을 전송합니다:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-haiku-5-5",
    "max_tokens": 4096,
    "output_config": {"effort": "medium"},
    "thinking": {"type": "adaptive", "display": "summarized"},
    "messages": [{"role": "user", "content": "Classify this ticket as billing, bug, or feature request: The export button times out on large projects."}]
  }'

Python SDK는 환경에서 `ANTHROPIC_API_KEY`를 가져옵니다:

import anthropic

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-haiku-5-5",
    max_tokens=4096,
    output_config={"effort": "medium"},
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[{"role": "user", "content": "Classify this ticket as billing, bug, or feature request: The export button times out on large projects."}],
)

for block in response.content:
    if block.type == "thinking":
        print("[thinking]", block.thinking)
    elif block.type == "text":
        print(block.text)
print(response.stop_reason, response.usage)

TypeScript도 동일한 형식을 따릅니다:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();
const response = await client.messages.create({
  model: "claude-haiku-5-5",
  max_tokens: 4096,
  output_config: { effort: "medium" },
  thinking: { type: "adaptive", display: "summarized" },
  messages: [
    { role: "user", content: "Classify this ticket as billing, bug, or feature request: The export button times out on large projects." },
  ],
});

for (const block of response.content) {
  if (block.type === "text") console.log(block.text);
}
console.log(response.stop_reason, response.usage);

이 코드를 작동 상태로 유지하는 세 가지 습관이 있습니다. 응답이 `thinking` 블록으로 시작될 수 있고 `content[0].text`가 중단될 수 있으므로, `type`으로 콘텐츠 블록을 선택하십시오. 사고(thinking) 토큰이 `max_tokens`에 포함되므로 충분한 여유 공간을 남겨두십시오. 그리고 요청 본문을 깨끗하게 유지하십시오: `temperature`, `top_p`, `top_k`, `budget_tokens` 또는 어시스턴트 사전 채우기를 사용하지 마십시오. 이들 각각은 이 모델에서 400 오류를 반환합니다. 이전 코드를 마이그레이션하는 경우, Haiku 5.5 대 Haiku 4.5 가이드는 모든 주요 변경 사항을 Before/After JSON과 함께 나열합니다.

노력 수준 선택

`output_config.effort`에 설정되는 노력(effort)은 품질, 지연 시간 및 비용의 주요 조절 장치입니다. 프롬프팅 가이드는 다음과 같은 시작점을 제시합니다:

`low`: 채팅, 짧은 도구 작업 및 간단하고 대량의 요청을 위한 가장 저렴하고 빠른 수준.
`medium`: 기본값입니다. 에이전트 코딩을 포함한 대부분의 작업은 여기서 시작하십시오.
`high`: 지식 작업, 더 긴 에이전트 작업 및 엄격한 지시 따르기.
`xhigh` 및 `max`: 평가에서 개선 사항이 있을 때만 사용하십시오. Anthropic은 Claude Sonnet 5.5에서 동일한 평가를 실행하고 비교할 것을 제안합니다.

비용 곡선은 가파릅니다. 다음은 Anthropic 자체의 OSWorld 2.1(오프라인 서브셋) 출시 차트 실행 결과로, 부분 점수 및 시도당 비용을 보여줍니다:

노력	점수	시도당 비용
`low`	42.0%	$0.0695
`medium`	53.3%	$0.1257
`high`	61.3%	$0.1827
`xhigh`	67.6%	$0.2792
`max`	72.4%	$0.6111

`xhigh`에서 `max`로 가면 5점 미만의 점수 상승을 위해 비용이 두 배 이상 증가합니다. Haiku 5.5 벤치마크 분석에는 다른 노력 수준별 차트가 있습니다.

한 가지 특이점: 멀티턴 채팅에서 `xhigh`를 사용하면 모델이 가끔 전체 답변을 사고(thinking)에 작성하고 가시적인 텍스트 없이 턴을 마칠 때가 있습니다. 사용자에게 보여주기 전에 빈 응답이 있는지 확인하십시오.

사고(thinking) 제어하기

적응형 사고(adaptive thinking)는 기본적으로 켜져 있으며, Haiku 4.5에서 두 가지가 변경되었습니다. 첫째, 기본 디스플레이는 텍스트를 숨깁니다. 각 `thinking` 블록은 비어있는 `thinking` 필드와 `signature`만 반환합니다. 로그나 UI에서 읽기 쉬운 요약을 원할 경우 `"display": "summarized"`(첫 호출에서와 같이)로 설정하십시오. 사고(thinking)를 줄이려면 노력을 낮추십시오. 모델이 직접 답변하도록 프롬프팅해도 Anthropic의 테스트에서는 멈추지 않았습니다.

{
  "model": "claude-haiku-5-5",
  "max_tokens": 1024,
  "thinking": {"type": "disabled"},
  "output_config": {"effort": "low"},
  "messages": [{"role": "user", "content": "Extract the invoice number from: INV-2291, due Nov 3."}]
}

`xhigh` 또는 `max`에서 동일한 본문을 사용하면 400을 반환합니다. 강제적인 `tool_choice`(`any` 또는 명명된 도구)는 허용되지만, 응답은 도구 호출로 시작하며 사고(thinking) 블록을 포함하지 않습니다.

멀티턴 및 에이전트 루프의 경우, 모든 사고(thinking) 블록을 변경하지 않고 다시 전달하고 기록은 추가 전용으로 유지하십시오. 반환된 사고(thinking) 블록 이전에 `system`, `tools` 또는 이전 `messages`를 변경하면 400 오류가 발생할 수 있으며, 사고(thinking) 블록은 이를 생성한 계정(또는 연결된 계정)에서만 작동합니다.

프롬프트 캐싱 및 배치 작업

캐싱은 Haiku 5.5가 저렴해지는 부분입니다. 최대 10만 토큰 프롬프트의 경우, 캐시 읽기는 백만 토큰당 $0.01이며, 새로운 입력에는 $0.10, 5분 캐시 쓰기는 $0.125, 1시간 쓰기는 $0.20입니다. 최소 캐시 가능한 프롬프트는 Haiku 4.5의 4,096 토큰에서 512 토큰으로 줄어들어 짧은 시스템 프롬프트 및 도구 목록도 이제 캐시 가능합니다. 안정적인 접두사를 `cache_control`로 표시하십시오:

{
  "model": "claude-haiku-5-5",
  "max_tokens": 1024,
  "system": [{
    "type": "text",
    "text": "You are a support triage assistant. <long, stable policy text here>",
    "cache_control": {"type": "ephemeral"}
  }],
  "messages": [{"role": "user", "content": "Ticket: refund not received after 10 days."}]
}

요청 간에 최상위 `effort`를 변경하면 캐시가 무효화됩니다. 메시지별 노력(베타 헤더 `mid-conversation-output-config-2026-07-01`, Claude API 및 Google Cloud)은 캐시를 유지합니다. 프롬프트 캐싱 문서는 TTL(Time To Live)을 다루며, 저희 프롬프트 캐싱 설명서는 개념을 다룹니다.

기다릴 수 있는 작업의 경우, Message Batches API는 입력 및 출력을 50% 절감합니다: 최대 10만 토큰 프롬프트의 경우 $0.05/$0.25, 그 이상은 $0.25/$1.25입니다. 배치는 또한 `output-300k-2026-03-24` 베타 헤더를 사용하여 30만 출력 토큰에 도달할 수 있는 유일한 경로입니다.

10만 토큰 선을 주시하십시오: Anthropic의 말에 따르면, "10만 토큰을 초과하는 프롬프트는 더 높은 가격을 지불합니다." Haiku 5.5 가격 가이드는 양쪽의 예시를 자세히 설명합니다.

stop_reason "거부(refusal)" 처리하기

Haiku 5.5는 요청을 거부할 수 있는 안전 분류기를 실행하며, 서버 측 대체(fallback)가 없습니다. 거부된 요청은 `stop_reason: "refusal"`과 함께 돌아오며, 범주는 `cyber`, `frontier_llm`, `bio`, `general_harms`입니다. Haiku 4.5에서 마이그레이션하는 경우, 이러한 거부는 새로운 것입니다. 동일한 요청을 다시 보내면 일반적으로 또 다른 거부가 반환되므로, 맹목적으로 재시도하지 마십시오:

def run(client, messages):
    response = client.messages.create(
        model="claude-haiku-5-5",
        max_tokens=4096,
        messages=messages,
    )
    if response.stop_reason == "refusal":
        details = getattr(response, "stop_details", None)
        category = getattr(details, "category", "unknown")
        log_refusal(category, messages)  # 자신의 로깅
        return {"status": "refused", "category": category}
    text = "".join(b.text for b in response.content if b.type == "text")
    return {"status": "ok", "text": text}

`content`를 읽기 전에 `stop_reason`에 따라 분기하고, 거부된 요청을 자신의 코드에서 사람이나 다른 모델로 라우팅하십시오. `cyber` 또는 `bio` 분류기에 의해 차단된 합법적인 보안 또는 생명 과학 작업을 수행하는 팀은 Anthropic의 사이버 검증 프로그램 또는 생명 과학 검증 프로그램에 신청할 수 있습니다.

컴퓨터 사용 및 브라우저 사용

Claude API 및 Google Cloud에서 Haiku 5.5는 베타 헤더가 필요 없는 `computer_toolset_20260801` 툴셋을 통해서만 컴퓨터 사용을 지원합니다. `computer_20250124`를 선언하면 400 오류가 반환됩니다. 브라우저 사용은 Haiku 4.5가 지원하지 않는 `browser_toolset_20260801`을 통해 이루어집니다. Python 및 TypeScript SDK는 출시 당일에 두 가지 모두에 대한 베타 클래스를 추가했습니다. 멤버 도구에 대해서는 컴퓨터 사용 도구 문서를 참조하십시오.

속도 제한

Haiku 5.5는 Haiku 4.5와 동일한 속도 제한을 가집니다: Start 티어에서는 분당 1,000 요청, 200만 입력 토큰 및 40만 출력 토큰이며, Scale 티어에서는 최대 10,000 요청, 1천만 입력 및 200만 출력 토큰입니다. Priority Tier는 지원되지 않습니다. 429 오류 처리에 대해서는 속도 제한 초과 가이드를 참조하십시오.

Apidog에서 Claude Haiku 5.5 API 테스트하기

저장된 요청은 노력 비교 및 거부 디버깅을 반복 가능하게 만듭니다. Apidog에서의 설정은 다음과 같습니다:

환경을 생성하고 `ANTHROPIC_API_KEY`를 비밀 변수로 추가하십시오. `x-api-key` 헤더에서 `anthropic-version: 2023-06-01` 및 `content-type: application/json` 옆에 `{{ANTHROPIC_API_KEY}}`로 참조하십시오.
`https://api.anthropic.com/v1/messages`로 POST 요청을 생성하고, 첫 호출 본문을 붙여넣은 다음 저장하십시오.
어설션(assertions)을 추가하십시오: 상태는 200, `$.stop_reason`은 `end_turn`, `$.usage.output_tokens`는 0보다 크고, `$.content[*].type`은 `text`를 포함합니다. 이제 거부 또는 빈 `xhigh` 응답은 테스트를 통과하는 대신 실패하게 됩니다.
요청을 `low`, `high`, `xhigh`, `max`로 네 번 복제하고 폴더를 실행하십시오. 자신의 프롬프트에 대한 각 노력 수준별 `usage`를 얻을 수 있습니다.
캐시된 시스템 프롬프트 변형을 추가하고 두 번째 실행에서 `$.usage.cache_read_input_tokens`가 0보다 큰지 확인하십시오.

더 넓은 패턴에 대해서는 LLM 애플리케이션 테스트하기를 참조하십시오.

자주 묻는 질문

Claude Haiku 5.5 모델 ID는 무엇인가요? `claude-haiku-5-5`이며, Claude API, Google Cloud, Microsoft Foundry 및 AWS의 Claude Platform에서는 날짜 접미사 및 별도 별칭이 없습니다. Amazon Bedrock에서는 `anthropic.claude-haiku-5-5`입니다.

무료 Claude Haiku 5.5 API가 있나요? 지속적인 무료 티어는 없지만, 새로운 API 사용자는 API를 테스트할 수 있는 소량의 무료 크레딧을 받습니다. 무료 Claude.ai 사용자는 채팅에서 Haiku 5.5를 선택할 수 있지만, 이는 API 키가 아닙니다. Max 및 Team 요금제에는 이제 월별 API 크레딧이 포함됩니다. 무료 액세스 가이드에서 무엇이 포함되고 무엇이 포함되지 않는지 다룹니다.

제 Haiku 4.5 요청이 400을 반환하는 이유는 무엇인가요? `budget_tokens`, 기본값이 아닌 `temperature` 또는 `top_p`, 모든 `top_k`, 어시스턴트 사전 채우기 또는 이전 `computer_20250124` 도구가 있는지 확인하십시오. 이것들이 일반적인 원인입니다.

Claude Code에서 Haiku 5.5를 사용할 수 있나요? 네, v2.1.293부터 가능합니다. Anthropic API에서 `haiku` 별칭은 Haiku 5.5로 연결됩니다. Claude Code의 Claude Haiku 5.5를 참조하십시오.

에이전트 코딩에 Haiku 5.5 또는 Sonnet 5.5를 사용해야 하나요? Anthropic은 Sonnet 5.5와 Opus 5.5가 “복잡한 에이전트 코딩 작업에 더 나은 선택으로 남아 있다”고 말합니다. Haiku 5.5는 분류, 요약, 압축, 서브에이전트 및 브라우저 사용과 같이 범위가 좁은 작업에 사용하십시오.

다음 단계

자신의 작업 부하에서 프롬프트를 사용하여 `medium`으로 첫 호출 요청을 보낸 다음, `low` 및 `high`로 다시 실행하고 `usage.output_tokens` 및 답변 품질을 비교하십시오. 어설션과 함께 세 가지 실행 결과를 모두 보관하려면 Apidog를 다운로드하십시오. 이렇게 하면 다음 모델 릴리스가 단일 필드 변경으로 처리될 수 있습니다.

버튼