Files API

Die Files API ermöglicht es dir, 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 du das Code-Execution-Tool verwendest, um Eingaben (z. B. Datensätze und Dokumente) bereitzustellen und anschließend Ausgaben (z. B. Diagramme) herunterzuladen. Du kannst die Files API auch nutzen, um zu vermeiden, dass häufig verwendete Dokumente und Bilder über mehrere API-Aufrufe hinweg immer wieder neu hochgeladen werden müssen. Zusätzlich zu diesem Leitfaden kannst du die API-Referenz direkt erkunden.



Unterstützte Modelle

Das Referenzieren einer file_id in einer Messages-Anfrage wird von allen Modellen unterstützt, die den jeweiligen Dateityp unterstützen. Bilder werden von allen aktuellen Claude-Modellen unterstützt. Für PDFs und andere Dateitypen mit dem Code-Execution-Tool findest du auf den verlinkten Seiten Informationen zur Modellunterstützung.

Die Files API ist über die Claude API, Claude Platform on AWS und Microsoft Foundry verfügbar. Sie ist derzeit nicht auf Amazon Bedrock oder Vertex AI verfügbar.



Wie die Files API funktioniert

Die Files API bietet einen einfachen Ansatz nach dem Prinzip „einmal erstellen, mehrfach verwenden" für die Arbeit mit Dateien:

• Dateien hochladen in den sicheren Speicher von Anthropic und eine eindeutige file_id erhalten
• Dateien herunterladen, die von Skills oder dem Code-Execution-Tool erstellt wurden
• Dateien referenzieren in Messages-Anfragen mithilfe der file_id, anstatt Inhalte erneut hochzuladen
• Deine Dateien verwalten mit Auflisten-, Abrufen- und Löschen-Operationen



So verwendest du die Files API



Eine Datei hochladen

Lade eine Datei hoch, um sie in zukünftigen API-Aufrufen zu referenzieren:

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 referenzierst du die Datei über ihre file_id:



Dateitypen und Content-Blöcke

Die Files API unterstützt verschiedene Dateitypen, die unterschiedlichen Content-Block-Typen entsprechen:



Arbeiten mit anderen Dateiformaten

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



Document-Blöcke

Für PDFs und Textdateien verwendest du den document-Content-Block:

{
  "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
}



Image-Blöcke

Für Bilder verwendest du den image-Content-Block:

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



Dateien verwalten



Dateien auflisten

Rufe eine Liste deiner hochgeladenen Dateien ab:



Datei-Metadaten abrufen

Rufe Informationen zu einer bestimmten Datei ab:



Eine Datei löschen

Entferne eine Datei aus deinem Workspace:



Eine Datei herunterladen

Lade Dateien herunter, die von Skills oder dem Code-Execution-Tool erstellt wurden:



Dateispeicher und Limits



Speicherlimits

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



Datei-Lebenszyklus

• Dateien sind auf den Workspace des API-Keys beschränkt. Andere API-Keys können Dateien verwenden, die von einem beliebigen anderen API-Key erstellt wurden, der demselben Workspace zugeordnet ist
• Dateien bleiben bestehen, bis du sie löschst
• Gelöschte Dateien können nicht wiederhergestellt werden
• Dateien sind kurz nach dem Löschen nicht mehr über die API zugänglich, können aber in aktiven Messages-API-Aufrufen und zugehörigen Tool-Nutzungen weiterhin bestehen
• Dateien, die Nutzer löschen, werden gemäß der Datenaufbewahrungsrichtlinie von Anthropic gelöscht.



Datenaufbewahrung

Dateien, die über die Files API hochgeladen werden, bleiben erhalten, bis sie explizit über den Endpunkt DELETE /v1/files/{file_id} gelöscht werden. Dateien werden zur Wiederverwendung über mehrere API-Anfragen hinweg gespeichert.

Informationen zur ZDR-Eignung für alle Funktionen findest du unter API und Datenaufbewahrung.



Fehlerbehandlung

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

• Datei nicht gefunden (404): Die angegebene file_id existiert nicht oder du hast keinen Zugriff darauf
• Ungültiger Dateityp (400): Der Dateityp passt nicht zum Content-Block-Typ (z. B. Verwendung einer Bilddatei in einem Document-Block)
• Überschreitet die Größe des Kontextfensters (400): Die Datei ist größer als das Kontextfenster (z. B. Verwendung einer 500 MB großen Klartextdatei in einer /v1/messages-Anfrage)
• Ungültiger Dateiname (400): Der Dateiname erfüllt nicht die Längenanforderungen (1–255 Zeichen) oder enthält unzulässige 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

File-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 Input-Token abgerechnet. Du kannst nur Dateien herunterladen, die von Skills oder dem Code-Execution-Tool erstellt wurden.



Ratenlimits

Während der Beta-Phase:

• Dateibezogene API-Aufrufe sind auf etwa 100 Anfragen pro Minute begrenzt
• Kontaktiere uns, wenn du höhere Limits für deinen Anwendungsfall benötigst