Skip to main content
POST
Dùng POST /v1/messages để gửi yêu cầu Claude theo định dạng Anthropic Messages. Các ví dụ cấu hình Anthropic SDK chính thức với base URL của CometAPI và đọc API key của bạn từ $COMETAPI_KEY.
Để xem định nghĩa trường và các tùy chọn dành riêng cho model, hãy xem tài liệu chính thức Tài liệu tham khảo API Messages. Đối với các yêu cầu tương thích OpenAI, hãy xem Chat Completions.
Xác thực bằng x-api-key hoặc Authorization: Bearer. Anthropic SDK sử dụng x-api-key. Các ví dụ HTTP bao gồm anthropic-version: 2023-06-01.

Bắt đầu nhanh

Các ví dụ sau yêu cầu ba truy vấn tìm kiếm. Đặt $COMETAPI_KEY trước khi chạy chúng. Cài đặt anthropic cho Python hoặc @anthropic-ai/sdk cho JavaScript:
Phản hồi chứa một mảng content. Đọc các khối có typetext; các khối thinking và tool có thể xuất hiện trước văn bản.

Kiểm soát suy luận thích ứng

Đặt thinking.type thành adaptive và chọn một giá trị output_config.effort. Ví dụ sau sử dụng xhigh và đọc thông báo đã hoàn tất từ một luồng:
Quá trình suy luận góp phần vào giới hạn đầu ra max_tokens. Hãy chừa chỗ cho câu trả lời cuối cùng cũng như quá trình suy luận. Một phản hồi có thể chứa văn bản mà không có khối suy luận hiển thị. Giữ nguyên mọi khối suy luận được trả về trong lịch sử cuộc trò chuyện. Để biết cấu hình suy luận dành riêng cho từng model, hãy xem Suy luận. Các ví dụ bỏ qua temperature, top_ptop_k; hãy tham khảo tài liệu về tham số của model đã chọn trước khi thêm các điều khiển lấy mẫu.

Lưu đệm Prompt

Đặt một điểm ngắt bộ nhớ đệm trên tài liệu tham chiếu mà bạn tái sử dụng giữa các yêu cầu. Lưu tài liệu tham chiếu của bạn vào một tệp reference.txt mã hóa UTF-8 trước khi chạy ví dụ này. Hãy sử dụng một tiền tố đáp ứng yêu cầu của model đã chọn về độ dài tối thiểu có thể lưu vào bộ nhớ đệm:
Chạy lại yêu cầu với cùng model, văn bản tham chiếu và chế độ cài đặt suy luận. Kiểm tra các bộ đếm mức sử dụng để xác định liệu yêu cầu có tái sử dụng một tiền tố hay không:
  • cache_creation_input_tokens đếm số Token được ghi vào bộ nhớ đệm.
  • cache_read_input_tokens đếm số Token được đọc từ bộ nhớ đệm.
  • input_tokens đếm số Token đầu vào được xử lý ngoài các bộ đếm bộ nhớ đệm đó.
Trong các yêu cầu lặp lại, cache_read_input_tokens báo cáo số Token đầu vào được đọc từ bộ nhớ đệm. Ví dụ OpenAPI Prompt Cache chứa một tài liệu tham chiếu hư cấu hoàn chỉnh mà bạn có thể lưu dưới dạng reference.txt để thử ví dụ mẫu.

Truyền phản hồi theo luồng

Đặt stream: true để dùng Server-Sent Events. SDK hiển thị các đoạn văn bản khi chúng đến:
Một luồng thông điệp chứa message_start, các sự kiện khối nội dung, message_delta, và message_stop. Các khối nội dung có thể chứa văn bản, quá trình suy luận hoặc hoạt động của công cụ. Đối với khối văn bản, content_block_delta chứa một text_delta. Đọc thông tin sử dụng cuối cùng và lý do dừng từ message_delta.

Kiểm soát mức độ nỗ lực

Đặt output_config.effort để định hướng mức độ suy luận. Ví dụ này sử dụng low cho phần giải thích ngắn và chờ thông điệp được truyền theo luồng hoàn tất:
Hãy sử dụng tài liệu tham khảo chính thức về effort để chọn mức độ nỗ lực. Đặt riêng max_tokens để giới hạn độ dài đầu ra.

Sử dụng công cụ máy chủ

Các công cụ máy chủ thực thi trong quá trình gửi yêu cầu API và trả về các khối kết quả cùng với câu trả lời của Claude.
Tìm nạp một bài báo và yêu cầu Claude sử dụng tài liệu đã truy xuất trong câu trả lời của mình. Ví dụ này stream phản hồi và kiểm tra cả văn bản cuối cùng lẫn web_fetch_tool_result khối:
Phản hồi ghép một khối server_tool_use với một khối web_fetch_tool_result chứa tài liệu đã tìm nạp hoặc lỗi công cụ.

Trả về kết quả công cụ phía máy khách

Đối với công cụ phía máy khách, Claude trả về một khối tool_use. Hãy chạy hàm của ứng dụng bạn và gửi kết quả của hàm đó trong một khối tool_resulttool_use_id tương ứng. Giữ nguyên toàn bộ nội dung assistant giữa hai yêu cầu. Ví dụ này cung cấp một kết quả đơn hàng hư cấu và yêu cầu Claude sử dụng kết quả đó:

Ví dụ phản hồi

Một yêu cầu không dùng Streaming trả về một đối tượng message. Ví dụ sau hiển thị các trường text và usage cùng một mã định danh message minh họa:
Lý do dừng mô tả hành động tiếp theo. end_turn hoàn tất câu trả lời, max_tokens có nghĩa là đầu ra đã đạt giới hạn, còn tool_use yêu cầu kết quả từ một công cụ phía máy khách trả về. Với một lượt công cụ phía máy chủ trả về pause_turn, hãy tiếp tục với nội dung assistant được trả về mà không thay đổi.

Ủy quyền

x-api-key
string
header
bắt buộc

Your CometAPI key passed via the x-api-key header. Authorization: Bearer $COMETAPI_KEY is also supported.

Tiêu đề

anthropic-version
string
mặc định:2023-06-01

The Anthropic API version to use. Defaults to 2023-06-01.

Ví dụ:

"2023-06-01"

anthropic-beta
string

Comma-separated feature identifiers required by a specific beta API feature. Omit this header for the examples on this page.

Nội dung

application/json
model
string
mặc định:claude-opus-5
bắt buộc

The Claude model to use. See the Models page for available Claude model IDs.

Ví dụ:

"claude-opus-5"

messages
object[]
bắt buộc

Conversation history. Use user and assistant messages with text strings or content-block arrays. Return complete assistant content blocks when continuing a tool call.

max_tokens
integer
bắt buộc

The maximum number of tokens to generate. The model may stop before reaching this limit. When using thinking, the thinking tokens count towards this limit.

Phạm vi bắt buộc: x >= 1
Ví dụ:

1024

system

System prompt providing context and instructions to Claude. Can be a plain string or an array of content blocks (useful for prompt caching).

temperature
number

Sampling temperature. The examples omit sampling overrides.

Phạm vi bắt buộc: 0 <= x <= 1
top_p
number

Nucleus sampling threshold. The examples omit sampling overrides.

Phạm vi bắt buộc: 0 <= x <= 1
top_k
integer

Limits sampling to the k most likely tokens. The examples omit sampling overrides.

Phạm vi bắt buộc: x >= 0
stream
boolean
mặc định:false

If true, stream the response incrementally using Server-Sent Events (SSE). Events include message_start, content_block_start, content_block_delta, content_block_stop, message_delta, and message_stop.

stop_sequences
string[]

Custom strings that cause the model to stop generating when encountered. The stop sequence is not included in the response.

thinking
object

Thinking configuration. The adaptive example uses type adaptive and sets output_config.effort separately.

tools
object[]

Client tools define a name and input_schema. Server tools use a versioned type and name, such as the web_fetch and web_search examples on this page.

tool_choice
object

Controls how the model uses tools.

metadata
object

Request metadata for tracking and analytics.

output_config
object

Configuration for reasoning effort and structured output.

service_tier
enum<string>

The service tier to use. auto tries priority capacity first, standard_only uses only standard capacity.

Tùy chọn có sẵn:
auto,
standard_only

Phản hồi

Successful response. When stream is true, the response is a stream of SSE events.

id
string

Message identifier returned by the API.

type
enum<string>

Always message.

Tùy chọn có sẵn:
message
role
enum<string>

Always assistant.

Tùy chọn có sẵn:
assistant
content
object[]

The response content blocks. May include text, thinking, tool_use, and other block types.

model
string

Model ID reported by the response.

stop_reason
enum<string>

Why the model stopped generating. refusal can be returned as a successful HTTP response when the model declines a request.

Tùy chọn có sẵn:
end_turn,
max_tokens,
stop_sequence,
tool_use,
pause_turn,
refusal
stop_sequence
string | null

The stop sequence that caused the model to stop, if applicable.

usage
object

Token usage statistics.

Lần sửa đổi cuối 8 tháng 9, 2026