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 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 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 ditambah 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 kami dan terima file_id yang 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 list, retrieve, dan delete

Cara menggunakan Files API

Mengunggah file

Unggah file untuk direferensikan dalam panggilan API di masa mendatang:

curl -X POST https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -F "file=@/path/to/document.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 pesan

Setelah diunggah, referensikan file menggunakan file_id-nya:

curl -X POST https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -H "content-type: application/json" \
  -d '{
    "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_011CNha8iCJcU1wXNR6q4V8w"
            }
          }
        ]
      }
    ]
  }'

Jenis file dan blok konten

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

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:

# Contoh: Membaca file teks dan mengirimkannya sebagai teks biasa
# Catatan: Untuk file dengan karakter khusus, pertimbangkan pengkodean base64
TEXT_CONTENT=$(cat document.txt | jq -Rs .)

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d @- <<EOF
{
  "model": "claude-opus-4-6",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Here's the document content:\n\n${TEXT_CONTENT}\n\nPlease summarize this document."
        }
      ]
    }
  ]
}
EOF

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 telah Anda unggah:

curl https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

Dapatkan metadata file

Ambil informasi tentang file tertentu:

curl https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

Hapus file

Hapus file dari workspace Anda:

curl -X DELETE https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

Mengunduh file

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

curl -X GET "https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w/content" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  --output downloaded_file.txt

Penyimpanan dan batas file

Batas penyimpanan

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

Siklus hidup file

• File dibatasi pada workspace dari API key. API key lain dapat menggunakan file yang dibuat oleh API key lain yang terkait dengan workspace yang sama
• File tetap ada hingga 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 yang aktif dan penggunaan alat terkait
• File yang dihapus pengguna akan dihapus sesuai dengan kebijakan retensi data kami.

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 kesalahan

Kesalahan umum saat menggunakan Files API meliputi:

• File tidak ditemukan (404): file_id yang ditentukan tidak ada atau Anda tidak memiliki akses ke sana
• 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 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 yang dilarang (<, >, :, ", |, ?, *, \, /, atau karakter unicode 0-31)
• File terlalu besar (413): File melebihi batas 500 MB
• Batas penyimpanan terlampaui (403): Organisasi Anda telah mencapai batas penyimpanan 100 GB

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

Penggunaan dan penagihan

Operasi File API adalah gratis:

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

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

Batas kecepatan

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