Files API của Claude: tải lên một lần, dùng file_id nhiều lần

Ứng dụng của bạn hỏi đáp trên cùng một file PDF 200 trang hàng chục lần một ngày, và lần nào cũng gửi lại nguyên file dạng base64. Vừa tốn băng thông vừa làm request cồng kềnh. Files API của Claude cho bạn tải file lên một lần, nhận file_id, rồi tham chiếu nó trong mọi request sau. Nó cũng là cách lấy về các file mà skill hay code execution tạo ra (biểu đồ, file Excel, slide).

Luồng sử dụng

uploaded = client.files.upload(
    file=("hop-dong.pdf", open("hop-dong.pdf", "rb"), "application/pdf"))

client.messages.create(
    model="claude-opus-5-5", max_tokens=1024,
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "Tóm tắt các điều khoản phạt."},
        {"type": "document", "source": {"type": "file", "file_id": uploaded.id}},
    ]}])

Files API đã ra khỏi beta, không cần beta header (header cũ files-api-2025-04-14 vẫn chạy nhưng trả định dạng cũ).

Loại file và khối nội dung

File .docx, .xlsx không dùng được trực tiếp trong khối document: chuyển sang văn bản, hoặc đổi .docx có ảnh sang PDF, hoặc đưa vào code execution qua container_upload.

Giới hạn và vòng đời

• Mỗi file tối đa 500 MB; tổng 1 TB mỗi tổ chức.
• File không sửa, không đổi tên được; muốn đổi nội dung thì tải file mới, xoá file cũ.
• File tồn tại tới khi bạn xoá, hoặc tới expires_at nếu đặt expires_in_seconds lúc tải (từ 1 giờ tới 90 ngày).
• Chỉ tải về được file do skill hoặc code execution tạo (downloadable: true); file bạn tự tải lên thì không.
• Tải lên, tải về, liệt kê, xoá đều miễn phí; nội dung file dùng trong request tính như input token. Giới hạn khoảng 500 request mỗi phút.

Rủi ro lớn nhất: phạm vi workspace

File không gắn với người dùng cuối, hội thoại hay phiên. Mọi API key có quyền vào workspace đều đọc được mọi file trong đó. Hệ quả:

• Không bao giờ nhận file_id từ người dùng hay nguồn không tin cậy: một ID do người dùng gửi có thể cho họ đọc file của người khác. Lưu ánh xạ người dùng ↔ file trong ứng dụng của bạn.
• Ứng dụng nhiều khách hàng: tài liệu khuyên mỗi tenant một workspace (tối đa 100 workspace mỗi tổ chức), dùng key giới hạn theo workspace.
• Không đủ điều kiện ZDR: file được giữ tới khi xoá hoặc hết hạn.

Áp dụng thế nào?

• Dev: Tải tài liệu dùng nhiều lần lên một lần, lưu file_id trong database cạnh bản ghi của bạn; đặt expires_in_seconds cho file tạm.
• Tech Lead: Thiết kế workspace theo tenant ngay từ đầu nếu xây sản phẩm nhiều khách hàng.
• PM: Kết hợp Files API với skill xlsx/pptx để có tính năng "xuất báo cáo" mà người dùng tải về được.