Files API

Files API memungkinkan Anda mengunggah dan mengelola file untuk digunakan dengan Claude API tanpa perlu mengunggah ulang konten pada setiap permintaan. Ini sangat berguna saat menggunakan alat eksekusi kode untuk menyediakan input (misalnya, dataset dan dokumen) lalu mengunduh output (misalnya, grafik). Anda dapat menjelajahi referensi API secara langsung, selain panduan ini.

Dukungan jenis file

Mereferensikan file_id dalam permintaan Messages didukung pada semua model yang mendukung jenis file tersebut. Gambar didukung pada semua model Claude saat ini. Untuk PDF dan jenis file lain dengan alat eksekusi kode, lihat halaman tertaut untuk dukungan model.

Cara kerja Files API

Files API menyediakan pendekatan buat-sekali, gunakan-berkali-kali untuk bekerja dengan file:

• Unggah file ke penyimpanan aman Anthropic dan terima file_id unik
• Unduh file yang dibuat oleh skills atau alat eksekusi kode
• Referensikan file dalam permintaan Messages menggunakan file_id alih-alih mengunggah ulang konten
• Kelola file Anda dengan operasi list, retrieve, dan delete

Cara menggunakan Files API

Mengunggah file

Unggah file untuk direferensikan dalam panggilan API mendatang:

uploaded = client.files.upload(
    file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
)
file_id = uploaded.id
print(file_id)

Respons dari pengunggahan file mencakup:

{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "type": "file",
  "filename": "document.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1024000,
  "created_at": "2025-01-01T00:00:00Z",
  "downloadable": false,
  "expires_at": null
}

downloadable bernilai false untuk file yang Anda unggah. Hanya file yang dibuat oleh skills atau alat eksekusi kode yang dapat diunduh. Lihat Mengunduh file.

Menggunakan file dalam pesan

Setelah diunggah, referensikan file dengan meneruskan id dari respons unggahan sebagai file_id:

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Please summarize this document for me."},
                {
                    "type": "document",
                    "source": {
                        "type": "file",
                        "file_id": file_id,
                    },
                },
            ],
        }
    ],
)
print(response)

Jenis file dan blok konten

Files API mendukung berbagai jenis file yang sesuai dengan berbagai jenis blok konten:

Blok dokumen

Untuk PDF dan file teks, gunakan blok konten document:

{
  "type": "document",
  "source": {
    "type": "file",
    "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
  },
  "title": "Document Title", // Optional
  "context": "Context about the document", // Optional
  "citations": { "enabled": true } // Optional, enables citations
}

Blok gambar

Untuk gambar, gunakan blok konten image:

{
  "type": "image",
  "source": {
    "type": "file",
    "file_id": "file_011CPMxVD3fHLUhvTqtsQA5w"
  }
}

Blok container upload

Untuk mengirim file ke alat eksekusi kode, gunakan blok konten container_upload:

{
  "type": "container_upload",
  "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
}

Bekerja dengan format file lain

Untuk jenis file yang tidak didukung oleh blok document (misalnya, .docx dan .xlsx), konversikan file ke teks biasa dan sertakan kontennya langsung dalam pesan Anda. File yang sudah berupa teks biasa, seperti file .csv dan .md, dapat dibaca dengan cara ini atau diunggah melalui Files API dengan jenis konten text/plain yang eksplisit. Untuk menganalisis dataset alih-alih membacanya sebagai teks, unggah dataset tersebut untuk alat eksekusi kode menggunakan blok container_upload.

Contoh berikut membaca file teks dan mengirim kontennya sebagai teks biasa:

client = anthropic.Anthropic()

# Baca file teks
with open("document.txt") as f:
    text_content = f.read()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": f"Here's the document content:\n\n{text_content}\n\nPlease summarize this document.",
                }
            ],
        }
    ],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

Mengelola file

Daftar file

Ambil daftar file yang telah Anda unggah. Endpoint ini menggunakan paginasi: setiap permintaan mengembalikan hingga limit file (20 secara default, dan maksimal 1.000), dan kursor next_page pada respons mengambil halaman berikutnya ketika diteruskan kembali sebagai parameter page. File diurutkan dari yang terbaru. Lihat referensi API List Files. SDK mengembalikan halaman pertama dan menyediakan helper paginasi otomatis. Contoh CLI membatasi jumlah total dengan --max-items:

client = anthropic.Anthropic()
files = client.files.list()
print(files)

Untuk memeriksa sekumpulan file yang sudah diketahui dalam satu permintaan alih-alih melakukan paginasi, teruskan hingga 100 ID file sebagai parameter query ids[]. Permintaan ids[] selalu mengembalikan satu halaman (next_page bernilai null), dan ID apa pun yang tidak merujuk ke file di workspace Anda akan dihilangkan secara diam-diam dari data; bandingkan ID yang dikembalikan dengan ID yang diminta untuk mendeteksi yang tidak ditemukan. ids[] tidak dapat digabungkan dengan page atau limit.

Mendapatkan metadata file

Ambil informasi tentang file tertentu:

file = client.files.retrieve_metadata(file_id)
print(file)

Menghapus file

Hapus file dari workspace Anda:

client.files.delete(file_id)

Mengunduh file

Unduh file yang dibuat oleh skills atau alat eksekusi kode. File yang Anda unggah tidak dapat diunduh. file_id dari file yang dihasilkan muncul dalam blok konten bash_code_execution_tool_result pada respons Messages yang membuatnya:

file_content = client.files.download(file_id)

file_content.write_to_file("downloaded_file.txt")

Di Claude API, file gambar, video, dan audio yang didukung yang dihasilkan Claude dengan alat eksekusi kode, termasuk file yang dibuat oleh skills, membawa C2PA Content Credentials yang ditandatangani saat Anda mengunduhnya. Lihat Content Credentials pada file yang dihasilkan untuk mengetahui isi kredensial tersebut dan cara memverifikasinya.

Penyimpanan dan batas file

Batas penyimpanan

• Ukuran file maksimum: 500 MB per file
• Total penyimpanan: 1 TB per organisasi

Siklus hidup file

• File dibatasi pada workspace tempat file tersebut diunggah. Permintaan apa pun dalam workspace yang sama dapat mereferensikannya; jangan pernah menerima ID file dari sumber tidak tepercaya (lihat peringatan akses workspace)
• File tidak dapat dimodifikasi atau diubah namanya setelah diunggah. Untuk mengubah konten file, unggah file baru dan hapus yang lama
• File tetap ada hingga Anda menghapusnya dengan endpoint DELETE /v1/files/{file_id} atau hingga mencapai expires_at
• File yang dihapus tidak dapat dipulihkan
• File tidak dapat diakses melalui API sesaat setelah penghapusan, tetapi mungkin masih ada dalam panggilan Messages API yang sedang aktif dan penggunaan alat terkait
• File yang dihapus pengguna akan dihapus sesuai dengan kebijakan retensi data Anthropic. Untuk kelayakan ZDR di semua fitur, lihat API dan retensi data

Kedaluwarsa file

Agar file kedaluwarsa secara otomatis, sertakan field form expires_in_seconds saat Anda mengunggahnya. Nilainya adalah bilangan bulat dalam detik antara 3.600 (1 jam) dan 7.776.000 (90 hari). Timestamp expires_at yang dihasilkan (RFC 3339) muncul pada setiap respons file dan bernilai null untuk file yang diunggah tanpa kedaluwarsa. Kedaluwarsa ditetapkan sekali saat unggah dan tidak dapat diubah.

Ketika file mencapai expires_at:

• Mengunduh kontennya (GET /v1/files/{file_id}/content) mengembalikan error 404
• Permintaan Messages yang mereferensikan file tersebut gagal sebelum inferensi
• Metadatanya (GET /v1/files/{file_id}) tetap dapat dibaca hingga 30 hari, dengan expires_at di masa lalu
• File tersebut tetap muncul dalam respons list selama jangka waktu itu; bandingkan expires_at dengan waktu saat ini untuk memfilter file yang kedaluwarsa

Menghapus file yang kedaluwarsa dengan DELETE /v1/files/{file_id} akan menghapus metadatanya segera alih-alih menunggu jangka waktu 30 hari berlalu.

Pencatatan audit

Jika organisasi Anda telah mengaktifkan Compliance API, Activity Feed-nya mencatat operasi Files API yang dilakukan dengan kunci API Claude atau dari Claude Console: setiap unggahan (POST /v1/files), unduhan konten (GET /v1/files/{file_id}/content), dan penghapusan (DELETE /v1/files/{file_id}) muncul sebagai aktivitas platform_file_uploaded, platform_file_content_downloaded, atau platform_file_deleted. Mendaftar file dan mengambil metadata file tidak dicatat. Operasi yang terjadi saat Compliance API nonaktif tidak dicatat dan tidak dapat dipulihkan kemudian, jadi siapkan Compliance API sebelum Anda mengandalkan jejak audit ini. Di Claude Platform on AWS, audit operasi file dengan data event AWS CloudTrail sebagai gantinya.

Migrasi dari files-api-2025-04-14

Files API telah keluar dari beta dan tidak memerlukan header beta. Migrasi dari files-api-2025-04-14 bersifat opsional: permintaan yang masih mengirimkannya tetap berfungsi dan tetap mengembalikan bentuk respons beta, sehingga integrasi yang ada tetap berfungsi hingga Anda mengubahnya. Menghapus header tersebut akan mengalihkan permintaan itu ke bentuk yang didokumentasikan di halaman ini:

Untuk bermigrasi:

1. Hapus header beta. Hilangkan anthropic-beta: files-api-2025-04-14 dari permintaan Anda. Di SDK, panggil client.files alih-alih client.beta.files; tetap menggunakan client.beta.files hanya berfungsi pada rilis SDK yang tidak lagi mengirim header tersebut. Rilis sebelumnya mengirimkannya dari client.beta.files bahkan tanpa argumen betas.
2. Perbarui paginasi. Ganti loop after_id/before_id dengan kursor page/next_page, atau gunakan helper paginasi otomatis SDK yang ditunjukkan di Mengelola file.
3. Baca expires_at. Field ini hanya muncul tanpa header; null berarti file tidak memiliki kedaluwarsa (lihat Kedaluwarsa file).

Namespace beta SDK

Mulai dari Python SDK 1.2.0, TypeScript SDK 0.122.0, Go SDK 1.68.0, Java SDK 2.59.0, Ruby SDK 1.67.0, dan C# SDK 12.44.0, client.beta.files tidak lagi mengirim files-api-2025-04-14 dan mengembalikan bentuk yang sama dengan client.files, dengan nama tipe berawalan Beta. Namespace ini menerima argumen betas untuk fitur Files yang masih dalam beta, seperti pemfilteran scope_id di bawah header beta Managed Agents. Rilis SDK sebelumnya memiliki tipe sesuai bentuk beta; jika Anda bergantung pada tipe tersebut, tetaplah pada rilis sebelumnya hingga Anda bermigrasi.

Permintaan yang membawa anthropic-beta: managed-agents-2026-04-01 tanpa files-api-2025-04-14 menerima bentuk di halaman ini dengan satu kelonggaran kompatibilitas pada GET /v1/files: before_id dan after_id masih diterima (tidak dapat digabungkan dengan page atau ids[]), dan respons list menyertakan has_more, first_id, dan last_id di samping next_page. Versi beta Managed Agents yang lebih baru menerima bentuk biasa.

Penanganan error

Error umum saat menggunakan Files API meliputi:

• File tidak ditemukan (404): file_id yang ditentukan tidak ada atau Anda tidak memiliki akses ke file tersebut
• Jenis file tidak valid (400): Jenis file tidak cocok dengan jenis blok konten (misalnya, menggunakan file gambar dalam blok dokumen)
• Tidak dapat diunduh (400): File yang Anda unggah memiliki "downloadable": false dan tidak dapat diunduh. Hanya file yang dibuat oleh skills atau alat eksekusi kode yang dapat diunduh
• Melebihi ukuran jendela konteks (400): File lebih besar dari ukuran "context window" (jendela konteks) (misalnya, menggunakan file teks biasa 500 MB dalam permintaan /v1/messages)
• Nama file tidak valid (400): Nama file tidak memenuhi persyaratan panjang (1-255 karakter) atau mengandung karakter terlarang (<, >, :, ", |, ?, *, \, /, atau karakter Unicode 0-31)
• File terlalu besar (413): File melebihi batas 500 MB
• Batas penyimpanan terlampaui (400): Organisasi Anda telah mencapai batas penyimpanan 1 TB

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "File `file_011CNha8iCJcU1wXNR6q4V8w` not found."
  },
  "request_id": "req_011CQFYcrRp7mCHLDsAYT8Qt"
}

Penggunaan dan penagihan

Operasi Files API gratis:

• Mengunggah file
• Mengunduh file
• Mendaftar file
• Mendapatkan metadata file
• Menghapus file

Konten file yang digunakan dalam permintaan Messages dikenai harga sebagai token input.

Batas laju

Panggilan API terkait file dibatasi hingga sekitar 500 permintaan per menit ("rate limit" atau batas laju). Untuk meminta batas yang lebih tinggi, hubungi tim penjualan.

Langkah selanjutnya

Compatibility