Files API

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



Model yang didukung

Mereferensikan file_id dalam permintaan Messages didukung pada semua model yang mendukung tipe file yang diberikan. Gambar didukung pada semua model Claude saat ini. Untuk PDF dan tipe file lainnya dengan alat eksekusi kode, lihat halaman yang ditautkan untuk dukungan model.

Files API tersedia di Claude API, Claude Platform di AWS, dan Microsoft Foundry. Di Microsoft Foundry, Files API memerlukan deployment Hosted on Anthropic. Saat ini belum tersedia di Amazon Bedrock atau Google Cloud.



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 yang 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 di masa mendatang:

uploaded = client.beta.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
}

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.beta.messages.create(
    model="claude-opus-4-8",
    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)



Tipe file dan blok konten

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



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 lainnya

Untuk tipe file yang tidak didukung oleh blok document (misalnya, .docx dan .xlsx), konversikan file tersebut 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 tipe konten text/plain secara 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 isinya 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-4-8",
    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.",
                }
            ],
        }
    ],
)

print(response.content[0].text)



Mengelola file



Menampilkan daftar file

Ambil daftar file yang telah Anda unggah. Endpoint ini dipaginasi: setiap permintaan mengembalikan hingga limit file (20 secara default), dan parameter before_id serta after_id mengambil halaman yang berdekatan. Lihat referensi List Files API. SDK mengembalikan halaman pertama dan menyediakan helper paginasi otomatis. Contoh CLI membatasi total dengan --max-items:

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



Mendapatkan metadata file

Ambil informasi tentang file tertentu:

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



Menghapus file

Hapus file dari workspace Anda:

client.beta.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 di blok konten code_execution_tool_result dari respons Messages yang membuatnya:

file_content = client.beta.files.download(file_id)

file_content.write_to_file("downloaded_file.txt")



Penyimpanan dan batasan file



Batasan penyimpanan

• Ukuran file maksimum: 500 MB per file
• Total penyimpanan: 500 GB per organisasi



Siklus hidup file

• File dibatasi pada workspace dari kunci API yang mengunggahnya. Kunci API mana pun dalam workspace yang sama dapat mereferensikannya
• File tidak dapat dimodifikasi atau diganti namanya setelah diunggah. Untuk mengubah konten file, unggah file baru dan hapus file lama
• File tetap ada sampai Anda menghapusnya dengan endpoint DELETE /v1/files/{file_id}
• File yang dihapus tidak dapat dipulihkan
• File tidak dapat diakses melalui API segera setelah penghapusan, tetapi file tersebut mungkin tetap ada dalam panggilan Messages API yang 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



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
• Tipe file tidak valid (400): Tipe file tidak cocok dengan tipe 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 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 500 GB

{
  "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
• Menampilkan daftar file
• Mendapatkan metadata file
• Menghapus file

Konten file yang digunakan dalam permintaan Messages dikenakan biaya sebagai token input.



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



Langkah selanjutnya