Claude Files API: Tải lên một lần, tham chiếu mọi nơi (Hướng dẫn GA)

Files API của Claude cho phép bạn tải một tệp lên https://api.anthropic.com/v1/files một lần, nhận lại file_id, và tham chiếu ID đó trong bất kỳ yêu cầu Messages nào thay vì gửi lại nội dung mỗi lần. Kể từ ngày 20 tháng 8 năm 2026, nó đã chính thức khả dụng (GA) trên Claude Platform: không cần beta header, 1 TB dung lượng lưu trữ cho mỗi tổ chức, và giới hạn tốc độ cao gấp năm lần so với bản beta. Anthropic đã công bố thay đổi này trong bài viết về production agents, cùng với việc GA cho computer use, công cụ trình duyệt và Skills API.

Hướng dẫn này bao quát toàn bộ vòng đời: tải lên, tham chiếu tệp trong messages, tải xuống các output được tạo ra, thời hạn hết hạn, mô hình bảo mật theo workspace, và những giới hạn bạn sẽ gặp trong môi trường production. Vì mọi bước ở đây đều là một lệnh gọi HTTP, coding agent của bạn có thể biến toàn bộ luồng này thành một kịch bản kiểm thử Apidog CLI thay vì một đống lệnh curl rời rạc.

Files API làm được gì

Files API là một lớp lưu trữ kiểu "tạo một lần, dùng nhiều lần" cho Claude API. Nó giải quyết một vấn đề chi phí cụ thể: nếu ứng dụng của bạn đặt câu hỏi về cùng một tệp PDF 40 trang qua hàng trăm yêu cầu, việc tải lại tệp PDF đó trong mỗi yêu cầu sẽ lãng phí băng thông và làm phức tạp code phía client. Với Files API bạn có thể:

• Tải lên một tệp vào kho lưu trữ của Anthropic và nhận về một file_id duy nhất
• Tham chiếu ID đó trong các yêu cầu Messages thông qua một content block
• Tải xuống những tệp do skills hoặc công cụ thực thi code tạo ra (biểu đồ, bảng tính, slide)
• Quản lý mọi thứ bằng các thao tác list, retrieve-metadata và delete

Bề mặt endpoint khá nhỏ gọn:

Tất cả đều hoạt động với các header chuẩn x-api-key và anthropic-version: 2023-06-01. Nếu bạn mới làm quen với chính Messages API, hướng dẫn Claude Opus 5 API của chúng tôi có đề cập những kiến thức cơ bản về xác thực và cấu trúc yêu cầu.

Những gì đã thay đổi khi GA

Files API đã ở trạng thái beta sau một header trong nhiều tháng. Bản GA ngày 20 tháng 8 năm 2026 đã thay đổi bốn điều quan trọng cho việc lập kế hoạch production:

1. Không cần beta header. Các yêu cầu hoạt động với header chuẩn trên Claude API.
2. Giới hạn tốc độ cao gấp 5 lần. Các thao tác tệp giờ đây cho phép khoảng 500 yêu cầu mỗi phút, với giới hạn cao hơn có thể thương lượng qua đội ngũ bán hàng.
3. 1 TB dung lượng lưu trữ cho mỗi tổ chức, với giới hạn 500 MB cho mỗi tệp.
4. Phạm vi nền tảng rộng hơn. Files API chạy trực tiếp trên Claude API, trên Claude Platform on AWS ở dạng beta, và trên Microsoft Foundry khi dùng triển khai Hosted on Anthropic. Nó không khả dụng trên Amazon Bedrock hay Google Cloud Vertex AI, và không đủ điều kiện cho các thỏa thuận zero-data-retention. Hãy lập kế hoạch cho phù hợp nếu bạn đang áp dụng chính sách lưu trữ nghiêm ngặt.

Tải một tệp lên

Việc tải lên là các yêu cầu multipart form, không phải JSON:

curl -X POST https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -F "file=@/path/to/report.pdf"

Phản hồi sẽ cung cấp cho bạn mọi thứ cần thiết để tham chiếu tệp sau này:

{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "type": "file",
  "filename": "report.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1024000,
  "created_at": "2026-08-24T00:00:00Z",
  "downloadable": false,
  "expires_at": null
}

Có hai trường đáng chú ý. downloadable là false đối với mọi thứ bạn tải lên; chỉ những tệp do Claude tạo ra thông qua skills hoặc thực thi code mới có thể được tải ngược trở lại. Và expires_at là null trừ khi bạn đặt thời hạn hết hạn tại thời điểm tải lên (sẽ nói thêm ở phần dưới).

Trong bài kiểm thử Apidog CLI ở phần dưới, bước tải lên sẽ lưu id thành một biến, để mọi yêu cầu phía sau đều tham chiếu {{claude_file_id}} thay vì một chuỗi được hardcode.

Tham chiếu tệp trong messages

Sau khi tải lên, tệp được đưa vào một yêu cầu Messages thông qua một trong ba loại content block, tùy theo loại tệp:

Một yêu cầu tóm tắt PDF trông như thế này:

curl -X POST https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 1024,
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Summarize this document."},
        {"type": "document", "source": {"type": "file", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"}}
      ]
    }]
  }'

Block document cũng chấp nhận các trường tùy chọn title, context và citations, để bạn có thể bật tính năng xuất trích dẫn dựa trên tệp đã tải lên. Với hình ảnh, hãy đổi loại block thành image với cùng cấu trúc source. Với bảng tính, các tệp CSV mà bạn muốn phân tích thay vì chỉ đọc, hoặc bất kỳ định dạng nào mà block document không nhận, hãy dùng container_upload để giao tệp cho công cụ thực thi code.

Một lưu ý về định dạng: .docx và .xlsx không được block document hỗ trợ trực tiếp. Hãy chuyển đổi tệp Word sang PDF để giữ khả năng phân tích hình ảnh và trích dẫn, hoặc trích xuất văn bản thuần rồi gửi trực tiếp.

Tải xuống các tệp được tạo ra

Endpoint tải xuống tồn tại cho output, không phải cho input. Khi Claude tạo một biểu đồ bằng thực thi code hoặc tạo một bảng tính thông qua một skill, phản hồi sẽ bao gồm một file_id bên trong block bash_code_execution_tool_result. ID đó có thể tải xuống được:

curl "https://api.anthropic.com/v1/files/$FILE_ID/content" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  --output chart.png

Cố gắng tải xuống một tệp bạn đã tải lên sẽ trả về lỗi 400. Hãy kiểm tra cờ downloadable trong metadata trước khi viết logic retry xung quanh việc này; nó giúp bạn tiết kiệm một ticket hỗ trợ. Vòng lặp tải lên vào, tạo ra output này là xương sống của quy trình Skills API vừa được GA, nơi các skill tạo ra tài liệu Office mà bạn tải xuống thông qua chính endpoint này. Hướng dẫn của chúng tôi về Claude Skills đề cập skills là gì và cách chúng thực thi.

Thời hạn hết hạn và vòng đời của tệp

Các tệp tồn tại cho đến khi bạn xóa chúng hoặc cho đến khi hết thời hạn bạn đặt lúc tải lên:

• Truyền expires_in_seconds như một form field khi tải lên. Phạm vi hợp lệ: 3.600 (1 giờ) đến 7.776.000 (90 ngày). Nó được đặt một lần và không thể thay đổi sau đó.
• Sau khi expires_at trôi qua, việc tải nội dung xuống sẽ trả về 404 và mọi yêu cầu Messages tham chiếu tệp đó đều thất bại trước khi suy luận diễn ra.
• Metadata vẫn có thể đọc được trong tối đa 30 ngày sau khi hết hạn, và các tệp đã hết hạn vẫn xuất hiện trong phản hồi list trong khoảng thời gian đó. Hãy so sánh expires_at với thời điểm hiện tại khi lọc.
• Xóa một tệp sẽ loại bỏ nó ngay lập tức và không thể hoàn tác. Nội dung đã hết hạn sẽ được giải phóng khỏi hạn mức lưu trữ của bạn nhưng có thể được giữ lại trong thời gian ngắn để rà soát an toàn, vì vậy thời hạn hết hạn là một công cụ quản lý vòng đời, không phải một cơ chế đảm bảo xóa.

Mô hình bảo mật: các tệp thuộc phạm vi workspace

Đây là điểm nhức nhối nhất trong toàn bộ API. Các tệp đã tải lên có thể được truy cập bởi toàn bộ workspace của bạn, chứ không bị giới hạn theo người dùng cuối, cuộc hội thoại hay phiên làm việc. Bất kỳ API key nào trong cùng workspace đều có thể đọc bất kỳ tệp nào được tải lên ở đó, và tất cả các key đều dùng chung Default Workspace của tổ chức bạn trừ khi bạn gán chúng ở nơi khác.

Các nguyên tắc thực tế:

• Tuyệt đối không nhận giá trị file_id từ người dùng cuối. Một ID do người dùng cung cấp sẽ cho phép một người dùng của ứng dụng bạn đọc được tệp tải lên của người dùng khác. Hãy coi file ID là tham chiếu phía server và lưu ánh xạ người dùng – tệp trong cơ sở dữ liệu của riêng bạn.
• Xây dựng multi-tenant? Một workspace cho mỗi tenant. Workspace chính là ranh giới cô lập. Mỗi tổ chức có tối đa 100 workspace, và đội ngũ account của Anthropic có thể nâng con số đó.

Nếu bạn đã đang theo dõi API key theo từng tenant để phân bổ chi phí (một chủ đề chúng tôi đào sâu trong cách cắt giảm hóa đơn Claude API), thì cùng cách bố trí workspace đó cũng cho bạn khả năng cô lập tệp miễn phí.

Giới hạn và thanh toán

Những con số cần ghi nhớ:

Việc thanh toán khá thân thiện: tải lên, tải xuống, liệt kê và xóa tệp đều miễn phí. Bạn chỉ trả tiền khi nội dung tệp đi vào một yêu cầu Messages, lúc đó nó được tính giá như input token thông thường. Một tệp PDF 100 trang được tham chiếu trong mười yêu cầu sẽ tốn cùng lượng input token mười lần; Files API giúp bạn tiết kiệm băng thông và độ phức tạp phía client, chứ không phải chi phí token. Để tiết kiệm về phía token, hãy kết hợp tham chiếu tệp với prompt caching.

Hãy chú ý những lỗi sau: 413 khi tệp vượt quá 500 MB, 400 khi tổ chức của bạn chạm mức trần 1 TB, 400 khi loại tệp không khớp với content block của nó (ví dụ một hình ảnh trong block document), và 404 đối với các ID nằm ngoài workspace của bạn.

Để Claude Code kiểm thử Files API với Apidog CLI

Files API là một luồng có trạng thái, gồm nhiều bước, nên nó xứng đáng có một bài kiểm thử hồi quy, chứ không phải chỉ nằm trong lịch sử shell. Claude Code, hay bất kỳ coding agent nào, đều có thể xây dựng và chạy bài kiểm thử đó thông qua Apidog CLI. Thiết lập một lần:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

Token lấy từ Apidog trong Account Settings, API Access Token. Sau đó đưa cho agent một prompt:

Use Apidog CLI on project <id>. Add the Files API endpoints (upload, list,
metadata, download, delete) and POST /v1/messages, with x-api-key from
{{ANTHROPIC_API_KEY}} and the anthropic-version header. Build a test scenario:
upload with expires_in_seconds=3600 and assert expires_at is set, save the id
as claude_file_id, reference it in a Messages call and assert 200, delete it,
then assert the metadata call returns 404. Run it and summarize any failures.

Các lệnh nó chạy, đã đối chiếu với Apidog CLI 2.2.7:

apidog cli-schema get endpoint-create
apidog endpoint create --project <id> --file files-upload.json
apidog test-scenario create --project <id> --name "Files API lifecycle" --priority 1
apidog test-scenario import-steps <scenarioId> --project <id> --source endpoint \
  --ids <uploadId>,<messagesId>,<deleteId>,<metadataId> --sync manual
apidog cli-schema validate test-scenario-update --file lifecycle.json
apidog test-scenario update <scenarioId> --project <id> --file lifecycle.json
apidog run -t <scenarioId> --project <id> -e <envId> \
  --env-var "ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY" -r cli,json

Agent sẽ lặp lại endpoint create cho từng endpoint, rồi viết phần trích xuất biến và các assertion vào kịch bản trước khi chạy. Việc đổi tệp kiểm thử về sau chỉ có nghĩa là thay đổi một bước tải lên, chứ không phải mọi yêu cầu. Hãy yêu cầu thêm một mock cho phản hồi tải lên (apidog mock create), và đội frontend sẽ có được cấu trúc JSON trước cả khi backend proxy của bạn tồn tại. Cùng dòng apidog run đó với -r junit sẽ đưa vào CI; hướng dẫn Apidog CLI trong Claude Code của chúng tôi bao quát toàn bộ việc thiết lập agent từ đầu đến cuối.

Câu hỏi thường gặp

Tôi có còn cần beta header không? Không. Kể từ bản GA ngày 20 tháng 8 năm 2026, Files API hoạt động trên Claude API với các header chuẩn x-api-key và anthropic-version. Nếu SDK hoặc proxy của bạn vẫn ghim beta header files cũ, hãy gỡ nó khi nâng cấp.

Tôi có thể cập nhật nội dung của một tệp không? Không. Các tệp là bất biến sau khi tải lên. Hãy tải lên một tệp mới, trỏ các tham chiếu của bạn sang ID mới, và xóa tệp cũ.

Files API có hoạt động trên Bedrock hay Vertex AI không? Không. Nó có trên Claude API, Claude Platform on AWS (beta), và Microsoft Foundry với triển khai Hosted on Anthropic. Trên Bedrock và Vertex, bạn vẫn cần nội dung base64 gửi trực tiếp.

Files API có phải là thứ mà Skills API dùng cho các output không? Đúng vậy. Skills và công cụ thực thi code ghi các tài liệu chúng tạo ra vào cùng kho tệp đó, và bạn tải chúng xuống thông qua GET /v1/files/{file_id}/content. Phía Skills API của quy trình đó rất hợp để kết hợp với kiểm thử tự động.

Tổng kết

Việc Files API chuyển sang GA đã loại bỏ lý do cuối cùng để nhồi base64 cùng một tài liệu vào mọi yêu cầu. Tải lên một lần, tham chiếu bằng ID, đặt thời hạn hết hạn, và giữ tệp của từng tenant trong các workspace riêng biệt. Bề mặt API chỉ có năm endpoint, và mỗi cái đều có thể kiểm thử trong vài phút: hãy để coding agent của bạn lập trình luồng này bằng Apidog CLI, nối file_id qua một biến, và đưa toàn bộ vòng đời vào CI trước khi người dùng của bạn tìm ra các trường hợp biên thay bạn.