Files API

Files API memungkinkan Anda mengunggah dan mengelola file untuk digunakan dengan Claude API tanpa perlu mengunggah ulang konten dengan setiap permintaan. Ini sangat berguna saat menggunakan alat eksekusi kode untuk menyediakan input (misalnya dataset dan dokumen) dan kemudian mengunduh output (misalnya bagan). Anda juga dapat menggunakan Files API untuk menghindari harus terus mengunggah ulang dokumen dan gambar yang sering digunakan di seluruh panggilan API. Anda dapat menjelajahi referensi API secara langsung, selain panduan ini.

Files API sedang dalam beta. Hubungi kami melalui formulir umpan balik untuk berbagi pengalaman Anda dengan Files API.

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

Model yang didukung

Mereferensikan file_id dalam permintaan Messages didukung di semua model yang mendukung jenis file yang diberikan. Misalnya, gambar didukung di semua model Claude 3+, PDF di semua model Claude 3.5+, dan berbagai jenis file lainnya untuk alat eksekusi kode di Claude Haiku 4.5 plus semua model Claude 3.7+.

Files API saat ini tidak didukung di Amazon Bedrock atau Google Vertex AI.

Cara kerja Files API

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

Unggah file ke penyimpanan aman Anthropic dan terima file_id unik
Unduh file yang dibuat dari skill atau alat eksekusi kode
Referensikan file dalam permintaan Messages menggunakan file_id alih-alih mengunggah ulang konten
Kelola file Anda dengan operasi daftar, ambil, dan hapus

Cara menggunakan Files API

Untuk menggunakan Files API, Anda perlu menyertakan header fitur beta: anthropic-beta: files-api-2025-04-14.

Mengunggah file

Unggah file untuk direferensikan dalam panggilan API di masa depan:

Respons dari mengunggah file akan mencakup:

Output

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

Menggunakan file dalam pesan

Setelah diunggah, referensikan file menggunakan file_id-nya:

Jenis file dan blok konten

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

Jenis File	Tipe MIME	Jenis Blok Konten	Kasus Penggunaan
PDF	`application/pdf`	`document`	Analisis teks, pemrosesan dokumen
Teks biasa	`text/plain`	`document`	Analisis teks, pemrosesan
Gambar	`image/jpeg`, `image/png`, `image/gif`, `image/webp`	`image`	Analisis gambar, tugas visual
Dataset, lainnya

Bekerja dengan format file lainnya

Untuk jenis file yang tidak didukung sebagai blok document (.csv, .txt, .md, .docx, .xlsx), konversi file ke teks biasa, dan sertakan konten langsung dalam pesan Anda:

Untuk file .docx yang berisi gambar, konversi ke format PDF terlebih dahulu, kemudian gunakan dukungan PDF untuk memanfaatkan penguraian gambar bawaan. Ini memungkinkan penggunaan kutipan dari dokumen PDF.

Blok dokumen

Untuk PDF dan file teks, gunakan blok konten document:

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

Blok gambar

Untuk gambar, gunakan blok konten image:

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

Mengelola file

Daftar file

Ambil daftar file yang diunggah:

Dapatkan metadata file

Ambil informasi tentang file tertentu:

Hapus file

Hapus file dari ruang kerja Anda:

Mengunduh file

Unduh file yang telah dibuat oleh skill atau alat eksekusi kode:

Anda hanya dapat mengunduh file yang dibuat oleh skill atau alat eksekusi kode. File yang Anda unggah tidak dapat diunduh.

Penyimpanan file dan batas

Batas penyimpanan

Ukuran file maksimal: 500 MB per file
Total penyimpanan: 500 GB per organisasi

Siklus hidup file

File dibatasi pada ruang kerja kunci API. Kunci API lain dapat menggunakan file yang dibuat oleh kunci API lain apa pun yang terkait dengan ruang kerja yang sama
File bertahan sampai Anda menghapusnya
File yang dihapus tidak dapat dipulihkan
File tidak dapat diakses melalui API segera setelah penghapusan, tetapi mungkin tetap ada dalam panggilan API Messages aktif dan penggunaan alat terkait
File yang dihapus pengguna akan dihapus sesuai dengan kebijakan retensi data Anthropic.

Retensi data

File yang diunggah melalui Files API disimpan sampai dihapus secara eksplisit menggunakan endpoint DELETE /v1/files/{file_id}. File disimpan untuk digunakan kembali di seluruh permintaan API.

Untuk kelayakan ZDR di semua fitur, lihat API dan retensi data.

Penanganan kesalahan

Kesalahan 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)
Melebihi ukuran jendela konteks (400): File lebih besar dari ukuran jendela konteks (misalnya menggunakan file plaintext 500 MB dalam permintaan /v1/messages)
Nama file tidak valid (400): Nama file tidak memenuhi persyaratan panjang (1-255 karakter) atau berisi karakter terlarang (<, >, :, ", |, ?, *, \, /, atau karakter unicode 0-31)
File melebihi batas 500 MB

Output

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "File not found: file_011CNha8iCJcU1wXNR6q4V8w"
  }
}

Penggunaan dan penagihan

Operasi File API gratis:

Mengunggah file
Mengunduh file
Mendaftar file
Mendapatkan metadata file
Menghapus file

Konten file yang digunakan dalam permintaan Messages ditagih sebagai token input. Anda hanya dapat mengunduh file yang dibuat oleh skill atau alat eksekusi kode.

Batas laju

Selama periode beta:

Panggilan API terkait file dibatasi hingga sekitar 100 permintaan per menit
Hubungi kami jika Anda memerlukan batas yang lebih tinggi untuk kasus penggunaan Anda

response = client.beta.messages.create(
    model="claude-opus-4-6",
    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,
                    },
                },
            ],
        }
    ],
    betas=["files-api-2025-04-14"],
)
print(response)

import pandas as pd
# ...
# Contoh: Membaca file CSV
df = pd.read_csv("data.csv")
csv_content = df.to_string()

# Kirim sebagai teks biasa dalam pesan
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": f"Here's the CSV data:\n\n{csv_content}\n\nPlease analyze this data.",
                }
            ],
        }
    ],
)

print(response.content[0].text)