Hướng dẫn tích hợp Claude API: Console, API Key và Messages (2026)

Điểm khó khi tích hợp Claude API không nằm ở việc “có biết gửi yêu cầu HTTP hay không”, mà ở vài chi tiết dễ sai: khóa đặt trong header nào, anthropic-version có bắt buộc không, vì sao không thể bỏ max_tokens, vì sao content là mảng chứ không phải chuỗi. Chỉ cần làm đúng những điểm này, một lần gọi tối thiểu có thể chạy trong khoảng mười phút.

Bài viết đi theo thứ tự: tài khoản và khóa, header, curl, Python, truyền phát và tham số, xử lý lỗi, an toàn khóa, cuối cùng là cách dùng một cổng tương thích làm điểm vào thay thế. ID mô hình, ngữ cảnh và cách tính phí căn cứ theo tài liệu chính thức của Anthropic và bảng giá mô hình trên site.

Lưu ý: Anthropic và Claude là nhãn hiệu của chủ sở hữu tương ứng; OpenAI là nhãn hiệu của chủ sở hữu tương ứng. Bài viết chỉ nhằm giải thích kỹ thuật tích hợp. Mô hình, giá và hạn mức có thể điều chỉnh, vui lòng đối chiếu tài liệu chính thức trước khi tích hợp.

1. Chuẩn bị trước khi tích hợp: tài khoản, không gian làm việc và khóa

Claude API dùng Anthropic Console để quản lý tài khoản, không gian làm việc, API Key và hóa đơn. Trước khi bắt đầu, hãy xác nhận ba việc:

Hạng mục chuẩn bị	Cần xác nhận điều gì	Ghi chú
Tài khoản	Email xác minh được, đăng nhập được Console	Đội ngũ nên dùng email công ty
Không gian làm việc	Khóa thuộc không gian nào	Không gian ảnh hưởng đến thành viên, khóa và mức dùng
Tính phí	Phương thức thanh toán, thông tin hóa đơn, hạn mức khả dụng	Căn cứ hiển thị thực tế trên Console

Nếu đội chưa xác định ai quản lý hóa đơn, đừng vội tạo khóa sản xuất. Khóa đã phát ra thì mức dùng và quyền đều gắn với không gian tương ứng; tách chi phí về sau sẽ khó hơn.

2. Tạo API Key: sáu bước

Mở Anthropic Console (console.anthropic.com), đăng ký hoặc đăng nhập, hoàn tất xác minh email.
Tạo hoặc chọn không gian làm việc. Nên tách sản xuất, kiểm thử và thử nghiệm cá nhân để tránh dùng một khóa ở mọi nơi.
Vào trang API Keys, tạo khóa mới, đặt tên rõ mục đích, ví dụ prod-backend-2026-10.
Sao chép khóa và lưu ngay vào dịch vụ quản lý khóa hoặc biến môi trường. Phần lớn bảng điều khiển chỉ hiển thị đầy đủ giá trị một lần khi tạo.
Trong trang tính phí của Console, xác nhận phương thức thanh toán, thông tin hóa đơn và thiết lập hạn mức. Việc có hỗ trợ nạp trước, hóa đơn và giới hạn hạn mức hay không tùy lựa chọn thực tế của bảng điều khiển.
Đặt biến môi trường cục bộ và gửi một yêu cầu tối thiểu để xác nhận khóa dùng được.

export ANTHROPIC_API_KEY="sk-ant-khoa-cua-ban"

Không ghi khóa vào mã nguồn, kho Git, trang frontend hay lịch sử trò chuyện. Giai đoạn kiểm thử cũng nên tạo khóa riêng để có thể thu hồi bất cứ lúc nào.

3. Header và lần gọi curl tối thiểu

Endpoint của Messages API là POST https://api.anthropic.com/v1/messages; ba header quan trọng nhất:

Header	Giá trị	Tác dụng
`x-api-key`	API Key của bạn	Xác thực Anthropic API Key
`anthropic-version`	`2023-06-01`	Chỉ định phiên bản API, thiếu có thể báo lỗi
`content-type`	`application/json`	Khai báo thân yêu cầu JSON

Lưu ý: API Key đi qua x-api-key, không phải Authorization: Bearer. Trộn hai kiểu xác thực này là nguyên nhân rất phổ biến gây lỗi 401.

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "system": "Bạn là trợ lý kỹ thuật tiếng Việt, trả lời ngắn gọn.",
    "messages": [
      {"role": "user", "content": "Giải thích API gateway là gì trong ba câu."}
    ]
  }'

ID mô hình trong ví dụ chỉ là một trong các dòng hiện có; dòng khả dụng thực tế, ngữ cảnh và giá căn cứ theo Models API chính thức và bảng giá mô hình trên site. Trường content trong phản hồi là mảng các khối nội dung; văn bản thường nằm ở content[0].text, nhưng cách an toàn hơn là duyệt mảng và kiểm tra type == "text".

4. Gọi Messages API bằng Python

Cài SDK chính thức:

pip install anthropic

Lần gọi tối thiểu:

import os
import anthropic

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

resp = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    system="Bạn là trợ lý kỹ thuật tiếng Việt, trả lời ngắn gọn.",
    messages=[
        {"role": "user", "content": "Giải thích API gateway là gì trong ba câu."}
    ],
)

for block in resp.content:
    if block.type == "text":
        print(block.text)

print(resp.stop_reason)
print(resp.usage.input_tokens, resp.usage.output_tokens)

Vài điểm cần nhớ:

system là tham số cấp cao nhất, không viết thành tin nhắn {"role": "system"}. Vai trò tin nhắn của Messages API chủ yếu là user và assistant.
max_tokens là bắt buộc, biểu thị độ dài đầu ra tối đa của lần trả lời này. Đặt quá nhỏ sẽ bị cắt và stop_reason hiển thị max_tokens; đặt quá lớn thì phải cân nhắc chi phí và thời gian chờ.
resp.content là mảng khối, có thể chứa khối văn bản, khối suy nghĩ hoặc khối gọi công cụ. Mã nghiệp vụ không nên mặc định chỉ có văn bản.
Ghi lại usage và stop_reason; đối soát và xử lý sự cố đều dựa vào chúng.

5. system, max_tokens và truyền phát

system dùng để đặt vai trò, định dạng đầu ra và điều kiện biên. Nội dung ổn định, ít thay đổi nên đặt phía trước; đầu vào người dùng thay đổi đặt trong messages, có lợi cho việc trúng bộ nhớ đệm.

max_tokens không phải “càng lớn càng tốt”. Nó giới hạn đầu ra của một lần gọi, không làm thay đổi chi phí đầu vào; báo cáo dài, mã dài cần đủ chỗ, còn phân loại và trích xuất có thể đặt nhỏ hơn. Môi trường sản xuất nên cấu hình riêng theo từng loại endpoint thay vì dùng một giá trị chung.

Truyền phát phù hợp với câu trả lời dài và giao diện tương tác. Cách viết với SDK Python:

with client.messages.stream(
    model="claude-opus-5-5",
    max_tokens=4096,
    system="Bạn là trợ lý kỹ thuật tiếng Việt.",
    messages=[{"role": "user", "content": "Viết một đoạn mô tả sản phẩm khoảng 200 từ."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Yêu cầu truyền phát cũng trả về usage và stop_reason; đừng bỏ sót khi ghi dữ liệu. Nếu dùng HTTP thuần, thêm "stream": true vào thân yêu cầu; phản hồi là luồng sự kiện SSE, cần phân tích theo các sự kiện như content_block_delta.

6. Đặt tên mô hình và chọn phiên bản

Mô hình Claude được chia theo dòng Opus, Sonnet, Haiku; định vị, ngữ cảnh và giá của các dòng khác nhau. ID mô hình thường có hai dạng: bí danh ổn định và ảnh chụp kèm ngày. Môi trường sản xuất cần xác định rõ dùng dạng nào, không lấy tên hiển thị trên bảng điều khiển ghi thẳng vào mã.

Thứ tự lựa chọn đề xuất:

Dùng bộ đánh giá nghiệp vụ để chọn ra dòng đáp ứng yêu cầu chất lượng.
So sánh độ trễ, ngữ cảnh và chi phí.
Cuối cùng xác nhận dòng đó khả dụng ở khu vực mục tiêu và với cách tích hợp đã chọn.

Mô hình có thể được thêm hoặc ngừng cung cấp, ID cũ cũng có thể chuyển sang trạng thái legacy. Hãy tập trung tên mô hình vào cấu hình hoặc bảng ánh xạ để khi di chuyển chỉ sửa một chỗ. Dòng khả dụng cụ thể căn cứ theo Models API chính thức, bảng điều khiển và bảng giá mô hình.

7. Xử lý 401, 429 và 400

Mã trạng thái	Nguyên nhân thường gặp	Thứ tự xử lý
401	Thiếu khóa, sai header, khóa bị thu hồi, không khớp không gian làm việc	Kiểm tra `x-api-key`, khoảng trắng/xuống dòng, trạng thái khóa, base URL
429	Vượt tần suất yêu cầu hoặc tốc độ Token, đồng thời tăng đột biến, vấn đề hạn mức	Đọc `retry-after`, lùi hàm mũ kèm nhiễu, tách khóa, giảm đồng thời
400	JSON không hợp lệ, thiếu `max_tokens`, sai ID mô hình, tham số vượt giới hạn	Giữ thân lỗi và request id, đối chiếu từng mục trong thân yêu cầu
404	Đường dẫn hoặc tên mô hình không tồn tại	Xác nhận `/v1/messages` và ID mô hình
5xx	Sự cố tạm thời phía thượng nguồn	Thử lại có giới hạn, vẫn thất bại thì chuyển điểm vào dự phòng

Khi xử lý sự cố, trước hết hãy giữ header request-id. Với 401, đừng vội nghi ngờ số dư; hãy kiểm tra header xác thực và bản thân khóa trước. 429 không nhất thiết là “hết tiền”, có thể chỉ là giới hạn tốc độ. 400 phần lớn là vấn đề thân yêu cầu; thông báo lỗi thường chỉ ra trường cụ thể.

8. An toàn khóa và cổng tương thích thay thế

An toàn khóa cần tối thiểu bốn việc: chỉ lưu trong biến môi trường hoặc dịch vụ quản lý khóa; tách khóa theo dự án; đặt cảnh báo mức dùng; luân chuyển định kỳ và thu hồi khóa của thành viên đã rời đi. Không được xuất hiện khóa dài hạn ở frontend, ứng dụng di động hay kho công khai.

Các đội trong nước nếu gặp vấn đề về mạng, thanh toán hoặc hóa đơn có thể dùng cổng cung cấp endpoint tương thích Anthropic thay cho địa chỉ chính thức. SDK chính thức thường chỉ cần đổi base_url và khóa:

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url="https://ai.zhongshangqihang.com",
)

resp = client.messages.create(
    model="Theo danh sách mô hình trên site",
    max_tokens=256,
    messages=[{"role": "user", "content": "Chỉ trả lời OK"}],
)
print(resp.content)

Nếu cổng chỉ cung cấp giao diện tương thích OpenAI, cần đổi cấu trúc yêu cầu hoặc thêm một lớp chuyển đổi, không thể chỉ thay base URL. Khi chọn cổng, xác nhận ba việc: có hỗ trợ giao thức gốc của Anthropic không, tên mô hình được ánh xạ thế nào, chính sách giới hạn tốc độ và nhật ký có minh bạch không.

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

Claude API và gói thành viên Claude trên web có phải một thứ?

Không. Bản web là gói đăng ký dành cho người dùng; API tính phí theo mức dùng. Hai bên có hệ thống tài khoản, hạn mức và điểm quản lý khác nhau. Khóa, hóa đơn và mức dùng của API được quản lý trong Anthropic Console.

Sau khi tạo API Key có còn xem được giá trị đầy đủ?

Phần lớn trường hợp chỉ hiển thị một lần khi tạo. Sau đó chỉ thấy tiền tố hoặc tên, vì vậy phải lưu ngay vào dịch vụ quản lý khóa; nếu mất, hãy thu hồi khóa cũ và tạo khóa mới.

Vì sao bắt buộc phải truyền max_tokens?

Messages API yêu cầu khai báo rõ giới hạn đầu ra của một lần gọi để kiểm soát độ dài sinh và tài nguyên. Bỏ qua sẽ trả về 400. Hãy đặt giá trị hợp lý theo nhiệm vụ, không nên kéo tối đa một cách máy móc.

429 là hết hạn mức hay đồng thời quá cao?

Cả hai đều có thể. Trước hết xem thân phản hồi và retry-after: xuất hiện dồn dập trong thời gian ngắn thường là vấn đề tốc độ hoặc đồng thời; xuất hiện liên tục kèm hạn mức bất thường thì kiểm tra gói và mức dùng. Cách xử lý gồm thử lại có lùi, giảm đồng thời và tách khóa.

Đội trong nước có nhất thiết phải dùng cổng?

Không nhất thiết. Đội có thể kết nối trực tiếp ổn định, hoàn tất thanh toán và đánh giá tuân thủ thì dùng trực tiếp đơn giản hơn. Khi cần thanh toán bằng nhân dân tệ, hóa đơn, đầu mối đa mô hình thống nhất hoặc tối ưu mạng, hãy đánh giá cổng và xác nhận chính sách dữ liệu và xử lý sự cố.

Bước tiếp theo

Trước hết hãy đăng ký ZSQH AI Gateway, dùng khóa thử nghiệm chạy thông yêu cầu tối thiểu tới /v1/messages, rồi mới tích hợp nghiệp vụ. Mô hình, ngữ cảnh và cách tính phí căn cứ theo bảng giá mô hình.

Đọc thêm: