DEV Community

Cover image for 클로드 하이쿠 5.5 API 사용 방법
Rihpig
Rihpig

Posted on Originally published at apidog.com

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

Claude Haiku 5.5 API를 호출하려면 https://api.anthropic.com/v1/messages에 POST 요청을 보내고, 요청 본문에 "model": "claude-haiku-5-5"를 포함하십시오. x-api-key 헤더에 API 키를 설정하고 anthropic-version: 2023-06-01을 명시해야 합니다. 최대 10만 토큰 프롬프트의 가격은 입력/출력 토큰 100만 개당 각각 $0.10/$0.50이며, 10만 토큰을 초과하면 $0.50/$2.50입니다. 이 모델은 최대 100만 토큰 컨텍스트를 읽고 기본적으로 최대 12만 8천 토큰을 생성하며, 적응형 사고(adaptive thinking)와 medium 노력 수준을 기본값으로 사용합니다.

지금 Apidog 사용해 보기

Anthropic은 2026년 10월 7일 노력 수준(effort levels)을 지원하는 최초의 Haiku 모델인 Haiku 5.5를 출시했습니다. 모델 사양과 포지셔닝은 Claude Haiku 5.5란 무엇인가에서 확인할 수 있습니다. 이 글에서는 curl, Python, TypeScript로 첫 요청을 보내는 방법부터 노력 수준, 사고, 캐싱, 배치, 거부 처리, 에이전트 툴셋까지 구현 관점에서 다룹니다. 아래 요청은 모두 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 베타 헤더를 사용하는 배치에서는 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 콘솔에서 API 키를 생성하고, 환경 변수로 내보내십시오. 키를 소스 코드에 직접 작성하지 마십시오. 키 생성 단계는 Anthropic API 키 가이드를 참고할 수 있습니다.

export ANTHROPIC_API_KEY="your-api-key"
Enter fullscreen mode Exit fullscreen mode

curl

다음 요청은 티켓을 billing, bug, feature request 중 하나로 분류합니다.

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."
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

Python

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)
Enter fullscreen mode Exit fullscreen mode

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);
Enter fullscreen mode Exit fullscreen mode

구현 시 다음 세 가지를 확인하십시오.

  1. 응답은 thinking 블록으로 시작할 수 있습니다. content[0].text에 의존하지 말고 각 블록의 type으로 분기하십시오.
  2. 사고(thinking) 토큰도 max_tokens에 포함됩니다. 출력 토큰 예산에 충분한 여유를 두십시오.
  3. 요청 본문에서 temperature, top_p, top_k, budget_tokens, 어시스턴트 사전 채우기를 제거하십시오. Haiku 5.5에서는 이 항목들이 400 오류를 유발합니다.

기존 요청을 마이그레이션한다면 Haiku 5.5 대 Haiku 4.5 가이드에서 Before/After JSON을 확인하십시오.

노력 수준 선택

output_config.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"를 설정하십시오.

사고 사용량을 줄이는 가장 직접적인 방법은 노력 수준을 낮추는 것입니다. 모델에 “직접 답변하라”고 프롬프팅해도 Anthropic 테스트에서는 사고가 멈추지 않았습니다.

사고를 비활성화하려면 low, medium, high 노력 수준에서 다음과 같이 설정합니다.

{
  "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."
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

같은 요청을 xhigh 또는 max와 함께 보내면 400 오류가 반환됩니다.

강제 tool_choice(any 또는 특정 도구 이름)는 허용됩니다. 단, 응답은 도구 호출로 시작하고 사고(thinking) 블록을 포함하지 않습니다.

멀티턴 대화와 에이전트 루프에서는 다음 원칙을 지키십시오.

  • 반환된 모든 thinking 블록을 수정하지 않고 다음 요청에 다시 전달합니다.
  • 대화 기록은 추가 전용으로 유지합니다.
  • 사고 블록보다 앞선 system, tools, 이전 messages를 변경하지 않습니다.

이 규칙을 위반하면 400 오류가 발생할 수 있습니다. 또한 사고 블록은 해당 블록을 생성한 계정 또는 연결된 계정에서만 사용할 수 있습니다.

프롬프트 캐싱 및 배치 작업

Haiku 5.5에서는 프롬프트 캐싱이 비용 최적화에 특히 중요합니다. 최대 10만 토큰 프롬프트 기준 가격은 다음과 같습니다.

항목 MTok당 가격
신규 입력 $0.10
캐시 읽기 $0.01
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."
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

요청 간 최상위 effort 값을 변경하면 캐시가 무효화됩니다. Claude API 및 Google Cloud에서는 베타 헤더 mid-conversation-output-config-2026-07-01을 사용한 메시지별 노력 설정이 캐시를 유지합니다.

TTL(Time To Live)은 프롬프트 캐싱 문서를 참고하십시오. 캐싱 개념과 적용 사례는 프롬프트 캐싱 설명서에서 다룹니다.

응답을 즉시 받을 필요가 없다면 Message Batches API를 사용하십시오. 입력과 출력 비용이 50% 절감됩니다.

프롬프트 길이 입력 MTok당 출력 MTok당
최대 10만 토큰 $0.05 $0.25
10만 토큰 초과 $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"
}
Enter fullscreen mode Exit fullscreen mode

거부 범주는 cyber, frontier_llm, bio, general_harms입니다. Haiku 4.5에서 마이그레이션했다면 이 거부 처리는 새로 고려해야 할 동작입니다.

같은 요청을 무조건 재시도하면 다시 거부될 가능성이 높으므로, stop_reason을 먼저 확인하고 적절히 라우팅하십시오.

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(
        block.text
        for block in response.content
        if block.type == "text"
    )
    return {"status": "ok", "text": text}
Enter fullscreen mode Exit fullscreen mode

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,000만 분당 200만

Priority Tier는 지원되지 않습니다.

429 응답을 받으면 재시도 정책, 지수 백오프, 요청 큐를 구현하십시오. 구현 패턴은 속도 제한 초과 가이드를 참고하십시오.

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

저장된 요청을 사용하면 노력 수준별 결과를 반복 비교하고 거부 응답을 재현하기 쉬워집니다. Apidog에서 다음 순서로 구성하십시오.

Apidog에서 Claude Haiku 5.5 API 요청 구성 화면

  1. 환경을 생성하고 ANTHROPIC_API_KEY를 비밀 변수로 추가합니다. x-api-key 헤더 값에는 {{ANTHROPIC_API_KEY}}를 사용하고, anthropic-version: 2023-06-01, content-type: application/json도 추가합니다.
  2. https://api.anthropic.com/v1/messages에 POST 요청을 생성합니다.
  3. 첫 번째 호출 예제의 요청 본문을 붙여넣고 저장합니다.
  4. 다음 어설션을 추가합니다.
    • 상태 코드: 200
    • $.stop_reason: end_turn
    • $.usage.output_tokens: 0보다 큼
    • $.content[*].type: text 포함
  5. 요청을 low, high, xhigh, max 설정으로 복제한 뒤 폴더 실행을 수행합니다.
  6. 캐시된 시스템 프롬프트 변형을 만들고, 두 번째 실행에서 $.usage.cache_read_input_tokens가 0보다 큰지 확인합니다.

이 설정을 사용하면 거부 응답이나 비어 있는 xhigh 응답이 정상 테스트로 통과하는 대신 명확하게 실패합니다. 더 넓은 테스트 패턴은 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 도구

이 항목들이 Haiku 5.5에서 400 오류를 만드는 일반적인 원인입니다.

Claude Code에서 Haiku 5.5를 사용할 수 있나요?

네. Claude Code 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를 다운로드하여 요청 컬렉션과 테스트를 관리하십시오.

Top comments (0)