Hướng Dẫn Sử Dụng Messages API Của Claude

Bài viết này hướng dẫn các pattern phổ biến khi làm việc với Messages API của Claude — bao gồm gửi yêu cầu cơ bản, xây dựng hội thoại nhiều lượt, kỹ thuật prefill, và khả năng xử lý hình ảnh (vision). Nếu bạn muốn xem đầy đủ thông số API, hãy tham khảo bài hướng dẫn bắt đầu với Claude API.

Messages API là cổng giao tiếp chính để tương tác với các model Claude — từ Opus, Sonnet đến Haiku. Dù bạn đang xây dựng chatbot, ứng dụng phân tích văn bản, hay hệ thống AI agent phức tạp, hiểu rõ cách hoạt động của API này là bước đầu tiên không thể thiếu.

💡 Lưu ý: Tính năng này hỗ trợ Zero Data Retention (ZDR). Khi tổ chức của bạn có thỏa thuận ZDR, dữ liệu gửi qua API sẽ không được lưu trữ sau khi phản hồi được trả về.

Yêu cầu và phản hồi cơ bản

Dưới đây là cách gửi một yêu cầu đơn giản đến Messages API bằng các ngôn ngữ lập trình phổ biến. Bạn cần có API key từ Anthropic Console để bắt đầu.

Ví dụ với cURL

#!/bin/sh
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-4-6",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, Claude"}
    ]
}'

Ví dụ với Python

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)

Ví dụ với TypeScript

import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic();

const message = await anthropic.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }]
});
console.log(message);

Phản hồi mẫu (JSON)

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claude-opus-4-6",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

Một số trường quan trọng trong phản hồi:

• stop_reason: Lý do Claude dừng phản hồi — end_turn nghĩa là Claude đã hoàn thành câu trả lời, max_tokens nghĩa là đã đạt giới hạn token tối đa.
• usage: Số token đã sử dụng — giúp bạn theo dõi chi phí API. input_tokens là số token đầu vào, output_tokens là số token đầu ra.

Hội thoại nhiều lượt (Multi-turn Conversation)

Messages API hoạt động theo cơ chế stateless — nghĩa là API không lưu trạng thái giữa các lần gọi. Mỗi lần gửi request, bạn cần đính kèm toàn bộ lịch sử hội thoại. Đây là cách bạn xây dựng cuộc trò chuyện liên tục với Claude.

Điểm đặc biệt: các lượt trước trong hội thoại không nhất thiết phải đến từ Claude. Bạn có thể tạo tin nhắn assistant giả lập (synthetic messages) để thiết lập ngữ cảnh ban đầu cho cuộc hội thoại.

Ví dụ hội thoại nhiều lượt với Python

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"},
        {"role": "assistant", "content": "Hello!"},
        {"role": "user", "content": "Can you describe LLMs to me?"},
    ],
)
print(message)

Ví dụ với TypeScript

import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic();

await anthropic.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 1024,
  messages: [
    { role: "user", content: "Hello, Claude" },
    { role: "assistant", content: "Hello!" },
    { role: "user", content: "Can you describe LLMs to me?" }
  ]
});

Mẹo cho developer Việt Nam: Khi xây dựng chatbot, hãy lưu lại mảng messages trong database hoặc session storage. Mỗi khi người dùng gửi tin nhắn mới, bạn thêm tin nhắn đó vào mảng rồi gửi toàn bộ mảng đến API. Đừng quên giới hạn số lượng tin nhắn để kiểm soát chi phí token.

Điền trước phản hồi của Claude (Prefill)

Bạn có thể điền trước một phần phản hồi của Claude bằng cách đặt nội dung trong tin nhắn assistant ở vị trí cuối cùng của danh sách messages. Kỹ thuật này rất hữu ích để kiểm soát định dạng output của Claude.

Ví dụ dưới đây sử dụng "max_tokens": 1 để lấy đúng một câu trả lời trắc nghiệm từ Claude:

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-6",
    max_tokens=1,
    messages=[
        {
            "role": "user",
            "content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae",
        },
        {"role": "assistant", "content": "The answer is ("},
    ],
)
print(message)
# Output: "C"

⚠️ Lưu ý quan trọng: Tính năng prefill đã bị deprecated (ngừng hỗ trợ) trên Claude Opus 4.6, Claude Sonnet 4.6, và Claude Sonnet 4.5. Thay vào đó, hãy sử dụng Structured Outputs hoặc chỉ dẫn trong system prompt để kiểm soát output.

Xử lý hình ảnh với Vision

Claude có khả năng đọc cả text và hình ảnh trong request. Hình ảnh có thể được gửi bằng 3 cách:

• base64: Mã hóa hình ảnh thành chuỗi base64 và gửi trực tiếp trong request
• url: Cung cấp URL công khai của hình ảnh
• file: Tham chiếu đến hình ảnh đã upload qua Files API

Các định dạng hỗ trợ: image/jpeg, image/png, image/gif, và image/webp.

Ví dụ gửi hình ảnh bằng URL (Python)

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message)

Ví dụ gửi hình ảnh bằng Base64 (Python)

import anthropic
import base64
import httpx

image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image_data = base64.standard_b64encode(httpx.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/jpeg",
                        "data": image_data,
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message)

Ứng dụng thực tế cho doanh nghiệp Việt: Tính năng Vision rất hữu ích cho việc đọc hóa đơn, trích xuất dữ liệu từ ảnh sản phẩm, hoặc phân tích biểu đồ tài chính. Ví dụ, bạn có thể chụp ảnh hóa đơn và nhờ Claude trích xuất thông tin tự động.

Sử dụng Tool Use và Computer Use

Ngoài nhắn tin cơ bản, Messages API còn hỗ trợ các tính năng nâng cao:

• Tool Use: Cho phép Claude gọi các công cụ bên ngoài (API, database, calculator...) để thực hiện tác vụ phức tạp. Xem thêm tại trang Claude Anthropic trên Agentwork.vn.
• Computer Use: Cho phép Claude điều khiển môi trường desktop — click, gõ phím, chụp ảnh màn hình.
• Structured Outputs: Đảm bảo output ở định dạng JSON chính xác theo schema bạn định nghĩa.

Để tìm hiểu chi tiết về từng tính năng, hãy theo dõi các bài hướng dẫn tiếp theo trên Agentwork.vn.