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

Để sử dụng API Claude Haiku 5.5, hãy gửi yêu cầu POST đến https://api.anthropic.com/v1/messages với "model": "claude-haiku-5-5", khóa API của bạn trong tiêu đề x-api-key và anthropic-version: 2023-06-01. Chi phí là 0,10 USD/0,50 USD cho mỗi triệu token đầu vào/đầu ra đối với các lời nhắc lên đến 100K token (0,50 USD/2,50 USD nếu vượt quá mức đó), đọc lên đến 1M token ngữ cảnh, ghi lên đến 128K, và mặc định là nỗ lực medium với tính năng tư duy thích ứng được bật.

Anthropic đã phát hành Haiku 5.5 vào ngày 7 tháng 10 năm 2026, và đây là Haiku đầu tiên có các mức độ nỗ lực (Claude Haiku 5.5 là gì bao gồm thông số kỹ thuật và định vị sản phẩm). Hướng dẫn này bao gồm một cuộc gọi đầu tiên trong curl, Python và TypeScript, sau đó là nỗ lực, tư duy, lưu vào bộ nhớ cache, xử lý theo lô, từ chối và bộ công cụ tác nhân. Bạn có thể lưu và xác nhận mọi yêu cầu bên dưới trong Apidog.

Tổng quan về API Claude Haiku 5.5

Nguồn: trang mô hình Haiku 5.5 và tài liệu giá API Claude.

Cuộc gọi API Claude Haiku 5.5 đầu tiên của bạn

Tạo khóa trong Claude Console (hướng dẫn khóa API Anthropic sẽ hướng dẫn bạn thực hiện) và xuất nó dưới dạng ANTHROPIC_API_KEY. Không bao giờ dán khóa vào mã. Sau đó gửi yêu cầu này:

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."}]
  }'

SDK Python sẽ lấy 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)

TypeScript có cấu trúc tương tự:

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);

Ba thói quen giúp mã này hoạt động. Chọn các khối nội dung theo type, vì một phản hồi có thể bắt đầu bằng khối thinking và content[0].text sẽ bị lỗi. Để lại không gian trong max_tokens, vì các token tư duy được tính vào đó. Và giữ cho phần thân yêu cầu gọn gàng: không có temperature, top_p, top_k, budget_tokens hoặc tự động điền của trợ lý. Mỗi lỗi này sẽ trả về 400 trên mô hình này. Nếu bạn đang di chuyển mã cũ, hướng dẫn Haiku 5.5 so với Haiku 4.5 liệt kê mọi thay đổi gây lỗi với JSON trước/sau.

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

Mức độ nỗ lực, được đặt trong output_config.effort, là yếu tố chính quyết định chất lượng, độ trễ và chi phí. Hướng dẫn tạo lời nhắc đưa ra các điểm khởi đầu sau:

• low: mức độ rẻ nhất và nhanh nhất, dành cho trò chuyện, các tác vụ công cụ ngắn và các yêu cầu đơn giản, khối lượng lớn.
• medium: mặc định. Bắt đầu ở đây cho hầu hết công việc, bao gồm cả lập trình tác nhân.
• high: công việc tri thức, các tác vụ tác nhân dài hơn và tuân thủ nghiêm ngặt các hướng dẫn.
• xhigh và max: chỉ khi các đánh giá của bạn cho thấy sự cải thiện. Anthropic đề xuất chạy các đánh giá tương tự trên Claude Sonnet 5.5 và so sánh.

Đường cong chi phí rất dốc. Dưới đây là các lần chạy OSWorld 2.1 (tập con ngoại tuyến) của Anthropic từ biểu đồ ra mắt, với điểm tín dụng một phần và chi phí cho mỗi lần thử:

Chuyển từ xhigh sang max làm tăng hơn gấp đôi chi phí cho dưới năm điểm. Phân tích điểm chuẩn Haiku 5.5 có các biểu đồ theo mức độ nỗ lực khác.

Một điểm đặc biệt: ở mức xhigh trong các cuộc trò chuyện nhiều lượt, mô hình đôi khi viết toàn bộ câu trả lời của nó trong phần tư duy và kết thúc lượt mà không có văn bản hiển thị. Hãy kiểm tra xem có phản hồi trố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 theo mặc định và có hai điều đã thay đổi so với Haiku 4.5. Thứ nhất, hiển thị mặc định ẩn văn bản. Mỗi khối thinking trả về với trường thinking trống và chỉ có signature. Đặt "display": "summarized" (như trong cuộc gọi đầu tiên) khi bạn muốn có các bản tóm tắt dễ đọc trong nhật ký hoặc giao diện người dùng. Để ít tư duy hơn, hãy giảm mức độ nỗ lực; việc nhắc mô hình trả lời trực tiếp không ngăn được nó trong quá trình thử nghiệm của Anthropic.

Thứ hai, bạn có thể tắt tư duy, nhưng chỉ ở mức nỗ lực high trở xuống:

{
  "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."}]
}

Cùng một phần thân yêu cầu ở mức xhigh hoặc max sẽ trả về 400. Một tool_choice bắt buộc (any hoặc một công cụ được đặt tên) được chấp nhận, nhưng phản hồi bắt đầu bằng lệnh gọi công cụ và không chứa khối tư duy.

Đối với các vòng lặp nhiều lượt và tác nhân, hãy chuyển mọi khối tư duy trở lại mà không thay đổi và giữ lịch sử chỉ bổ sung. Thay đổi system, tools hoặc các messages trước đó trước một khối tư duy được trả về có thể trả về 400, và các khối tư duy chỉ hoạt động trong tài khoản đã tạo ra chúng (hoặc tài khoản được liên kết với nó).

Bộ nhớ đệm lời nhắc và các tác vụ theo lô

Bộ nhớ đệm là nơi Haiku 5.5 trở nên rẻ. Đối với các lời nhắc lên đến 100K token, một lần đọc bộ nhớ đệm có giá 0,01 USD mỗi triệu token so với 0,10 USD cho đầu vào mới, một lần ghi bộ nhớ đệm 5 phút có giá 0,125 USD và một lần ghi 1 giờ có giá 0,20 USD. Lời nhắc có thể lưu vào bộ nhớ đệm tối thiểu là 512 token, giảm từ 4.096 trên Haiku 4.5, vì vậy các lời nhắc hệ thống ngắn và danh sách công cụ giờ đây đủ điều kiện. Đánh dấu tiền tố ổ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."}]
}

Thay đổi effort cấp cao nhất giữa các yêu cầu sẽ làm mất hiệu lực bộ nhớ đệm; nỗ lực trên mỗi tin nhắn (tiêu đề beta mid-conversation-output-config-2026-07-01, API Claude và Google Cloud) sẽ giữ nguyên. Tài liệu lưu lời nhắc vào bộ nhớ đệm bao gồm các TTL, và bài giải thích về lưu lời nhắc vào bộ nhớ đệm của chúng tôi bao gồm khái niệm này.

Đối với công việc có thể chờ đợi, API Xử lý tin nhắn theo lô (Message Batches API) cắt giảm 50% đầu vào và đầu ra: 0,05 USD/0,25 USD cho các lời nhắc lên đến 100K token và 0,25 USD/1,25 USD nếu vượt quá. Xử lý theo lô cũng là cách duy nhất để đạt được 300K token đầu ra, với tiêu đề beta output-300k-2026-03-24.

Hãy lưu ý giới hạn 100K: "một lời nhắc trên 100.000 token sẽ phải trả giá cao hơn", theo lời của Anthropic. Hướng dẫn giá Haiku 5.5 trình bày các ví dụ ở cả hai phía.

Xử lý stop_reason “refusal” (từ chối)

Haiku 5.5 chạy các bộ phân loại an toàn có thể từ chối một yêu cầu và nó không có cơ chế dự phòng phía máy chủ. Một yêu cầu bị từ chối sẽ trả về với stop_reason: "refusal", và các danh mục bao gồm cyber, frontier_llm, bio và general_harms. Nếu bạn đang chuyển từ Haiku 4.5, những từ chối này là mới. Gửi lại cùng một yêu cầu thường trả về một từ chối khác, vì vậy đừng thử lại một cách mù quáng:

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)  # your logging
        return {"status": "refused", "category": category}
    text = "".join(b.text for b in response.content if b.type == "text")
    return {"status": "ok", "text": text}

Phân nhánh theo stop_reason trước khi bạn đọc content, và chuyển các yêu cầu bị từ chối đến một người hoặc một mô hình khác trong mã của bạn. Các nhóm đang thực hiện công việc bảo mật hoặc khoa học đời sống hợp pháp bị chặn bởi các bộ phân loại 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 API Claude và Google Cloud, Haiku 5.5 chỉ hỗ trợ sử dụng máy tính thông qua bộ công cụ computer_toolset_20260801, không cần tiêu đề beta; khai báo computer_20250124 sẽ trả về 400. Việc sử dụng trình duyệt thông qua browser_toolset_20260801, mà Haiku 4.5 không hỗ trợ. Các SDK Python và TypeScript đã thêm các lớp beta cho cả hai vào ngày ra mắt. Xem tài liệu công cụ sử dụng máy tính để biết các công cụ thành viên.

Giới hạn tỷ lệ

Haiku 5.5 có giới hạn tỷ lệ tương tự như Haiku 4.5: 1.000 yêu cầu, 2M token đầu vào và 400K token đầu ra mỗi phút trên gói Start, lên đến 10.000 yêu cầu, 10M đầu vào và 2M đầu ra trên gói Scale. Gói Priority Tier không được hỗ trợ. Để xử lý lỗi 429, hãy xem hướng dẫn vượt quá giới hạn tỷ lệ.

Kiểm tra API Claude Haiku 5.5 trong Apidog

Các yêu cầu đã lưu giúp việc so sánh mức độ nỗ lực và gỡ lỗi từ chối có thể lặp lại. Dưới đây là thiết lập trong Apidog:

1. Tạo một môi trường và thêm ANTHROPIC_API_KEY làm biến bí mật. Tham chiếu nó dưới dạng {{ANTHROPIC_API_KEY}} trong tiêu đề x-api-key, bên cạnh anthropic-version: 2023-06-01 và content-type: application/json.
2. Tạo một yêu cầu POST tới https://api.anthropic.com/v1/messages, dán nội dung cuộc gọi đầu tiên và lưu lại.
3. Thêm các xác nhận: trạng thái là 200, $.stop_reason bằng end_turn, $.usage.output_tokens lớn hơn 0, và $.content[*].type chứa text. Một sự từ chối hoặc một phản hồi xhigh trống giờ đây sẽ khiến kiểm tra thất bại thay vì lọt qua.
4. Nhân đôi yêu cầu bốn lần với low, high, xhigh và max, sau đó chạy thư mục. Bạn sẽ nhận được usage cho mỗi mức độ nỗ lực trên lời nhắc của riêng bạn.
5. Thêm biến thể lời nhắc hệ thống được lưu vào bộ nhớ đệm và xác nhận rằng $.usage.cache_read_input_tokens lớn hơn 0 trong lần chạy thứ hai.

Để biết các mẫu rộng hơn, hãy xem kiểm tra các ứng dụng LLM.

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

ID mô hình Claude Haiku 5.5 là gì? claude-haiku-5-5, không có hậu tố ngày tháng và không có bí danh riêng biệt, trên API Claude, Google Cloud, Microsoft Foundry và Nền tảng Claude trên AWS. Trên Amazon Bedrock thì là anthropic.claude-haiku-5-5.

Có API Claude Haiku 5.5 miễn phí không? Không có gói miễn phí liên tục, nhưng 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 API. Người dùng Claude.ai miễn phí có thể chọn Haiku 5.5 trong cuộc trò chuyện, nhưng đó không phải là khóa API. Các gói Max và Team hiện bao gồm tín dụng API hàng tháng. Hướng dẫn truy cập miễn phí bao gồm những gì được tính và những gì không.

Tại sao yêu cầu Haiku 4.5 của tôi trả về 400? Kiểm tra budget_tokens, temperature hoặc top_p không mặc định, bất kỳ top_k nào, tính năng tự động điền của trợ lý hoặc công cụ computer_20250124 cũ. Đó là những nguyên nhân thường gặp.

Tôi có thể sử dụng Haiku 5.5 trong Claude Code không? Có, từ v2.1.293. Trên API Anthropic, bí danh haiku phân giải thành Haiku 5.5. Xem Claude Haiku 5.5 trong Claude Code.

Tôi nên sử dụng Haiku 5.5 hay Sonnet 5.5 cho lập trình tác nhân? Anthropic cho biết Sonnet 5.5 và Opus 5.5 "vẫn là lựa chọn tốt hơn cho các tác vụ lập trình tác nhân phức tạp." Sử dụng Haiku 5.5 cho các công việc có phạm vi hẹp: phân loại, tóm tắt, nén, tác nhân con và sử dụng trình duyệt.

Bước tiếp theo

Gửi yêu cầu cuộc gọi đầu tiên ở mức medium, sau đó chạy lại ở mức low và high trên một lời nhắc từ khối lượng công việc của riêng bạn và so sánh usage.output_tokens và chất lượng câu trả lời. Tải xuống Apidog để lưu giữ cả ba lần chạy với các xác nhận, để lần phát hành mô hình tiếp theo chỉ là một thay đổi trường.