Cách Sử Dụng API Claude Sonnet 5.5: Lần Gọi Đầu Tiên, Nỗ Lực, Tư Duy, Công Cụ và Truyền Phát

Để sử dụng API Claude Sonnet 5.5, hãy gửi yêu cầu POST đến https://api.anthropic.com/v1/messages với "model": "claude-sonnet-5-5", khóa của bạn trong tiêu đề x-api-key, và anthropic-version: 2023-06-01. Chi phí là 2 đô la cho mỗi triệu token đầu vào và 10 đô la cho mỗi triệu token đầu ra, đọc được tới 1 triệu token ngữ cảnh, ghi được tới 128K, chạy tư duy thích ứng theo mặc định và mặc định ở mức độ nỗ lực high.

Anthropic đã phát hành Sonnet 5.5 vào ngày 28 tháng 9 năm 2026 (Claude Sonnet 5.5 là gì bao gồm các thông số kỹ thuật và điểm chuẩn). Hướng dẫn này sẽ trình bày cuộc gọi đầu tiên bằng curl, Python và TypeScript, sau đó là mức độ nỗ lực, tư duy, công cụ, truyền trực tuyến, từ chối và giới hạn tốc độ. Bạn đang di chuyển mã Sonnet 5? Hướng dẫn Sonnet 5.5 so với Sonnet 5 có mọi thay đổi quan trọng với JSON trước/sau. Bạn có thể gửi từng yêu cầu dưới đây từ Apidog và lưu nó dưới dạng bài kiểm tra đã lưu với các xác nhận.

Tổng quan về API Claude Sonnet 5.5

Nguồn: trang mô hình Sonnet 5.5 và hướng dẫn di chuyển.

Ví dụ về API Claude Sonnet 5.5: cuộc gọi đầu tiên của bạn

Tạo một khóa (người hướng dẫn khóa API của Anthropic sẽ hướng dẫn bạn) và xuất nó dưới dạng ANTHROPIC_API_KEY thay vì mã hóa cứng. 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-sonnet-5-5",
    "max_tokens": 4096,
    "output_config": {"effort": "medium"},
    "messages": [{"role": "user", "content": "Explain idempotency keys in two sentences."}]
  }'

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

import anthropic

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "Explain idempotency keys in two sentences."}],
)
print(response.stop_reason)
for block in response.content:
    if block.type == "text":
        print(block.text)

TypeScript cũng hoạt động tương tự:

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

const client = new Anthropic();
const response = await client.messages.create({
  model: "claude-sonnet-5-5",
  max_tokens: 4096,
  output_config: { effort: "medium" },
  messages: [{ role: "user", content: "Explain idempotency keys in two sentences." }],
});
for (const block of response.content) {
  if (block.type === "text") console.log(block.text);
}

Đọc các khối nội dung theo type. Tư duy được bật theo mặc định, vì vậy một phản hồi có thể bắt đầu bằng một khối thinking, và mã đọc content[0].text sẽ bị lỗi. Token tư duy được tính phí là đầu ra và tính vào max_tokens ngay cả khi văn bản của chúng bị ẩn, vì vậy hãy để lại khoảng trống lớn hơn so với phản hồi bạn mong đợi.

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 chi phí và chất lượng của bạn. Anthropic đã hiệu chỉnh lại các mức độ cho Sonnet 5.5, vì vậy cài đặt Sonnet 5 sẽ không còn hiệu lực; hãy thực hiện một đánh giá mới trên các đánh giá của riêng bạn. Hướng dẫn tạo lời nhắc gợi ý các điểm bắt đầu sau:

Phạm vi rất rộng. Trên các lần chạy Terminal-Bench 4.0 của Anthropic, Sonnet 5.5 đạt 43.0% ở mức high với chi phí 1.94 đô la cho mỗi lần thử và 70.6% ở mức max với chi phí 12.54 đô la. Phân tích chi phí Sonnet 5.5 trình bày chi phí cho mỗi yêu cầu.

Lên kế hoạch cho ba hành vi. Từ mức medium trở lên, mô hình sẽ suy nghĩ trước hầu hết mọi phản hồi, ngay cả lời chào, và việc nhắc nó suy nghĩ ít hơn không đáng tin cậy: thay vào đó hãy giảm mức độ nỗ lực. Ở mức low và medium, nó có xu hướng kiểm tra sớm đối với các tác vụ tác nhân dài. Và việc thay đổi mức độ nỗ lực 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 lời nhắc. Để chuyển đổi các mức độ trong cuộc hội thoại và giữ bộ nhớ đệm, hãy sử dụng mức độ nỗ lực theo từng tin nhắn (beta, tiêu đề anthropic-beta: mid-conversation-output-config-2026-07-01): thêm một tin nhắn role: "system" với content trống và output_config.effort mới.

Kiểm soát tư duy: thích ứng hoặc giữa các công cụ (between_tools)

Bỏ qua trường thinking và Sonnet 5.5 sẽ chạy tư duy thích ứng. Nó từ chối {"type": "disabled"} với lỗi 400. Để tắt tư duy ban đầu, hãy gửi between_tools, cài đặt thấp nhất:

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 16000,
  "thinking": {"type": "between_tools"},
  "output_config": {"effort": "high"},
  "messages": [{"role": "user", "content": "..."}]
}

Các quy tắc cho Sonnet 5.5 between_tools:

• Nó chỉ hoạt động ở mức low, medium hoặc high. Ở mức xhigh hoặc max, nó trả về lỗi 400.
• Nó không chấp nhận trường nào khác. Thêm display, budget_tokens hoặc block_binding sẽ trả về lỗi 400.
• Nó không yêu cầu tiêu đề beta và hoạt động trên mọi nền tảng.
• Mức độ nỗ lực không thể thay đổi giữa cuộc hội thoại khi nó đã được đặt.
• Các phiên bản SDK không định nghĩa nó sẽ không vượt qua kiểm tra kiểu, vì vậy hãy cập nhật SDK của bạn.

Trong tư duy thích ứng, display quyết định nội dung của các khối tư duy. Mặc định, omitted, trả về mỗi khối thinking với một trường thinking trống cùng với một signature. summarized trả về các bản tóm tắt dễ đọc. updates (beta, tiêu đề thinking-display-updates-2026-08-18) chỉ trả về các cập nhật tiến độ dưới dạng văn bản.

Các cập nhật tiến độ là thay đổi nhiều khả năng gây nhầm lẫn cho giao diện người dùng nhất. Sonnet 5.5 đặt các ghi chú dài hơn một hoặc hai câu, được viết giữa các lần gọi công cụ, vào các khối thinking riêng thay vì text. Theo mặc định omitted, các khối đó trống, vì vậy giao diện tác nhân từng tường thuật các bước của nó sẽ trở nên im lặng. Đặt display: "updates" hoặc "summarized", hoặc chạy between_tools, sẽ trả về các ghi chú kèm văn bản. Hiển thị từng khối thinking không trống trước khối tool_use theo sau nó. Yêu cầu lý do trong văn bản phản hồi có thể dẫn đến việc từ chối reasoning_extraction, vì vậy hãy đọc các khối này thay thế.

Sử dụng công cụ mà không cần buộc lựa chọn công cụ (tool_choice)

Việc sử dụng công cụ bắt buộc đã bị loại bỏ. Một tool_choice là {"type": "any"} hoặc {"type": "tool", ...} sẽ trả về lỗi 400 với thông báo này, ngay cả trên điểm cuối đếm token:

tool_choice: type "tool" and "any" are not supported for this model.

Gửi auto, đánh dấu công cụ strict: true để đầu vào của nó khớp với lược đồ, và cho mô hình biết trong lời nhắc khi nào nên gọi nó:

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "tools": [{
    "name": "get_weather",
    "description": "Get the current weather for a city",
    "input_schema": {
      "type": "object",
      "properties": {"location": {"type": "string"}},
      "required": ["location"],
      "additionalProperties": false
    },
    "strict": true
  }],
  "tool_choice": {"type": "auto"},
  "messages": [{"role": "user", "content": "What's the weather in Paris? Use the get_weather tool."}]
}

Một yêu cầu có thể chứa tối đa 20 công cụ nghiêm ngặt (strict tools), và các lược đồ nghiêm ngặt yêu cầu additionalProperties: false trên mỗi đối tượng. Trên Amazon Bedrock, các công cụ nghiêm ngặt không khả dụng cho Sonnet 5.5: hãy gửi auto mà không có strict và xác thực đầu vào trong mã của bạn.

Hai chi tiết vòng lặp quan trọng. Truyền lại mọi khối thinking mà không thay đổi cùng với khối tool_use của nó, bao gồm cả những khối trống. Và hãy dự đoán những lỗi chính tả không thường xuyên, chẳng hạn như bash cho một công cụ được khai báo là Bash. Hướng dẫn tạo lời nhắc gợi ý chấp nhận các kết quả khớp rõ ràng, hoặc trả về một tool_result với is_error: true ghi rõ tên chính xác.

Truyền trực tuyến phản hồi

Thêm "stream": true vào phần thân yêu cầu, hoặc sử dụng trình trợ giúp luồng của SDK. Đối với lập trình tác nhân, hướng dẫn tạo lời nhắc khuyến nghị max_tokens là 128.000 với truyền trực tuyến:

with client.messages.stream(
    model="claude-sonnet-5-5",
    max_tokens=128000,
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "Review this diff for bugs: ..."}],
) as stream:
    for event in stream:
        if event.type == "content_block_delta" and event.delta.type == "text_delta":
            print(event.delta.text, end="", flush=True)
    final = stream.get_final_message()

Các sự kiện được gửi từ máy chủ (Server-sent events) đến dưới dạng message_start, sau đó là content_block_start, content_block_delta và content_block_stop cho mỗi khối, sau đó là message_delta (mang theo stop_reason) và message_stop. Trong chế độ omitted, một khối tư duy sẽ truyền một thinking_delta trống và một signature_delta, sau đó văn bản bắt đầu. Dự kiến ​​sẽ có một khoảng dừng vài giây trước khi một khối cập nhật tiến độ mở ra.

stream.get_final_message() (TypeScript: stream.finalMessage()) xây dựng lại các khối hoàn chỉnh với chữ ký của chúng. Thêm nội dung đó vào lịch sử như lượt của trợ lý, không thay đổi, và giữ lịch sử chỉ có thể thêm vào. Sonnet 5.5 ký từng khối tư duy trong cuộc trò chuyện trước đó, vì vậy trên các tài khoản được tạo vào hoặc sau ngày 31 tháng 8 năm 2026 (00:00 UTC), việc phát lại một khối sau khi chỉnh sửa lịch sử trước đó sẽ trả về lỗi 400. Các khối cũng được liên kết với tài khoản đã tạo ra chúng.

Xử lý từ chối và dự phòng

Việc từ chối không phải là một lỗi. Bạn sẽ nhận được HTTP 200 với stop_reason: "refusal" và một đối tượng stop_details có category là cyber, bio, frontier_llm, reasoning_extraction hoặc general_harms, cùng với một explanation. Hiển thị giải thích thay vì phân tích nó; cách diễn đạt của nó không ổn định. Rẽ nhánh theo stop_reason trước khi bạn đọc content.

Dự phòng phía máy chủ là tùy chọn tham gia. Thêm "fallbacks": "default" và tiêu đề anthropic-beta: server-side-fallback-2026-07-01 (beta, chỉ API Claude), và API sẽ thử lại các yêu cầu bị từ chối thuộc loại cyber và frontier_llm trên Sonnet 5. Ba danh mục còn lại không được thử lại. Trường model của phản hồi đặt tên mô hình đã phục vụ nó, và một khối nội dung fallback đánh dấu sự chuyển giao.

Giới hạn tốc độ

Sonnet 5.5 có giới hạn tốc độ riêng, tách biệt với Sonnet 5. Trang giới hạn tốc độ liệt kê bốn cấp:

Để xử lý lỗi 429 và trì hoãn, xem hướng dẫn vượt quá giới hạn tốc độ.

Kiểm tra API Claude Sonnet 5.5 trong Apidog

Các yêu cầu đã lưu giúp việc so sánh nỗ lực và gỡ lỗi luồng 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. Tham chiếu nó dưới dạng {{ANTHROPIC_API_KEY}} trong tiêu đề x-api-key, bên cạnh anthropic-version và content-type.
2. Tạo yêu cầu POST đến https://api.anthropic.com/v1/messages, dán phần thân của 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. Việc từ chối giờ đây sẽ làm cho bài kiểm tra thất bại thay vì được thông qua một cách im lặng.
4. Nhân bản yêu cầu với "stream": true. Apidog hiển thị phản hồi text/event-stream theo từng sự kiện, vì vậy bạn có thể xem thinking_delta trống, signature_delta và văn bản đến theo thứ tự.
5. Sao chép lại với "model": "claude-sonnet-5" và giữ cặp này trong một thư mục: cùng một lời nhắc, hai mô hình, usage cạnh nhau.

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

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

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

Tôi có thể tắt hoàn toàn tư duy không? Không. disabled trả về lỗi 400. between_tools là cài đặt thấp nhất: không có tư duy ban đầu, ở mức độ nỗ lực low, medium hoặc high.

Tại sao yêu cầu Sonnet 5 của tôi trả về lỗi 400 trên Sonnet 5.5? Trước tiên, hãy kiểm tra thinking.type: "disabled" và tool_choice bị buộc. Hướng dẫn Sonnet 5.5 so với Sonnet 5 bao gồm tất cả năm thay đổi quan trọng và cách khắc phục chúng.

Có API Claude Sonnet 5.5 miễn phí không? API của Anthropic là trả trước và không có trang chính thức nào liệt kê tín dụng đăng ký miễn phí. Gói trò chuyện Claude cũng không bao gồm quyền truy cập API. Hướng dẫn API miễn phí bao gồm các chương trình tín dụng và con đường trả phí rẻ nhấ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 high và so sánh usage.output_tokens cùng chất lượng câu trả lời trên một lời nhắc từ khối lượng công việc của riêng bạn. Tải xuống Apidog để lưu cả hai lần chạy với các xác nhận. Nếu bạn muốn làm việc từ terminal, hãy xem Claude Sonnet 5.5 trong Claude Code.