Files API

Die Files API ermöglicht es Ihnen, Dateien hochzuladen und zu verwalten, um sie mit der Claude API zu verwenden, ohne Inhalte bei jeder Anfrage erneut hochladen zu müssen. Dies ist besonders nützlich, wenn Sie das Code-Ausführungs-Tool verwenden, um Eingaben bereitzustellen (z. B. Datensätze und Dokumente) und dann Ausgaben herunterzuladen (z. B. Diagramme). Sie können die Files API auch verwenden, um zu vermeiden, häufig verwendete Dokumente und Bilder bei mehreren API-Aufrufen immer wieder hochladen zu müssen. Sie können die API-Referenz direkt erkunden, zusätzlich zu diesem Leitfaden.

Unterstützte Modelle

Das Referenzieren einer file_id in einer Messages-Anfrage wird in allen Modellen unterstützt, die den jeweiligen Dateityp unterstützen. Zum Beispiel werden Bilder in allen Claude 3+ Modellen unterstützt, PDFs in allen Claude 3.5+ Modellen und verschiedene andere Dateitypen für das Code-Ausführungs-Tool in Claude Haiku 4.5 sowie allen Claude 3.7+ Modellen.

Die Files API wird derzeit nicht auf Amazon Bedrock oder Google Vertex AI unterstützt.

Wie die Files API funktioniert

Die Files API bietet einen einfachen Ansatz: einmal erstellen, mehrfach verwenden:

• Dateien hochladen in unseren sicheren Speicher und eine eindeutige file_id erhalten
• Dateien herunterladen, die von Skills oder dem Code-Ausführungs-Tool erstellt wurden
• Dateien referenzieren in Messages-Anfragen mithilfe der file_id anstatt Inhalte erneut hochzuladen
• Ihre Dateien verwalten mit Auflisten-, Abrufen- und Löschoperationen

Verwendung der Files API

Eine Datei hochladen

Laden Sie eine Datei hoch, die in zukünftigen API-Aufrufen referenziert werden soll:

Die Antwort beim Hochladen einer Datei enthält:

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

Eine Datei in Nachrichten verwenden

Nach dem Hochladen können Sie die Datei über ihre file_id referenzieren:

Dateitypen und Inhaltsblöcke

Die Files API unterstützt verschiedene Dateitypen, die verschiedenen Inhaltsblocktypen entsprechen:

Arbeiten mit anderen Dateiformaten

Für Dateitypen, die nicht als document-Blöcke unterstützt werden (.csv, .txt, .md, .docx, .xlsx), konvertieren Sie die Dateien in Klartext und fügen Sie den Inhalt direkt in Ihre Nachricht ein:

Dokumentblöcke

Für PDFs und Textdateien verwenden Sie den document-Inhaltsblock:

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

Bildblöcke

Für Bilder verwenden Sie den image-Inhaltsblock:

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

Dateien verwalten

Dateien auflisten

Eine Liste Ihrer hochgeladenen Dateien abrufen:

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"

Datei-Metadaten abrufen

Informationen über eine bestimmte Datei abrufen:

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"

Eine Datei löschen

Eine Datei aus Ihrem Workspace entfernen:

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"

Eine Datei herunterladen

Dateien herunterladen, die von Skills oder dem Code-Ausführungs-Tool erstellt wurden:

Dateispeicherung und Limits

Speicherlimits

• Maximale Dateigröße: 500 MB pro Datei
• Gesamtspeicher: 100 GB pro Organisation

Datei-Lebenszyklus

• Dateien sind auf den Workspace des API-Schlüssels beschränkt. Andere API-Schlüssel können Dateien verwenden, die von einem anderen API-Schlüssel erstellt wurden, der mit demselben Workspace verknüpft ist
• Dateien bleiben bestehen, bis Sie sie löschen
• Gelöschte Dateien können nicht wiederhergestellt werden
• Dateien sind kurz nach dem Löschen über die API nicht mehr zugänglich, können jedoch in aktiven Messages-API-Aufrufen und zugehörigen Tool-Verwendungen weiterhin vorhanden sein
• Dateien, die Benutzer löschen, werden gemäß unserer Datenaufbewahrungsrichtlinie gelöscht.

Datenspeicherung

Über die Files API hochgeladene Dateien werden aufbewahrt, bis sie explizit über den Endpunkt DELETE /v1/files/{file_id} gelöscht werden. Dateien werden für die Wiederverwendung über mehrere API-Anfragen hinweg gespeichert.

Informationen zur ZDR-Berechtigung für alle Funktionen finden Sie unter API und Datenspeicherung.

Fehlerbehandlung

Häufige Fehler bei der Verwendung der Files API sind:

• Datei nicht gefunden (404): Die angegebene file_id existiert nicht oder Sie haben keinen Zugriff darauf
• Ungültiger Dateityp (400): Der Dateityp stimmt nicht mit dem Inhaltsblocktyp überein (z. B. eine Bilddatei in einem Dokumentblock verwenden)
• Überschreitet die Kontextfenstergröße (400): Die Datei ist größer als die Kontextfenstergröße (z. B. eine 500 MB große Klartextdatei in einer /v1/messages-Anfrage verwenden)
• Ungültiger Dateiname (400): Der Dateiname erfüllt nicht die Längenanforderungen (1–255 Zeichen) oder enthält verbotene Zeichen (<, >, :, ", |, ?, *, \, / oder Unicode-Zeichen 0–31)
• Die Datei überschreitet das Limit von 500 MB

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

Nutzung und Abrechnung

Files-API-Operationen sind kostenlos:

• Dateien hochladen
• Dateien herunterladen
• Dateien auflisten
• Datei-Metadaten abrufen
• Dateien löschen

Dateiinhalte, die in Messages-Anfragen verwendet werden, werden als Eingabe-Token berechnet. Sie können nur Dateien herunterladen, die von Skills oder dem Code-Ausführungs-Tool erstellt wurden.

Ratenlimits

Während der Beta-Phase:

• Dateibezogene API-Aufrufe sind auf ungefähr 100 Anfragen pro Minute begrenzt
• Kontaktieren Sie uns, wenn Sie für Ihren Anwendungsfall höhere Limits benötigen