2.3 Claude API Mechanics (6.8%)

Nắm chắc cơ chế Messages API: cấu trúc request, stop_reason, streaming, vision, thinking, caching, Batches và gọi qua nhà cung cấp cloud.

1. System prompt truyền qua tham số system riêng; messages chỉ chứa lượt user/assistant. API stateless — ứng dụng lưu và gửi lại toàn bộ lịch sử.
2. stop_reason: "max_tokens" = output bị cắt ngang — không coi là câu trả lời đầy đủ; tăng max_tokens hoặc yêu cầu ngắn hơn.
3. Message Batches: rẻ hơn 50%, đa số xong trong 1 giờ, hết hạn sau 24 giờ, kết quả giữ 29 ngày; ghép kết quả bằng custom_id (thứ tự không bảo đảm).
4. Cache khớp chính xác tiền tố theo thứ tự tools → system → messages: đổi thứ tự tool hay chèn timestamp ở đầu làm mất cache mọi request.
5. Truy cập dữ liệu: ảnh là image block, PDF là document block; nguồn có thể là base64, URL, hoặc file_id từ Files API (tải lên một lần, dùng nhiều lần — đỡ gửi lại byte mỗi lượt).
6. stop_reason: "pause_turn" = vòng lặp server tool chạm giới hạn lượt → gửi lại nguyên nội dung assistant để Claude làm tiếp. Client tool dừng bằng tool_use, không bao giờ pause_turn.
7. Stream có thể đã trả HTTP 200 rồi mới phát event: error (vd. overloaded_error) → xử lý lỗi ngay trong vòng đọc stream, không chỉ ở mã HTTP.
8. Claude 5+: thinking bật sẵn, display mặc định "omitted" (khối thinking rỗng) — muốn xem thì đặt "summarized". Token thinking vẫn tính như output và nằm trong max_tokens.