Blog

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

Hướng dẫn API Claude Opus 5 từng bước: lấy khóa, gửi yêu cầu đầu tiên của bạn với ID mô hình claude-opus-5, phát trực tiếp phản hồi, thêm công cụ sử dụng, điều chỉnh nỗ lực và đọc mức sử dụng cho các lượt truy cập bộ nhớ đệm.

Ashley Innocent

Ashley Innocent

25 tháng 7 2026

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

Apidog cho doanh nghiệp

Triển khai tại chỗ

SSO & RBAC

Tuân thủ SOC 2

Khám phá Apidog Enterprise

Claude Opus 5 đã được phát hành vào ngày 24 tháng 7 năm 2026, và Anthropic hiện ưu tiên các nhà phát triển sử dụng nó trước tiên: tài liệu hướng dẫn rằng nếu bạn không chắc chắn nên sử dụng mô hình nào, hãy bắt đầu với Claude Opus 5. ID mô hình API là chuỗi chính xác claude-opus-5, không có hậu tố ngày tháng.

Hướng dẫn này sẽ trình bày toàn bộ các bước: lấy khóa, gửi yêu cầu đầu tiên, truyền phát (streaming), sử dụng công cụ, tư duy thích ứng, tham số effort và đọc đối tượng usage để xác nhận bộ nhớ đệm lời nhắc của bạn đang hoạt động. Mọi yêu cầu ở đây đều là HTTP thuần túy với đầu vào và đầu ra JSON, vì vậy bạn có thể xây dựng và gỡ lỗi nó trong Apidog trước khi tích hợp vào mã ứng dụng của mình.

nút

Hai thay đổi từ Opus 4.8 sẽ ảnh hưởng đến bạn ngay trong lần gọi đầu tiên, vì vậy chúng được đề cập trước tiên. Nếu bạn đang di chuyển một dịch vụ hiện có thay vì bắt đầu lại từ đầu, hãy đọc hướng dẫn di chuyển đầy đủ từ Opus 4.8 sang Opus 5 cùng với hướng dẫn này.

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

1. Cơ chế tư duy được bật mặc định. Trên Opus 4.8, một yêu cầu không có trường thinking sẽ chạy mà không có bất kỳ quá trình tư duy nào. Trên Opus 5, yêu cầu tương tự sẽ chạy với cơ chế tư duy thích ứng. max_tokens vẫn là giới hạn cứng cho tổng số token tư duy và token phản hồi, vì vậy một nội dung yêu cầu bạn sao chép từ một tích hợp 4.8 đang hoạt động giờ đây có thể bị cắt bớt giữa chừng câu trả lời. Nếu max_tokens của bạn được điều chỉnh chặt chẽ theo độ dài đầu ra mong đợi, hãy tăng nó lên.

2. Tắt cơ chế tư duy sẽ giới hạn mức nỗ lực của bạn. Việc gửi thinking: {"type": "disabled"} cùng với mức nỗ lực xhigh hoặc max sẽ trả về lỗi 400. Anthropic thực thi điều này cho mỗi yêu cầu, vì vậy nó sẽ thất bại ngay lập tức thay vì giảm hiệu suất một cách lặng lẽ. Giải pháp là chọn một trong hai: giữ cơ chế tư duy bật và giảm nỗ lực để kiểm soát chi phí, hoặc giữ cơ chế tư duy tắt và giới hạn nỗ lực ở mức high.

Lời khuyên của chính Anthropic là lựa chọn đầu tiên. Khi tắt cơ chế tư duy, Opus 5 đôi khi viết các lời gọi công cụ ra dưới dạng văn bản thuần túy (chúng không bao giờ được thực thi và văn bản bị rò rỉ làm ô nhiễm các lượt sau trong một vòng lặp tác tử) và đôi khi rò rỉ các thẻ <thinking> vào đầu ra hiển thị. Bật cơ chế tư duy và giảm nỗ lực sẽ tránh được cả hai vấn đề này.

Cả hai thay đổi đều được ghi lại trong hướng dẫn di chuyển mô hình của Anthropic.

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

Đăng nhập vào Claude Developer Platform, mở phần API keys trong cài đặt tổ chức của bạn và tạo một khóa. Hãy sao chép nó một lần; bạn sẽ không thể đọc lại nó sau này.

Lưu trữ nó trong một biến môi trường thay vì dán trực tiếp vào mã:

export ANTHROPIC_API_KEY="sk-ant-..."

Nếu bạn đang kiểm tra trong một ứng dụng khách GUI, hãy đặt khóa vào một biến môi trường ở đó. Trong Apidog, điều đó có nghĩa là tạo một môi trường (Local, Staging, Production) với biến ANTHROPIC_API_KEY, sau đó tham chiếu {{ANTHROPIC_API_KEY}} trong tiêu đề. Các yêu cầu đã lưu của bạn vẫn có thể chia sẻ với nhóm và bí mật sẽ không bao giờ xuất hiện trong một tập tin xuất bộ sưu tập.

Bạn cũng cần thêm tín dụng thanh toán trước khi các yêu cầu có thể thành công. Mức giá cho Opus 5 là 5 đô la cho mỗi triệu token đầu vào và 25 đô la cho mỗi triệu token đầu ra, giống như Opus 4.8, và bảng phân tích giá đầy đủ bao gồm các mức giá cho bộ nhớ đệm, xử lý theo lô và chế độ nhanh.

Bước 2: Gửi yêu cầu đầu tiên của bạn

Điểm cuối là POST https://api.anthropic.com/v1/messages. Ba tiêu đề quan trọng: khóa của bạn, phiên bản API và loại nội dung.

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

Lưu ý giá trị max_tokens. 4096 là một bước tăng có chủ đích so với 1024 mà bạn thấy trong hầu hết các đoạn mã khởi đầu, bởi vì các token tư duy giờ đây cũng nằm trong cùng một ngân sách.

Mã Python tương đương thông qua 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)

Vòng lặp trên message.content không phải là phần trang trí. content phản hồi là một mảng các khối có kiểu, và khi bật cơ chế tư duy, bạn sẽ thấy một khối thinking trước khối text. Mã giả định content[0].text là câu trả lời sẽ bị lỗi trên Opus 5. Đây là lỗi nâng cấp phổ biến nhất và rất dễ bỏ qua vì yêu cầu vẫn trả về mã 200.

Một vài thông số kỹ thuật đáng lưu ý khi bạn xây dựng: Opus 5 có cửa sổ ngữ cảnh 1M token làm cả mặc định và tối đa (không cần tiêu đề beta, không có phí cao cấp cho ngữ cảnh dài), đầu ra tối đa 128k trên Messages API và thời điểm cắt dữ liệu kiến thức là tháng 5 năm 2026. Tổng quan về các mô hình có bảng đầy đủ, và bài giải thích về Opus 5 của chúng tôi bao gồm phần còn lại của bảng thông số kỹ thuật.

Bước 3: Làm việc với cơ chế tư duy thích ứng

Tư duy thích ứng có nghĩa là mô hình quyết định mức độ suy luận nội bộ mà một yêu cầu xứng đáng. Bạn không đặt ngân sách token. Bạn điều khiển nó bằng nỗ lực (effort), điều này sẽ được đề cập trong bước tiếp theo.

Những gì bạn cần xử lý trong mã:

Để tắt hoàn toàn cơ chế tư duy:

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

Mức nỗ lực được giới hạn ở high trong yêu cầu đó một cách có chủ đích. Tăng nó lên xhigh và bạn sẽ gặp lỗi 400 như đã mô tả ở trên.

Bước 4: Kiểm soát chi phí bằng output_config.effort

Trường effort nằm trong output_config và có thể nhận các giá trị low, medium, high, xhigh hoặc max. Mặc định là high. Đây là tham số mà các phương tiện truyền thông chính thống mô tả là một công tắc chuyển đổi giữa chi phí và khả năng; trên API, nó là một chuỗi trong phần thân yêu cầu của bạn.

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

Ba điều cần biết trước khi bạn điều chỉnh nó.

Bước 5: Truyền phát phản hồi

Thêm "stream": true và điểm cuối sẽ trả về các sự kiện được gửi từ máy chủ thay vì một nội dung JSON duy nhất.

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)

Chuỗi SSE thô là message_start, sau đó content_block_start / content_block_delta / content_block_stop cho mỗi khối, sau đó message_delta mang stop_reason và số token đầu ra cuối cùng, sau đó message_stop.

Khi bật cơ chế tư duy, bạn sẽ nhận được hai khối nội dung được truyền phát theo thứ tự: một khối tư duy mà các delta của nó đến dưới dạng thinking_delta, sau đó là khối văn bản với text_delta. Một giao diện người dùng hiển thị mọi delta vào cùng một bộ đệm sẽ in ra suy luận của mô hình cho người dùng của bạn. Hãy định tuyến chúng riêng biệt ngay từ đầu.

Truyền phát cũng là nơi một ứng dụng khách GUI phát huy tác dụng, bởi vì việc đọc SSE thô trong một thiết bị đầu cuối rất khó chịu. Apidog hiển thị luồng sự kiện khi nó đến, vì vậy bạn có thể theo dõi ranh giới khối và xác nhận các giả định phân tích cú pháp của mình trước khi viết một dòng mã xử lý nào.

Bước 6: Thêm sử dụng công cụ

Các định nghĩa công cụ nằm trong một mảng tools. Mô hình trả lời bằng stop_reason: "tool_use" và một khối nội dung tool_use; bạn thực thi công cụ và gửi kết quả trở lại dưới dạng khối tool_result trong một tin nhắn người dùng mới.

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(b for b in message.content if b.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}
            ]},
        ],
    )

Việc truyền trực tiếp message.content làm lượt của trợ lý là điều bảo toàn khối tư duy. Đừng xây dựng lại lượt đó bằng tay.

Hai chi tiết về Opus 5 quan trọng đối với các tác tử (agents). Chi phí lời nhắc hệ thống cho việc sử dụng công cụ thấp hơn so với Opus 4.8: 286 token với tool_choice được đặt thành auto hoặc none, so với 290 trên 4.8 và 675 trên Opus 4.7. Nhỏ cho mỗi yêu cầu, nhưng đáng kể trên hàng triệu lượt tác tử. Và có một tiêu đề beta, mid-conversation-tool-changes-2026-07-01, cho phép bạn thêm hoặc xóa công cụ giữa các lượt mà không làm mất hiệu lực bộ nhớ đệm lời nhắc.

Opus 5 cũng dễ dàng ủy quyền cho các tác tử phụ hơn so với 4.8. Đối với các khối lượng công việc nhạy cảm về chi phí, hãy giới hạn rõ ràng điều đó trong lời nhắc hệ thống của bạn thay vì phát hiện ra nó trên hóa đơn.

Bước 7: Đọc đối tượng usage để kiểm tra lượt truy cập bộ nhớ đệm

Mỗi phản hồi đều mang một đối tượng usage. Đó là cách trung thực duy nhất để xác nhận việc lưu vào bộ nhớ đệm lời nhắc của bạn đang hoạt động.

"usage": {
  "input_tokens": 84,
  "cache_creation_input_tokens": 6421,
  "cache_read_input_tokens": 0,
  "output_tokens": 913
}

Để lưu vào bộ nhớ đệm một khối, hãy đánh dấu nó bằng cache_control:

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

Lần gọi đầu tiên: cache_creation_input_tokens khác 0 và cache_read_input_tokens là 0. Lần gọi thứ hai với cùng tiền tố: các giá trị này sẽ đảo ngược. Nếu chúng không bao giờ đảo ngược, tiền tố của bạn không giống hệt từng byte hoặc nó thấp hơn mức tối thiểu.

Mức tối thiểu đó là tin tốt trên Opus 5. Lưu vào bộ nhớ đệm lời nhắc giờ đây bắt đầu ở mức **512 token**, giảm từ 1.024 trên Opus 4.8. Các lời nhắc trước đây quá ngắn để lưu vào bộ nhớ đệm giờ đây có thể được lưu mà không cần thay đổi mã, và lượt đọc bộ nhớ đệm được tính phí 0,50 đô la cho mỗi triệu token so với mức phí đầu vào cơ bản 5 đô la. Hãy kiểm tra cache_read_input_tokens trong bộ kiểm thử của bạn để một chỉnh sửa lời nhắc làm hỏng bộ nhớ đệm một cách thầm lặng sẽ hiển thị dưới dạng một kiểm thử thất bại thay vì một hóa đơn. Để biết thêm các cách kiểm soát, hãy xem hướng dẫn của chúng tôi về cắt giảm hóa đơn API Claude của bạn.

Kiểm tra và gỡ lỗi toàn bộ luồng trong Apidog

Tất cả những điều trên là một yêu cầu HTTP với các tiêu đề xác thực, một phần thân JSON, một luồng SSE và một phản hồi mà bạn cần kiểm tra. Apidog là một nền tảng phát triển API tất cả trong một, và đây chính xác là loại điểm cuối mà nó xử lý: nó gửi yêu cầu, lưu trữ khóa, hiển thị luồng và kiểm tra phản hồi. Nó không chạy suy luận hay định tuyến mô hình; cuộc gọi vẫn đến Anthropic.

Một thiết lập tự hoàn vốn ngay trong ngày đầu tiên:

  1. Tạo yêu cầu. POST https://api.anthropic.com/v1/messages với ba tiêu đề, và khóa được lấy từ một biến môi trường thay vì dán trực tiếp.
  2. Lưu vào bộ sưu tập. Nhóm của bạn sử dụng lại một hình dạng yêu cầu đã biết là tốt thay vì mỗi người tự xây dựng lại từ một đoạn mã blog.
  3. Phân nhánh theo mức nỗ lực. Sao chép yêu cầu với output_config.effort được đặt thành low, medium, high và xhigh, gửi cùng một lời nhắc đến từng yêu cầu và so sánh chất lượng đầu ra, độ trễ và số lượng token cạnh nhau. Đây là quy trình kiểm tra nỗ lực mà Anthropic yêu cầu bạn thực hiện, được thực hiện mà không cần viết mã hỗ trợ.
  4. Xem luồng SSE. Bật "stream": true và đọc các sự kiện khi chúng đến để xác nhận bạn xử lý các khối tư duy và khối văn bản riêng biệt.
  5. Kiểm tra tải trọng lời gọi công cụ. Khi stop_reason trả về là tool_use, đối tượng input chính xác mà mô hình tạo ra sẽ ở đó, đó là cách bạn biết input_schema của mình quá lỏng lẻo.
  6. Kiểm tra phản hồi. Thêm các kiểm tra để đảm bảo stop_reason không phải là max_tokens (phép thử cắt bớt của bạn) và cache_read_input_tokens lớn hơn không trong các lần gọi lặp lại (phép thử bộ nhớ đệm của bạn).

Tải xuống Apidog nếu bạn muốn làm theo. Mẫu bộ sưu tập tương tự hoạt động với bất kỳ mô hình Claude nào, vì vậy bạn có thể trỏ nó đến Sonnet 5 hoặc các yêu cầu Opus 4.8 hiện có của bạn và so sánh hành vi.

Các lỗi và cạm bẫy bạn thực sự sẽ gặp phải

Giới hạn chân thực

Opus 5 không phải là mô hình cao cấp nhất trong hệ thống Claude, và điều này đáng được nói rõ ràng. Fable 5 vẫn giữ danh hiệu "mạnh mẽ nhất được phát hành rộng rãi" của Anthropic, với giá 10 đô la cho mỗi triệu token đầu vào và 50 đô la cho mỗi triệu token đầu ra. Opus 5 cũng đứng sau Mythos 5 về khai thác an ninh mạng và nghiên cứu sinh học tự động, điều mà chính Anthropic đã tuyên bố.

Các tuyên bố về điểm chuẩn khi ra mắt (khoảng gấp đôi Opus 4.8 trên Frontier-Bench v0.1, khoảng gấp 3 lần mô hình tốt nhất tiếp theo trên ARC-AGI 3, trong vòng 0,5% so với Fable 5 trên CursorBench 3.2) đều là số liệu của riêng Anthropic 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 đọc chúng như những kết quả do nhà cung cấp thực hiện, sau đó hãy tự chạy đánh giá của riêng bạn. So sánh Opus 5 và Fable 5 trình bày chi tiết khi nào khoảng cách về giá đáng giá và khi nào không, và bài đăng ra mắt của Anthropic là nguồn chính cho các tuyên bố này.

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

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API

Đăng ký miễn phíTải xuống