Bắt đầu với Claude Vision — Gửi hình ảnh qua API

Claude không chỉ hiểu văn bản — nó còn có khả năng nhìn và phân tích hình ảnh. Tính năng này gọi là Vision hay Multimodal, cho phép bạn gửi ảnh kèm theo câu hỏi và Claude sẽ trả lời dựa trên nội dung hình ảnh đó.

Bài viết này hướng dẫn bạn từ đầu: cách gửi hình ảnh qua API, các định dạng được hỗ trợ, giới hạn kích thước, và những ví dụ thực tế đơn giản nhất.

Claude Vision có thể làm gì?

Trước khi đi vào code, hãy hiểu Claude Vision có thể xử lý những gì:

• Mô tả hình ảnh — Cho Claude xem ảnh, nó sẽ kể lại nội dung chi tiết
• Trích xuất text (OCR) — Đọc chữ viết trong ảnh, kể cả chữ viết tay
• Phân tích biểu đồ — Đọc số liệu từ bar chart, line chart, pie chart
• Nhận diện đối tượng — Xác định vật thể, người, địa điểm trong ảnh
• So sánh hình ảnh — Tìm điểm giống và khác giữa nhiều ảnh
• Phân tích tài liệu — Đọc hóa đơn, hợp đồng, form scan

Hai cách gửi hình ảnh

API của Claude hỗ trợ hai phương thức để gửi hình ảnh:

1. Base64 encoding — Chuyển file ảnh thành chuỗi text, nhúng trực tiếp vào request
2. URL — Cung cấp link ảnh công khai, Claude tự fetch về

Mỗi cách có ưu và nhược điểm riêng — chúng ta sẽ xem cả hai.

Cách 1: Gửi ảnh bằng Base64

Base64 là cách phổ biến nhất khi bạn có file ảnh trên máy. Bạn đọc file, chuyển thành base64 string, rồi nhúng vào request.

Python — đọc file và gửi base64

import anthropic
import base64

# Đọc file ảnh và encode thành base64
with open("image.jpg", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/jpeg",
                        "data": image_data,
                    },
                },
                {
                    "type": "text",
                    "text": "Mo ta hinh anh nay cho toi."
                }
            ],
        }
    ],
)

print(message.content[0].text)

Lưu ý cấu trúc của content: đây là một list chứa các block, mỗi block có type là "image" hoặc "text". Bạn có thể kết hợp nhiều block theo thứ tự bất kỳ.

Các media_type được hỗ trợ

Claude hỗ trợ bốn định dạng ảnh phổ biến nhất:

Chú ý: PDF, TIFF, BMP không được hỗ trợ trực tiếp. Nếu bạn có PDF, cần chuyển từng trang thành ảnh PNG hoặc JPEG trước.

Cách 2: Gửi ảnh bằng URL

Nếu ảnh đã có sẵn trên internet với URL công khai, bạn không cần download về mà có thể gửi URL thẳng:

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/4/47/PNG_transparency_demonstration_1.png/280px-PNG_transparency_demonstration_1.png",
                    },
                },
                {
                    "type": "text",
                    "text": "Hinh anh nay mo ta gi?"
                }
            ],
        }
    ],
)

print(message.content[0].text)

URL phải là link trực tiếp đến file ảnh (kết thúc bằng .jpg, .png, v.v.), không phải trang web chứa ảnh. Ảnh phải publicly accessible — URL yêu cầu đăng nhập hoặc signed URL sẽ không hoạt động.

Giới hạn kích thước và số lượng

Claude có một số giới hạn quan trọng bạn cần biết:

Ảnh tính token như thế nào? Claude chuyển ảnh thành "tiles" 512x512 pixel trước khi xử lý. Một ảnh 1000x1000 tốn khoảng 1334 tokens. Ảnh lớn hơn tốn nhiều tokens hơn nhưng cũng cung cấp nhiều chi tiết hơn.

Ví dụ thực tế: Mô tả hình ảnh

Đây là script hoàn chỉnh để mô tả một ảnh từ file local:

import anthropic
import base64
import sys

def describe_image(image_path: str) -> str:
    """Mo ta noi dung cua mot file anh."""

    # Xac dinh media type tu extension
    ext = image_path.lower().split(".")[-1]
    media_types = {
        "jpg": "image/jpeg",
        "jpeg": "image/jpeg",
        "png": "image/png",
        "gif": "image/gif",
        "webp": "image/webp",
    }
    media_type = media_types.get(ext, "image/jpeg")

    # Doc va encode anh
    with open(image_path, "rb") as f:
        image_data = base64.standard_b64encode(f.read()).decode("utf-8")

    # Goi API
    client = anthropic.Anthropic()
    message = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=512,
        messages=[
            {
                "role": "user",
                "content": [
                    {
                        "type": "image",
                        "source": {
                            "type": "base64",
                            "media_type": media_type,
                            "data": image_data,
                        },
                    },
                    {
                        "type": "text",
                        "text": "Hay mo ta chi tiet noi dung cua hinh anh nay bang tieng Viet."
                    }
                ],
            }
        ],
    )
    return message.content[0].text

# Chay thu
if __name__ == "__main__":
    path = sys.argv[1] if len(sys.argv) > 1 else "test.jpg"
    print(describe_image(path))

Ví dụ: Trích xuất text từ ảnh (OCR đơn giản)

def extract_text_from_image(image_path: str) -> str:
    """Trich xuat van ban tu hinh anh."""
    with open(image_path, "rb") as f:
        image_data = base64.standard_b64encode(f.read()).decode("utf-8")

    client = anthropic.Anthropic()
    message = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=2048,
        messages=[
            {
                "role": "user",
                "content": [
                    {
                        "type": "image",
                        "source": {
                            "type": "base64",
                            "media_type": "image/jpeg",
                            "data": image_data,
                        },
                    },
                    {
                        "type": "text",
                        "text": "Hay trich xuat toan bo van ban trong hinh anh nay. Chi tra ve text, khong co nhan xet them."
                    }
                ],
            }
        ],
    )
    return message.content[0].text

Ví dụ: Phân tích biểu đồ

def analyze_chart(chart_image_path: str) -> dict:
    """Phan tich bieu do va trich xuat so lieu."""
    with open(chart_image_path, "rb") as f:
        image_data = base64.standard_b64encode(f.read()).decode("utf-8")

    client = anthropic.Anthropic()
    message = client.messages.create(
        model="claude-opus-4-5",
        max_tokens=1024,
        messages=[
            {
                "role": "user",
                "content": [
                    {
                        "type": "image",
                        "source": {
                            "type": "base64",
                            "media_type": "image/png",
                            "data": image_data,
                        },
                    },
                    {
                        "type": "text",
                        "text": "Phan tich bieu do nay:
1. Loai bieu do la gi?
2. Cac muc du lieu chinh?
3. Xu huong hoac insight quan trong nhat?"
                    }
                ],
            }
        ],
    )
    return message.content[0].text

Lỗi thường gặp khi mới bắt đầu

Lỗi 1: Sai media_type

Nếu bạn khai báo media_type: "image/jpeg" nhưng gửi file PNG, Claude sẽ báo lỗi hoặc phân tích sai. Luôn đảm bảo media_type khớp với định dạng thực tế của file.

Lỗi 2: Ảnh quá lớn

File ảnh 10MB sẽ bị reject. Trước khi gửi, resize ảnh xuống còn khoảng 1920x1080 hoặc nhỏ hơn — chất lượng phân tích không giảm đáng kể nhưng giảm được chi phí và tốc độ.

from PIL import Image
import io

def resize_image(image_path: str, max_size: int = 1920) -> bytes:
    """Thu nho anh neu qua lon."""
    with Image.open(image_path) as img:
        # Giu ty le aspect ratio
        img.thumbnail((max_size, max_size))
        buffer = io.BytesIO()
        img.save(buffer, format="JPEG", quality=85)
        return buffer.getvalue()

Lỗi 3: URL ảnh không public

URL từ Google Drive, Dropbox shared links thường không phải direct link. Dùng các hosting service như Imgur, Cloudinary, hoặc S3 public bucket.

Tổng kết

Bạn đã học được những điều cơ bản nhất về Claude Vision:

• Base64 — Dùng khi có file ảnh local, nhúng trực tiếp vào request
• URL — Dùng khi ảnh đã có sẵn trên internet với link public
• Định dạng hỗ trợ — JPEG, PNG, GIF, WebP
• Giới hạn — 5MB mỗi ảnh, tối đa 20 ảnh mỗi request

Bước tiếp theo: Đọc Best Practices cho Vision để biết cách đặt ảnh và viết prompt hiệu quả hơn, và xem OCR với Claude để ứng dụng vào bài toán thực tế.

Bài viết liên quan

• Multi-Modal RAG với LlamaIndex + Claude Vision
• Crop Tool — Cho Claude khả năng zoom vào chi tiết hình ảnh
• Best Practices cho Vision — Tối ưu hình ảnh gửi Claude
• Claude API — Authentication, Rate Limits và Error Handling
• Claude Phân tích Dữ liệu: Hướng dẫn Kết nối Công cụ