DEV Community

Cover image for Hướng dẫn sử dụng API Claude Haiku 5.5
Sebastian Petrus
Sebastian Petrus

Posted on Originally published at apidog.com

Hướng dẫn sử dụng API Claude Haiku 5.5

#ai #claude #api #llm

Để gọi API Claude Haiku 5.5, gửi yêu cầu POST đến https://api.anthropic.com/v1/messages với model claude-haiku-5-5, khóa API trong header x-api-key và anthropic-version: 2023-06-01. Với lời nhắc tối đa 100K token, giá là 0,10 USD/MTok đầu vào và 0,50 USD/MTok đầu ra; nếu vượt 100K token, giá tăng lên 0,50 USD/2,50 USD. Model hỗ trợ tối đa 1M token ngữ cảnh, 128K token đầu ra và mặc định dùng mức nỗ lực medium với tư duy thích ứng.

Dùng thử Apidog ngay hôm nay

Anthropic phát hành Haiku 5.5 vào ngày 7 tháng 10 năm 2026. Đây là Haiku đầu tiên hỗ trợ các mức độ nỗ lực. Xem Claude Haiku 5.5 là gì để biết thông số kỹ thuật và định vị sản phẩm.

Bài viết này hướng dẫn:

  • Gọi API bằng curl, Python và TypeScript
  • Điều chỉnh output_config.effort
  • Xử lý tư duy, cache prompt, batch và từ chối
  • Dùng computer/browser toolset
  • Kiểm thử request trong Apidog

Tổng quan về API Claude Haiku 5.5

Tham số Hành vi của Haiku 5.5
ID mô hình claude-haiku-5-5; Bedrock: anthropic.claude-haiku-5-5; không có bí danh riêng
Giá mỗi MTok, prompt đến 100K token 0,10 USD đầu vào, 0,50 USD đầu ra, 0,01 USD đọc cache
Giá mỗi MTok, prompt trên 100K token 0,50 USD đầu vào, 2,50 USD đầu ra, 0,05 USD đọc cache
Ngữ cảnh / đầu ra tối đa 1M / 128K; 300K trên Batch với beta header output-300k-2026-03-24
output_config.effort low, medium (mặc định), high, xhigh, max
thinking adaptive mặc định; disabled chỉ dùng được ở high trở xuống
thinking.display Mặc định không hiển thị văn bản tư duy; summarized trả về bản tóm tắt dễ đọc
temperature, top_p, top_k Giá trị không mặc định trả về HTTP 400
Tự động điền của trợ lý Trả về HTTP 400, kể cả khi tắt tư duy
Prompt tối thiểu có thể cache 512 token, giảm từ 4.096 token ở Haiku 4.5

Nguồn: trang model Haiku 5.5 và tài liệu giá API Claude.

Gọi API Claude Haiku 5.5 lần đầu

Tạo khóa trong Claude Console, rồi lưu vào biến môi trường ANTHROPIC_API_KEY. Xem hướng dẫn khóa API Anthropic nếu cần.

Không hard-code hoặc commit API key vào source code.

Gọi bằng curl 

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

Gọi bằng Python

SDK Python tự đọc ANTHROPIC_API_KEY từ môi trường:

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

Gọi bằng 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

Checklist tránh lỗi 400

  1. Đọc content theo type. Phản hồi có thể bắt đầu bằng block thinking, vì vậy không truy cập trực tiếp content[0].text.
  2. Chừa token cho tư duy. Token tư duy được tính trong max_tokens.
  3. Không gửi các trường không hỗ trợ:
    • temperature không mặc định
    • top_p không mặc định
    • Bất kỳ top_k nào
    • budget_tokens
    • Assistant prefill

Nếu đang nâng cấp từ model cũ, xem so sánh Haiku 5.5 và Haiku 4.5 để kiểm tra các thay đổi JSON có thể gây lỗi.

Chọn mức độ nỗ lực

Thiết lập mức độ nỗ lực qua output_config.effort. Đây là biến số chính ảnh hưởng đến chất lượng, độ trễ và chi phí.

Theo hướng dẫn tạo prompt:

  • low: rẻ và nhanh nhất; phù hợp chatbot, tool call ngắn, tác vụ đơn giản số lượng lớn.
  • medium: mặc định; nên bắt đầu tại đây cho hầu hết workload, bao gồm agent coding.
  • high: phù hợp công việc tri thức, agent dài hơn, hoặc yêu cầu tuân thủ hướng dẫn nghiêm ngặt.
  • xhigh và max: chỉ dùng khi benchmark nội bộ chứng minh được lợi ích.

Dữ liệu OSWorld 2.1 (tập con ngoại tuyến) của Anthropic:

Nỗ lực Điểm Chi phí mỗi lần thử
low 42.0% 0,0695 USD
medium 53.3% 0,1257 USD
high 61.3% 0,1827 USD
xhigh 67.6% 0,2792 USD
max 72.4% 0,6111 USD

Chuyển từ xhigh sang max làm chi phí tăng hơn gấp đôi nhưng tăng dưới năm điểm. Xem thêm phân tích benchmark Haiku 5.5.

Ở xhigh trong hội thoại nhiều lượt, model đôi khi đặt toàn bộ câu trả lời trong phần tư duy và kết thúc mà không có text block. Luôn kiểm tra phản hồi rỗng trước khi hiển thị cho người dùng.

Kiểm soát tư duy

Tư duy thích ứng được bật mặc định. Có hai điểm cần lưu ý.

Hiển thị bản tóm tắt tư duy

Mặc định, block thinking không trả về nội dung dễ đọc; trường thinking rỗng và chỉ có signature.

Nếu cần log hoặc hiển thị bản tóm tắt, dùng:

{
  "thinking": {
    "type": "adaptive",
    "display": "summarized"
  }
}
Enter fullscreen mode Exit fullscreen mode

Muốn model suy nghĩ ít hơn, hãy giảm effort. Chỉ yêu cầu model “trả lời trực tiếp” không đảm bảo giảm tư duy.

Tắt tư duy

Bạn chỉ có thể tắt tư duy ở mức high hoặc thấp hơn:

{
  "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

Cùng request trên với xhigh hoặc max sẽ trả về HTTP 400.

Với agent hoặc workflow nhiều lượt:

  • Gửi lại nguyên vẹn mọi block thinking được trả về.
  • Chỉ thêm mới lịch sử hội thoại, không sửa lịch sử trước đó.
  • Không thay đổi system, tools hoặc message nằm trước block tư duy.

Vi phạm các điều kiện này có thể dẫn đến HTTP 400. Block tư duy cũng chỉ hoạt động trong tài khoản đã tạo chúng hoặc tài khoản được liên kết.

Cache prompt và xử lý theo lô

Prompt caching giúp Haiku 5.5 giảm đáng kể chi phí khi có prefix ổn định.

Với prompt đến 100K token:

  • Đọc cache: 0,01 USD/MTok
  • Đầu vào mới: 0,10 USD/MTok
  • Ghi cache TTL 5 phút: 0,125 USD/MTok
  • Ghi cache TTL 1 giờ: 0,20 USD/MTok

Prompt chỉ cần từ 512 token để đủ điều kiện cache, thay vì 4.096 token như Haiku 4.5.

Đánh dấu phần prompt ổn định bằng 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

Lưu ý: thay đổi effort ở cấp request làm cache mất hiệu lực. Effort theo từng message, dùng beta header mid-conversation-output-config-2026-07-01 trên Claude API và Google Cloud, vẫn giữ được cache.

Tham khảo tài liệu prompt caching và bài giải thích về prompt caching.

Dùng Message Batches API

Nếu workload có thể chờ, Message Batches API giảm 50% chi phí đầu vào và đầu ra:

Prompt Giá đầu vào / đầu ra
Đến 100K token 0,05 USD / 0,25 USD mỗi MTok
Trên 100K token 0,25 USD / 1,25 USD mỗi MTok

Batch cũng là cách duy nhất để nhận tối đa 300K token đầu ra, với beta header:

anthropic-beta: output-300k-2026-03-24
Enter fullscreen mode Exit fullscreen mode

Vượt 100K token sẽ áp dụng mức giá cao hơn. Xem hướng dẫn giá Haiku 5.5 để xem ví dụ chi phí.

Xử lý stop_reason: "refusal"

Haiku 5.5 có thể từ chối request do bộ phân loại an toàn. Khi đó:

{
  "stop_reason": "refusal"
}
Enter fullscreen mode Exit fullscreen mode

Các danh mục có thể gồm cyber, frontier_llm, bio và general_harms.

Không retry mù quáng: gửi lại cùng request thường tiếp tục tạo ra phản hồi từ chối.

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

Luôn kiểm tra stop_reason trước khi đọc content. Sau đó, route request bị từ chối sang reviewer, workflow khác hoặc model khác tùy kiến trúc ứng dụng.

Các nhóm làm việc hợp pháp trong an ninh mạng hoặc khoa học đời sống nhưng bị chặn bởi classifier cyber hoặc bio có thể đăng ký Chương trình Xác minh An ninh mạng hoặc Chương trình Xác minh Khoa học Đời sống của Anthropic.

Sử dụng máy tính và trình duyệt

Trên Claude API và Google Cloud, Haiku 5.5 hỗ trợ computer use qua toolset:

computer_toolset_20260801
Enter fullscreen mode Exit fullscreen mode

Không cần beta header. Khai báo tool cũ computer_20250124 sẽ trả về HTTP 400.

Haiku 5.5 cũng hỗ trợ browser use qua:

browser_toolset_20260801
Enter fullscreen mode Exit fullscreen mode

Haiku 4.5 không hỗ trợ browser toolset này. SDK Python và TypeScript đã bổ sung beta classes cho cả hai toolset vào ngày ra mắt.

Xem tài liệu computer use tool để biết các công cụ thành viên.

Giới hạn tỷ lệ

Haiku 5.5 có rate limit tương tự Haiku 4.5:

Gói Request/phút Token đầu vào/phút Token đầu ra/phút
Start 1.000 2M 400K
Scale 10.000 10M 2M

Priority Tier không được hỗ trợ.

Khi gặp HTTP 429, áp dụng retry có exponential backoff và giới hạn concurrency. Xem hướng dẫn xử lý vượt quá rate limit.

Kiểm tra API Claude Haiku 5.5 trong Apidog

Lưu request giúp bạn benchmark các mức effort, kiểm tra cache và tái tạo lỗi từ chối. Thiết lập trong Apidog:

Thiết lập request Claude Haiku 5.5 trong Apidog

  1. Tạo environment và thêm ANTHROPIC_API_KEY dưới dạng biến bí mật.
  2. Trong header x-api-key, dùng biến {{ANTHROPIC_API_KEY}}.
  3. Thêm các header: 
   anthropic-version: 2023-06-01
   content-type: application/json
Enter fullscreen mode Exit fullscreen mode
  1. Tạo request POST đến: 
   https://api.anthropic.com/v1/messages
Enter fullscreen mode Exit fullscreen mode
  1. Dán body của request đầu tiên và lưu request.
  2. Thêm assertions:
    • Status code là 200
    • $.stop_reason là end_turn
    • $.usage.output_tokens lớn hơn 0
    • $.content[*].type chứa text
  3. Nhân bản request cho low, high, xhigh và max, sau đó chạy collection để so sánh usage.
  4. Tạo biến thể dùng system prompt cache và xác nhận: 
   $.usage.cache_read_input_tokens > 0
Enter fullscreen mode Exit fullscreen mode

ở lần chạy thứ hai.

Xem thêm hướng dẫn kiểm thử ứng dụng LLM.

Câu hỏi thường gặp

ID model Claude Haiku 5.5 là gì?

Trên Claude API, Google Cloud, Microsoft Foundry và Claude Platform on AWS, ID là:

claude-haiku-5-5
Enter fullscreen mode Exit fullscreen mode

Trên Amazon Bedrock:

anthropic.claude-haiku-5-5
Enter fullscreen mode Exit fullscreen mode

Có API Claude Haiku 5.5 miễn phí không?

Không có free tier liên tục. Người dùng API mới nhận được một khoản tín dụng miễn phí nhỏ để thử nghiệm. Người dùng Claude.ai miễn phí có thể chọn Haiku 5.5 trong chat, nhưng đó không phải API key.

Các gói Max và Team hiện bao gồm tín dụng API hàng tháng. Xem hướng dẫn truy cập miễn phí.

Tại sao request Haiku 4.5 của tôi trả về 400?

Kiểm tra các trường sau:

  • budget_tokens
  • temperature hoặc top_p không mặc định
  • Bất kỳ top_k nào
  • Assistant prefill
  • Tool computer_20250124 cũ

Đây là các nguyên nhân phổ biến nhất.

Tôi có thể dùng Haiku 5.5 trong Claude Code không?

Có, từ Claude Code v2.1.293. Trên Anthropic API, alias haiku phân giải tới Haiku 5.5.

Xem Claude Haiku 5.5 trong Claude Code.

Nên dùng Haiku 5.5 hay Sonnet 5.5 cho agent coding?

Anthropic cho biết Sonnet 5.5 và Opus 5.5 vẫn phù hợp hơn cho tác vụ agent coding phức tạp.

Dùng Haiku 5.5 cho workload phạm vi hẹp như:

  • Phân loại
  • Tóm tắt
  • Nén dữ liệu
  • Sub-agent
  • Browser use

Bước tiếp theo

Bắt đầu với medium, sau đó chạy lại cùng prompt thực tế của bạn ở low và high. So sánh:

  • Chất lượng câu trả lời
  • usage.output_tokens
  • Độ trễ
  • Chi phí

Tải xuống Apidog để lưu các request, thêm assertions và biến việc nâng cấp model tiếp theo thành thay đổi cấu hình thay vì viết lại toàn bộ workflow.

Top comments (0)