Cơ chế Messages API - hội thoại, streaming, ảnh, thinking, gọi theo lô

Gần như mọi thứ bạn làm với Claude đều đi qua một endpoint: POST /v1/messages. Hiểu một lần gọi gửi gì, nhận gì, và những biến thể của nó (streaming, ảnh, tool, theo lô), là nền cho cả phần còn lại của chứng chỉ.

Bài này giúp bạn trả lời: Messages API hoạt động thế nào, và với mỗi yêu cầu cụ thể thì gọi theo cách nào?

Ví dụ xuyên suốt: ứng dụng gợi ý món ăn

Một ứng dụng nấu ăn cho người dùng chụp ảnh tủ lạnh rồi hỏi "tối nay nấu được món gì?". Claude nhìn ảnh, gọi tool tim_cong_thuc để tra kho công thức của ứng dụng, rồi trả lời từng bước nấu. Người dùng hỏi tiếp được ("không có hành thì sao?").

Ngoài phần chat, mỗi đêm ứng dụng cần viết mô tả ngắn cho khoảng 5.000 công thức mới do người dùng đóng góp. Một đối tác lớn muốn chạy bản riêng của ứng dụng trên Google Cloud.

Một lần gọi: gửi gì, nhận gì

Yêu cầu gồm model, max_tokens, có thể có system, và messages là danh sách lượt user và assistant xen kẽ. Phản hồi là một đối tượng Message:

{
  "role": "assistant",
  "content": [{ "type": "text", "text": "Với trứng, cà chua và đậu phụ, bạn có thể..." }],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 1830, "output_tokens": 412 }
}

• content là danh sách khối: text, tool_use, thinking… chứ không phải một chuỗi.
• stop_reason cho biết vì sao dừng: end_turn (xong), max_tokens (hết số token cho phép, câu trả lời bị cắt), tool_use (Claude muốn gọi tool), refusal…
• usage cho số token vào và ra, dùng để tính tiền.

Messages API không giữ trạng thái (stateless): lần gọi nào bạn cũng phải gửi lại toàn bộ hội thoại. Lịch sử hội thoại nằm trong code và kho lưu trữ của bạn. Khi người dùng hỏi "không có hành thì sao?", ứng dụng gửi lại ảnh, câu hỏi đầu, câu trả lời của Claude, rồi mới tới câu hỏi mới.

Gửi lại nhiều thì tốn token. Prompt caching giúp phần đầu giống nhau giữa các lần gọi được đọc từ cache: thêm cache_control vào yêu cầu, lần sau cùng phần đầu đó thì token đọc từ cache tính giá thấp (thường bằng 0,1 giá đầu vào; Opus 5.5 và Sonnet 5.5 là 0,05). Cache tính theo cả tiền tố tools, system, messages theo đúng thứ tự đó, nên giữ phần đầu ổn định, đừng chèn nội dung thay đổi vào đầu.

Streaming: khi người dùng đang nhìn màn hình

Không streaming, người dùng nhìn màn hình trống tới khi Claude viết xong. Với streaming ("stream": true, hoặc client.messages.stream() trong SDK), API trả về dần qua server-sent events theo thứ tự:

1. message_start: đối tượng Message với content rỗng.
2. Với mỗi khối nội dung: content_block_start, nhiều content_block_delta, rồi content_block_stop.
3. Một hay nhiều message_delta (có stop_reason và số token cộng dồn).
4. message_stop.

Xen giữa có thể có ping, và có thể có sự kiện error giữa chừng, ví dụ overloaded_error lúc tải cao. Code đọc stream phải xử lý trường hợp đó.

Streaming còn có lý do thứ hai ngoài trải nghiệm: yêu cầu dài. Docs về lỗi khuyên dùng streaming hoặc Batch API cho yêu cầu dài, nhất là trên 10 phút, và tránh đặt max_tokens lớn mà không stream. SDK còn kiểm trước và báo lỗi nếu một yêu cầu không streaming có thể vượt 10 phút. Nếu bạn không cần xử lý từng mẩu, SDK có thể tự gom stream rồi trả về Message hoàn chỉnh (stream.get_final_message() trong Python).

Ảnh và file

Ảnh gửi trong khối image, với một trong ba nguồn:

Vài điều cần nhớ: trên Amazon Bedrock và Google Cloud bản Google quản lý hiện chỉ dùng được base64. Docs khuyên đặt ảnh trước câu hỏi, giống như đặt tài liệu dài trước câu hỏi. Một yêu cầu chứa được tới 600 ảnh nhưng giới hạn kích thước yêu cầu (128 MB trên Claude API, 20 MB trên Bedrock, 30 MB trên Google Cloud bản Google quản lý) có thể tới trước. File tải qua Files API được giữ tới khi bạn xoá hoặc hết hạn, nên không thuộc diện Zero Data Retention.

Tool và thinking trong cùng vòng lặp

Khi Claude cần tra công thức, phản hồi có stop_reason: "tool_use" và một khối tool_use. Ứng dụng chạy tool, gửi lại cả lượt assistant vừa nhận và một lượt user chứa khối tool_result, rồi Claude viết tiếp.

Từ Claude 5 trở đi, thinking (Claude suy nghĩ trước khi trả lời) đã bật sẵn ở chế độ adaptive, không cần cấu hình, và phần chữ của thinking mặc định bị ẩn. Khối thinking vẫn có trong phản hồi, kèm signature. Khi trả kết quả tool, bạn phải gửi lại các khối thinking của lượt assistant đó, đầy đủ và không sửa: Claude đang viết dở câu trả lời và cần lập luận trước đó. Khối thinking bị sửa sẽ bị từ chối với lỗi 400.

messages.append({"role": "assistant", "content": response.content})  # giữ nguyên cả khối thinking
messages.append({"role": "user", "content": [{"type": "tool_result", "tool_use_id": tu.id, "content": ket_qua}]})

Gọi tức thì hay theo lô

Việc viết mô tả cho 5.000 công thức mỗi đêm không có ai ngồi chờ. Đó là việc của Message Batches API:

Gọi Claude qua nền tảng cloud

Đề thi nhắc việc gọi Claude qua nhà cung cấp bên thứ ba (third-party vendors). Dạng yêu cầu gần như giống hệt, nhưng có vài chỗ khác:

Trong ví dụ, bản cho đối tác chạy trên Google Cloud: ảnh tủ lạnh vẫn gửi base64 như cũ nên không phải sửa, nhưng code tạo client và cách đặt tên model phải đổi. Giữ phần logic ứng dụng tách khỏi phần gọi API giúp việc này gọn.