Claude Files API: Unggah Sekali, Pakai di Mana Saja (Panduan GA)

Claude Files API memungkinkan Anda mengunggah file satu kali ke https://api.anthropic.com/v1/files, mendapatkan kembali file_id, dan mereferensikan ID tersebut dalam permintaan Messages apa pun alih-alih mengirim ulang kontennya setiap kali. Per 20 Agustus 2026, API ini tersedia secara umum di Claude Platform: tanpa beta header, penyimpanan 1 TB per organisasi, dan batas laju lima kali lebih tinggi daripada beta. Anthropic mengumumkan perubahan ini dalam postingan production agents-nya, bersamaan dengan GA untuk computer use, browser tool, dan Skills API.

Panduan ini mencakup siklus hidup lengkap: mengunggah, mereferensikan file dalam pesan, mengunduh output yang dihasilkan, kedaluwarsa, model keamanan workspace, dan batas yang akan Anda temui di produksi. Karena setiap langkah di sini adalah panggilan HTTP, coding agent Anda dapat mengubah seluruh alur menjadi skenario pengujian Apidog CLI alih-alih tumpukan perintah curl sekali pakai.

Apa yang dilakukan Files API

Files API adalah lapisan penyimpanan sekali buat, pakai berkali-kali untuk Claude API. API ini menyelesaikan masalah biaya tertentu: jika aplikasi Anda mengajukan pertanyaan tentang PDF 40 halaman yang sama di ratusan permintaan, mengunggah ulang PDF tersebut di setiap permintaan membuang bandwidth dan memperumit kode klien Anda. Dengan Files API Anda:

• Unggah file ke penyimpanan Anthropic dan terima file_id unik
• Referensikan ID tersebut dalam permintaan Messages melalui blok konten
• Unduh file yang dihasilkan oleh skills atau code execution tool (bagan, spreadsheet, dek)
• Kelola semuanya dengan operasi list, retrieve-metadata, dan delete

Permukaan endpoint-nya kecil:

Semuanya bekerja dengan header standar x-api-key dan anthropic-version: 2023-06-01. Jika Anda baru mengenal Messages API itu sendiri, panduan Claude Opus 5 API kami membahas dasar-dasar autentikasi dan bentuk permintaan.

Apa yang berubah saat GA

Files API menghabiskan berbulan-bulan dalam beta di balik sebuah header. Rilis GA 20 Agustus 2026 mengubah empat hal yang penting untuk perencanaan produksi:

1. Tanpa beta header. Permintaan bekerja dengan header standar di Claude API.
2. Batas laju 5x lebih tinggi. Operasi file kini mengizinkan sekitar 500 permintaan per menit, dengan batas lebih tinggi tersedia melalui tim sales.
3. Penyimpanan 1 TB per organisasi, dengan batas 500 MB per file.
4. Cakupan platform yang lebih luas. Files API berjalan langsung di Claude API, di Claude Platform on AWS dalam beta, dan di Microsoft Foundry saat menggunakan deployment Hosted on Anthropic. API ini tidak tersedia di Amazon Bedrock atau Google Cloud Vertex AI, dan tidak memenuhi syarat untuk perjanjian zero-data-retention. Rencanakan dengan tepat jika Anda menerapkan kebijakan retensi yang ketat.

Mengunggah file

Unggahan adalah permintaan multipart form, bukan 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"

Responsnya memberi Anda semua yang diperlukan untuk mereferensikan file tersebut nanti:

{
  "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
}

Dua bidang perlu diperhatikan. downloadable bernilai false untuk apa pun yang Anda unggah; hanya file yang dihasilkan Claude melalui skills atau code execution yang dapat diunduh kembali. Dan expires_at bernilai null kecuali Anda menetapkan kedaluwarsa saat mengunggah (lebih lanjut di bawah).

Dalam pengujian Apidog CLI di bawah, langkah unggah menyimpan id sebagai variabel, sehingga setiap permintaan berikutnya mereferensikan {{claude_file_id}} alih-alih string yang di-hardcode.

Mereferensikan file dalam pesan

Setelah diunggah, file dimasukkan ke dalam permintaan Messages melalui salah satu dari tiga jenis blok konten, bergantung pada filenya:

Permintaan peringkasan PDF terlihat seperti ini:

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"}}
      ]
    }]
  }'

Blok document juga menerima bidang opsional title, context, dan citations, sehingga Anda dapat mengaktifkan output sitasi terhadap file yang diunggah. Untuk gambar, ganti jenis blok menjadi image dengan bentuk source yang sama. Untuk spreadsheet, CSV yang ingin Anda analisis alih-alih dibaca, atau format apa pun yang tidak diterima blok document, gunakan container_upload untuk menyerahkan file ke code execution tool.

Satu catatan format: .docx dan .xlsx tidak didukung langsung oleh blok document. Konversi file Word ke PDF untuk mempertahankan penguraian gambar dan sitasi, atau ekstrak teks biasa dan kirimkan secara inline.

Mengunduh file yang dihasilkan

Endpoint unduh ada untuk output, bukan input. Saat Claude membuat bagan dengan code execution atau menghasilkan spreadsheet melalui skill, responsnya menyertakan file_id di dalam blok bash_code_execution_tool_result. ID tersebut dapat diunduh:

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

Mencoba mengunduh file yang Anda unggah akan menghasilkan 400. Periksa flag downloadable di metadata sebelum menyusun logika retry di sekitarnya; ini menghemat tiket dukungan. Alur upload-in, generate-out ini adalah tulang punggung alur kerja Skills API yang baru saja GA, di mana skills menghasilkan dokumen Office yang Anda unduh melalui endpoint yang sama ini. Panduan kami tentang Claude Skills membahas apa itu skills dan bagaimana eksekusinya.

Kedaluwarsa dan siklus hidup file

File tetap ada sampai Anda menghapusnya atau hingga kedaluwarsa yang Anda tetapkan saat mengunggah:

• Berikan expires_in_seconds sebagai bidang form saat mengunggah. Rentang valid: 3.600 (1 jam) hingga 7.776.000 (90 hari). Nilai ini ditetapkan sekali dan tidak dapat diubah nanti.
• Setelah expires_at terlewati, unduhan konten mengembalikan 404 dan permintaan Messages apa pun yang mereferensikan file tersebut gagal sebelum inferensi.
• Metadata tetap dapat dibaca hingga 30 hari setelah kedaluwarsa, dan file yang kedaluwarsa masih muncul dalam respons list selama periode itu. Bandingkan expires_at dengan waktu saat ini ketika memfilter.
• Menghapus file akan menghapusnya segera dan tidak dapat dibatalkan. Konten yang kedaluwarsa dilepaskan dari kuota penyimpanan Anda tetapi mungkin disimpan sebentar untuk tinjauan keamanan, jadi kedaluwarsa adalah alat siklus hidup, bukan kontrol penghapusan yang terjamin.

Model keamanan: file dibatasi per workspace

Ini adalah sisi paling tajam di seluruh API. File yang diunggah dapat diakses oleh seluruh workspace Anda, bukan dibatasi untuk pengguna akhir, percakapan, atau sesi tertentu. Kunci API apa pun di workspace yang sama dapat membaca file apa pun yang diunggah di sana, dan semua kunci berbagi Default Workspace organisasi Anda kecuali Anda menetapkannya di tempat lain.

Aturan praktisnya:

• Jangan pernah menerima nilai file_id dari pengguna akhir. ID yang diberikan pengguna akan memungkinkan satu pengguna aplikasi Anda membaca unggahan pengguna lain. Perlakukan ID file sebagai referensi sisi server dan simpan pemetaan pengguna-ke-file di database Anda sendiri.
• Membangun multi-tenant? Satu workspace per tenant. Workspace adalah batas isolasi. Setiap organisasi mendapatkan hingga 100 workspace, dan tim account Anthropic dapat menaikkannya.

Jika Anda sudah melacak kunci API per tenant untuk atribusi biaya (topik yang kami bahas dalam cara memangkas tagihan Claude API Anda), tata letak workspace yang sama memberi Anda isolasi file secara gratis.

Batas dan penagihan

Angka yang perlu dijadikan acuan:

Penagihannya ramah: mengunggah, mengunduh, mendaftar, dan menghapus file semuanya gratis. Anda hanya membayar ketika konten file masuk ke permintaan Messages, di mana harganya dihitung sebagai token input biasa. PDF 100 halaman yang direferensikan dalam sepuluh permintaan memakan token input yang sama sepuluh kali; Files API menghemat bandwidth dan kompleksitas klien Anda, bukan pengeluaran token. Untuk menghemat dari sisi token, padukan referensi file dengan prompt caching.

Waspadai error ini: 413 ketika file melebihi 500 MB, 400 ketika organisasi Anda mencapai batas 1 TB, 400 ketika jenis file tidak cocok dengan blok kontennya (misalnya gambar dalam blok document), dan 404 untuk ID di luar workspace Anda.

Biarkan Claude Code menguji Files API dengan Apidog CLI

Files API adalah alur stateful multi-langkah, jadi layak mendapatkan tes regresi, bukan riwayat shell. Claude Code, atau coding agent apa pun, dapat membuat dan menjalankan tes tersebut melalui Apidog CLI. Siapkan sekali:

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 berasal dari Apidog di bawah Account Settings, API Access Token. Lalu beri agent satu 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.

Perintah yang dijalankannya, diverifikasi terhadap 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 mengulangi endpoint create untuk setiap endpoint, lalu menulis ekstraksi variabel dan assertion ke dalam skenario sebelum dijalankan. Mengganti file tes nanti berarti mengubah satu langkah unggah, bukan setiap permintaan. Minta juga mock untuk respons unggah (apidog mock create), dan tim frontend mendapatkan bentuk JSON sebelum proxy backend Anda ada. Baris apidog run yang sama dengan -r junit bisa langsung masuk ke CI; panduan Apidog CLI di Claude Code kami membahas penyiapan agent dari awal hingga akhir.

FAQ

Apakah saya masih memerlukan beta header? Tidak. Sejak GA 20 Agustus 2026, Files API bekerja di Claude API dengan header standar x-api-key dan anthropic-version. Jika SDK atau proxy Anda masih menyematkan beta header files yang lama, hapus saat Anda melakukan upgrade.

Bisakah saya memperbarui konten file? Tidak. File bersifat immutable setelah diunggah. Unggah file baru, arahkan referensi Anda ke ID baru, dan hapus yang lama.

Apakah Files API berfungsi di Bedrock atau Vertex AI? Tidak. API ini tersedia di Claude API, Claude Platform on AWS (beta), dan Microsoft Foundry dengan deployment Hosted on Anthropic. Di Bedrock dan Vertex Anda masih memerlukan konten base64 inline.

Apakah Files API sama dengan yang digunakan Skills API untuk output? Ya. Skills dan code execution tool menulis dokumen yang dihasilkan ke penyimpanan file yang sama, dan Anda mengunduhnya melalui GET /v1/files/{file_id}/content. Sisi Skills API dari alur kerja tersebut cocok dipadukan dengan pengujian otomatis.

Penutup

GA-nya Files API menghapus alasan terakhir untuk menjejalkan dokumen yang sama dalam base64 ke setiap permintaan. Unggah sekali, referensikan berdasarkan ID, tetapkan kedaluwarsa, dan simpan file tenant di workspace terpisah. Permukaan API-nya ada lima endpoint, dan semuanya dapat diuji dalam hitungan menit: suruh coding agent Anda menuliskan alurnya dengan Apidog CLI, rangkai file_id melalui variabel, dan masukkan seluruh siklus hidup ke CI sebelum pengguna Anda menemukan kasus tepi untuk Anda.