DEV Community

Cover image for Cách sử dụng API Claude Opus 5
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

Cách sử dụng API Claude Opus 5

Claude Opus 5 được phát hành ngày 24 tháng 7 năm 2026. Anthropic khuyến nghị bắt đầu với mô hình này nếu bạn chưa chắc nên chọn mô hình nào. ID API chính xác là claude-opus-5, không có hậu tố ngày tháng.

Dùng thử Apidog ngay hôm nay

Hướng dẫn này đi qua quy trình triển khai API: tạo khóa, gửi yêu cầu đầu tiên, streaming, tool use, adaptive thinking, output_config.effort và kiểm tra usage để xác nhận prompt caching. Mọi ví dụ đều dùng HTTP và JSON, vì vậy bạn có thể thử, lưu và gỡ lỗi chúng trong Apidog trước khi đưa vào ứng dụng.

Nếu đang nâng cấp từ Opus 4.8, hãy đọc thêm hướng dẫn di chuyển từ Opus 4.8 sang Opus 5.

Trước lần gọi đầu tiên: hai thay đổi gây gián đoạn

1. Adaptive thinking được bật mặc định

Với Opus 4.8, yêu cầu không có trường thinking sẽ không dùng cơ chế tư duy. Với Opus 5, cùng yêu cầu đó chạy adaptive thinking mặc định.

max_tokens vẫn là giới hạn cứng cho tổng token tư duy và token phản hồi. Nếu bạn nâng cấp một request 4.8 có max_tokens được đặt sát độ dài đầu ra kỳ vọng, phản hồi có thể bị cắt giữa chừng.

Việc cần làm: tăng max_tokens và kiểm tra stop_reason trong test.

2. Không thể tắt thinking khi dùng effort quá cao

Request sau sẽ trả về lỗi 400:

{
  "thinking": { "type": "disabled" },
  "output_config": { "effort": "xhigh" }
}
Enter fullscreen mode Exit fullscreen mode

Khi thinking bị tắt, effort chỉ được tối đa là high.

Bạn có hai lựa chọn:

  • Giữ thinking bật và giảm effort để kiểm soát chi phí.
  • Tắt thinking và giới hạn effort ở high.

Anthropic khuyến nghị lựa chọn đầu tiên. Khi tắt thinking, Opus 5 đôi khi có thể ghi tool call dưới dạng văn bản thay vì thực thi chúng, hoặc làm rò rỉ thẻ <thinking> vào đầu ra. Giữ thinking bật giúp tránh các tình huống này.

Xem thêm hướng dẫn di chuyển mô hình của Anthropic.

Bước 1: Lấy khóa API

Đăng nhập Claude Developer Platform, mở phần API keys trong cài đặt tổ chức và tạo khóa mới. Hãy sao chép khóa ngay vì bạn không thể xem lại giá trị đầy đủ sau đó.

Lưu khóa bằng biến môi trường:

export ANTHROPIC_API_KEY="sk-ant-..."
Enter fullscreen mode Exit fullscreen mode

Không dán khóa trực tiếp vào mã nguồn hoặc request đã chia sẻ.

Trong Apidog, tạo môi trường như Local, Staging hoặc Production, thêm biến ANTHROPIC_API_KEY, rồi tham chiếu biến này trong header:

{{ANTHROPIC_API_KEY}}
Enter fullscreen mode Exit fullscreen mode

Cách này giúp nhóm dùng chung request mà không đưa bí mật vào file export collection.

Bạn cũng cần thêm tín dụng thanh toán trước khi request có thể thành công. Giá Opus 5 là 5 USD cho mỗi triệu token đầu vào và 25 USD cho mỗi triệu token đầu ra, giống Opus 4.8. Xem bảng phân tích giá đầy đủ để biết giá cache, batch và chế độ nhanh.

Bước 2: Gửi request đầu tiên

Endpoint:

POST https://api.anthropic.com/v1/messages
Enter fullscreen mode Exit fullscreen mode

Ba header bắt buộc:

  • x-api-key
  • anthropic-version
  • content-type

Ví dụ với curl:

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-opus-5",
    "max_tokens": 4096,
    "messages": [
      {
        "role": "user",
        "content": "Explain the difference between a 429 and a 529 from an API perspective."
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

max_tokens: 4096 là mức khởi đầu hợp lý hơn 1024, vì ngân sách này hiện bao gồm cả token tư duy lẫn token đầu ra.

Ví dụ Python với SDK chính thức:

import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Explain the difference between a 429 and a 529 from an API perspective.",
        }
    ],
)

for block in message.content:
    if block.type == "text":
        print(block.text)
Enter fullscreen mode Exit fullscreen mode

Không giả định message.content[0].text luôn là câu trả lời. content là mảng block có kiểu; khi thinking bật, block đầu tiên có thể là thinking, theo sau mới là text.

Hãy luôn phân tích theo block.type.

Một số thông số cần biết:

  • Cửa sổ ngữ cảnh: 1M token, vừa là mặc định vừa là tối đa.
  • Không cần beta header cho ngữ cảnh 1M.
  • Không có phí premium cho ngữ cảnh dài.
  • Đầu ra tối đa trên Messages API: 128k token.
  • Mốc cắt dữ liệu kiến thức: tháng 5 năm 2026.

Xem tổng quan các mô hình và bài giải thích về Opus 5.

Bước 3: Xử lý adaptive thinking

Adaptive thinking cho phép mô hình tự quyết định lượng suy luận nội bộ cần dùng. Bạn không đặt trực tiếp token budget cho thinking; thay vào đó, điều chỉnh qua output_config.effort.

Khi triển khai, hãy làm ba việc sau:

  1. Phân tích block theo type

    Hiển thị block text cho người dùng. Chỉ log block thinking nếu cần quan sát hoặc debug.

  2. Giữ nguyên block trong hội thoại nhiều lượt

    Khi gọi tool hoặc tiếp tục hội thoại, gửi lại toàn bộ message.content thay vì tự ghép lại từ text.

  3. Theo dõi cắt bớt phản hồi

    Thinking và output dùng chung max_tokens. Nếu nhận:

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

hãy tăng max_tokens.

Ví dụ tắt thinking đúng cách:

{
  "model": "claude-opus-5",
  "max_tokens": 4096,
  "thinking": {
    "type": "disabled"
  },
  "output_config": {
    "effort": "high"
  },
  "messages": [
    {
      "role": "user",
      "content": "Return only the HTTP status code."
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Không đổi effort sang xhigh hoặc max trong request này, nếu không API sẽ trả về 400.

Bước 4: Kiểm soát chi phí với output_config.effort

effort nằm trong output_config và hỗ trợ:

low
medium
high
xhigh
max
Enter fullscreen mode Exit fullscreen mode

Giá trị mặc định là high.

Ví dụ request coding hoặc agentic workload với xhigh:

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-opus-5",
    "max_tokens": 65536,
    "output_config": {
      "effort": "xhigh"
    },
    "messages": [
      {
        "role": "user",
        "content": "Refactor this handler to stream responses and keep backpressure."
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

Khi điều chỉnh effort, lưu ý:

  • Không tái sử dụng trực tiếp cấu hình effort từ Opus 4.8.

    Các mức đã được hiệu chỉnh lại. low và medium mạnh hơn đáng kể trên Opus 5.

  • Bắt đầu với xhigh cho coding và agent workloads.

    Đồng thời cấp đủ max_tokens; 65536 là mốc khởi đầu phù hợp cho lượt tác tử dài.

  • Giảm effort không đồng nghĩa với output ngắn hơn.

    Việc này giảm lượng suy luận nội bộ. Nếu cần phản hồi ngắn hơn, hãy yêu cầu rõ trong prompt.

Để chọn mức phù hợp, chạy cùng một bộ đánh giá với low, medium, high và xhigh, sau đó so sánh chất lượng, độ trễ và token sử dụng. Xem phân tích tham số effort.

Bước 5: Stream phản hồi

Thêm "stream": true để nhận Server-Sent Events thay vì một JSON response duy nhất.

Ví dụ Python:

with client.messages.stream(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Draft a retry policy for a flaky upstream.",
        }
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

    final = stream.get_final_message()
    print("\n\nusage:", final.usage)
Enter fullscreen mode Exit fullscreen mode

Chuỗi SSE thô có dạng:

message_start
content_block_start
content_block_delta
content_block_stop
message_delta
message_stop
Enter fullscreen mode Exit fullscreen mode

Khi thinking bật, bạn thường nhận hai content block theo thứ tự:

  1. Block thinking, với delta kiểu thinking_delta.
  2. Block text, với delta kiểu text_delta.

Không đưa mọi delta vào cùng một UI buffer. Nếu làm vậy, bạn có thể vô tình hiển thị suy luận của mô hình cho người dùng. Hãy route thinking_delta và text_delta qua hai luồng xử lý riêng.

Apidog có thể hiển thị SSE khi event đến, giúp bạn kiểm tra block boundary và logic parser trước khi viết client code.

Bước 6: Thêm tool use

Khai báo tool qua mảng tools. Khi mô hình cần gọi tool, response có:

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

và một content block kiểu tool_use.

Quy trình:

  1. Gửi request kèm tools.
  2. Tìm block tool_use.
  3. Thực thi tool trong ứng dụng của bạn.
  4. Gửi kết quả lại bằng block tool_result.
  5. Giữ nguyên message.content của assistant trong lịch sử hội thoại.

Ví dụ:

tools = [
    {
        "name": "get_order_status",
        "description": "Look up the current status of a customer order by ID.",
        "input_schema": {
            "type": "object",
            "properties": {
                "order_id": {
                    "type": "string",
                    "description": "The order ID, e.g. A-10293",
                }
            },
            "required": ["order_id"],
        },
    }
]

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    tools=tools,
    messages=[
        {
            "role": "user",
            "content": "What's the status of order A-10293?",
        }
    ],
)

if message.stop_reason == "tool_use":
    call = next(block for block in message.content if block.type == "tool_use")
    result = get_order_status(**call.input)

    follow_up = client.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        tools=tools,
        messages=[
            {
                "role": "user",
                "content": "What's the status of order A-10293?",
            },
            {
                "role": "assistant",
                "content": message.content,
            },
            {
                "role": "user",
                "content": [
                    {
                        "type": "tool_result",
                        "tool_use_id": call.id,
                        "content": result,
                    }
                ],
            },
        ],
    )
Enter fullscreen mode Exit fullscreen mode

Điểm quan trọng là truyền trực tiếp:

{"role": "assistant", "content": message.content}
Enter fullscreen mode Exit fullscreen mode

Đừng tự tạo lại assistant message từ text, vì bạn sẽ làm mất thinking block và các block có cấu trúc khác.

Một số chi tiết đáng chú ý cho agent:

  • System prompt overhead khi dùng tool thấp hơn Opus 4.8: 286 token với tool_choice là auto hoặc none, so với 290 trên Opus 4.8 và 675 trên Opus 4.7.
  • Beta header mid-conversation-tool-changes-2026-07-01 cho phép thêm hoặc xóa tool giữa các lượt mà không làm mất hiệu lực prompt cache.
  • Opus 5 có thể ủy quyền cho tác tử phụ dễ hơn Opus 4.8. Với workload nhạy cảm chi phí, hãy giới hạn rõ hành vi này trong system prompt.

Bước 7: Kiểm tra prompt cache qua usage

Mỗi response chứa object usage:

{
  "usage": {
    "input_tokens": 84,
    "cache_creation_input_tokens": 6421,
    "cache_read_input_tokens": 0,
    "output_tokens": 913
  }
}
Enter fullscreen mode Exit fullscreen mode

Để cache nội dung ổn định, gắn cache_control vào block tương ứng:

{
  "model": "claude-opus-5",
  "max_tokens": 4096,
  "system": [
    {
      "type": "text",
      "text": "<your long, stable instructions and reference material>",
      "cache_control": {
        "type": "ephemeral"
      }
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "Question one."
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Cách đọc kết quả:

Lần gọi cache_creation_input_tokens cache_read_input_tokens
Lần đầu Khác 0 0
Lần sau với cùng tiền tố Thường là 0 Khác 0

Nếu cache read không xuất hiện, kiểm tra:

  • Prefix có thay đổi dù chỉ một byte hay không.
  • Nội dung cache có đủ ngưỡng token hay không.
  • System prompt, tool definitions hoặc cấu trúc request có thay đổi không.

Trên Opus 5, prompt caching bắt đầu từ 512 token, giảm từ 1.024 token trên Opus 4.8. Cache read được tính 0,50 USD mỗi triệu token, thấp hơn giá input cơ bản 5 USD mỗi triệu token.

Hãy thêm assertion vào test suite:

cache_read_input_tokens > 0
Enter fullscreen mode Exit fullscreen mode

Nhờ đó, thay đổi prompt làm hỏng cache sẽ hiện thành test fail thay vì chỉ xuất hiện trên hóa đơn. Xem thêm hướng dẫn cắt giảm hóa đơn API Claude.

Kiểm tra toàn bộ luồng trong Apidog

Toàn bộ tích hợp Claude ở đây gồm HTTP headers, JSON body, SSE stream và response assertions. Apidog giúp gửi request, lưu biến môi trường, quan sát stream và kiểm tra response. Nó không chạy inference hoặc định tuyến model; request vẫn được gửi đến Anthropic.

Thiết lập thực tế:

  1. Tạo request

    Dùng POST https://api.anthropic.com/v1/messages, thêm ba header bắt buộc và tham chiếu khóa từ biến môi trường.

  2. Lưu vào collection

    Giúp đội ngũ dùng lại request đã chuẩn hóa thay vì mỗi người tự tạo lại từ code snippet.

  3. Tạo các biến thể effort

    Sao chép request và đặt output_config.effort lần lượt là low, medium, high và xhigh. Gửi cùng prompt để so sánh chất lượng, latency và token.

  4. Quan sát SSE stream

    Bật "stream": true, xác nhận ứng dụng phân tách thinking block và text block.

  5. Kiểm tra tool payload

    Khi stop_reason là tool_use, kiểm tra input mà model sinh ra để đánh giá input_schema có quá lỏng hay không.

  6. Thêm response assertions

    Kiểm tra:

    • stop_reason không phải max_tokens
    • cache_read_input_tokens > 0 với request lặp lại

Tải xuống Apidog để làm theo. Collection tương tự cũng dùng được cho Sonnet 5 hoặc các request Opus 4.8.

Lỗi và cạm bẫy thường gặp

  • Lỗi 400 với thinking: disabled và effort: xhigh hoặc max

    Giảm effort xuống high, hoặc bật lại thinking.

  • Lỗi 400 với sampling parameters

    temperature, top_p và top_k ở giá trị không mặc định vẫn trả về lỗi 400, như trên Opus 4.8. Điều khiển hành vi qua system prompt thay vì sampling parameters.

  • Phản hồi bị cắt bớt

    Nếu stop_reason: "max_tokens", thinking và output đã vượt chung token budget. Tăng max_tokens.

  • Priority Tier không được hỗ trợ trên Opus 5

    Opus 4.8 vẫn hỗ trợ. Đây là điểm cần đánh giá trước khi chuyển traffic nếu hệ thống doanh nghiệp phụ thuộc vào Priority Tier.

  • System message giữa hội thoại

    Opus 5 chấp nhận mục role: "system" trong messages, trong khi Opus 4.8 trả 400. Điều này hữu ích nếu bạn từng phải dùng workaround.

  • Prompt yêu cầu “kiểm tra lại câu trả lời”

    Opus 5 tự xác minh công việc mà không cần chỉ dẫn này. Nếu mang prompt đó từ Opus 4.8 sang, hãy thử loại bỏ để tránh tiêu tốn thinking token không cần thiết.

Giới hạn cần lưu ý

Opus 5 không phải mô hình cao cấp nhất trong hệ thống Claude. Fable 5 vẫn là mô hình “mạnh mẽ nhất được phát hành rộng rãi” của Anthropic, với giá 10 USD mỗi triệu input token và 50 USD mỗi triệu output token.

Opus 5 cũng đứng sau Mythos 5 trong khai thác an ninh mạng và nghiên cứu sinh học tự động, theo tuyên bố của Anthropic.

Các benchmark khi ra mắt, bao gồm khoảng gấp đôi Opus 4.8 trên Frontier-Bench v0.1, khoảng gấp 3 mô hình tốt nhất tiếp theo trên ARC-AGI 3, và cách Fable 5 trong vòng 0,5% trên CursorBench 3.2, đều là số liệu do Anthropic công bố và chưa được tái tạo độc lập tính đến ngày 25 tháng 7 năm 2026.

Hãy coi đây là dữ liệu từ nhà cung cấp, sau đó chạy eval của chính bạn. Xem so sánh Opus 5 và Fable 5 và bài đăng ra mắt của Anthropic.

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

ID model của Claude Opus 5 là gì?

claude-opus-5, không có hậu tố ngày tháng.

Trên Amazon Bedrock, ID là:

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

Google Cloud và Claude Platform trên AWS sử dụng ID bên thứ nhất.

Vì sao request Opus 4.8 trước đây bị cắt khi chuyển sang Opus 5?

Adaptive thinking được bật mặc định. max_tokens giới hạn tổng token tư duy và phản hồi, nên mức đủ cho Opus 4.8 có thể không đủ cho Opus 5.

Tăng max_tokens và kiểm tra:

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

Vì sao tôi nhận lỗi 400 khi tắt thinking?

Bạn có thể đã dùng:

{
  "thinking": { "type": "disabled" },
  "output_config": { "effort": "xhigh" }
}
Enter fullscreen mode Exit fullscreen mode

Khi thinking bị tắt, hãy giới hạn effort ở high. Hoặc bật thinking và giảm effort.

Có cần beta header để dùng context window 1M không?

Không. Với Opus 5, 1M token là cả mặc định lẫn mức tối đa, không cần beta header và không có phí premium cho ngữ cảnh dài.

Bạn cần header beta output-300k-2026-03-24 để có 300k output trong Batch API. Messages API giới hạn output ở 128k.

Có thể tái sử dụng effort settings từ Opus 4.8 không?

Không nên. Anthropic cho biết các mức effort đã được hiệu chỉnh lại; low và medium mạnh hơn đáng kể trên Opus 5.

Hãy chạy lại eval dựa trên workload thực tế của bạn.

Apidog có chạy model không?

Không. Apidog gửi, kiểm tra và thử nghiệm HTTP request; inference diễn ra ở phía Anthropic. Apidog hỗ trợ quản lý khóa, streaming, tool payload và response validation quanh lời gọi API.

Top comments (0)