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 code execution tool untuk menyediakan input (misalnya dataset dan dokumen) lalu mengunduh output (misalnya grafik). Anda juga dapat menggunakan Files API untuk menghindari keharusan mengunggah ulang dokumen dan gambar yang sering digunakan secara terus-menerus di berbagai panggilan API. 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 tersebut. Gambar didukung pada semua model Claude saat ini. Untuk PDF dan tipe file lainnya dengan code execution tool, lihat halaman tertaut untuk dukungan model.

Files API tersedia di Claude API, Claude Platform on 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 sederhana buat-sekali, gunakan-berkali-kali untuk bekerja dengan file:

• Unggah file ke penyimpanan aman Anthropic dan terima file_id unik
• Unduh file yang dibuat dari skills atau code execution tool
• 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 berikutnya:

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

Respons dari pengunggahan file akan 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
}



Menggunakan file dalam messages

Setelah diunggah, referensikan file menggunakan file_id-nya:

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:



Bekerja dengan format file lainnya

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

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-8",
    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)



Blok document

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 image

Untuk gambar, gunakan blok konten image:

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



Mengelola file



Menampilkan daftar file

Ambil daftar file yang telah Anda unggah:

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



Mendapatkan metadata file

Ambil informasi tentang file tertentu:

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



Menghapus file

Hapus file dari workspace Anda:

result = client.beta.files.delete(file_id)



Mengunduh file

Unduh file yang telah dibuat oleh skills atau code execution tool:

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

# Simpan ke file
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. Kunci API lain dapat menggunakan file yang dibuat oleh kunci API lain mana pun yang terkait dengan workspace yang sama
• File tetap tersimpan hingga Anda menghapusnya
• File yang dihapus tidak dapat dipulihkan
• File tidak dapat diakses melalui API sesaat setelah penghapusan, tetapi mungkin masih ada dalam panggilan API Messages yang 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 hingga dihapus secara eksplisit menggunakan endpoint DELETE /v1/files/{file_id}. File disimpan untuk digunakan kembali di berbagai permintaan API.

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



Penanganan error

Error umum saat menggunakan Files API meliputi:

• File not found (404): file_id yang ditentukan tidak ada atau Anda tidak memiliki akses ke file tersebut
• Invalid file type (400): Tipe file tidak cocok dengan tipe blok konten (misalnya, menggunakan file gambar dalam blok document)
• Exceeds context window size (400): File lebih besar dari ukuran jendela konteks (misalnya menggunakan file teks biasa 500 MB dalam permintaan /v1/messages)
• Invalid filename (400): Nama file tidak memenuhi persyaratan panjang (1-255 karakter) atau berisi karakter terlarang (<, >, :, ", |, ?, *, \, /, atau karakter unicode 0-31)
• File too large (413): File melebihi batas 500 MB
• Storage limit exceeded (403): Organisasi Anda telah mencapai batas penyimpanan 500 GB

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



Penggunaan dan penagihan

Operasi File API bersifat 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. Anda hanya dapat mengunduh file yang dibuat oleh skills atau code execution tool.



Batas laju

Selama periode beta:

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