Die Files API ermöglicht es Ihnen, Dateien hochzuladen und zu verwalten, um sie mit der Anthropic 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 (z.B. Datensätze und Dokumente) bereitzustellen und dann Ausgaben (z.B. Diagramme) herunterzuladen. Sie können die Files API auch verwenden, um zu vermeiden, dass häufig verwendete Dokumente und Bilder über mehrere API-Aufrufe hinweg ständig neu hochgeladen werden müssen.

Die Files API befindet sich derzeit in der Beta-Phase. Bitte teilen Sie uns Ihre Erfahrungen mit der Files API über unser Feedback-Formular mit.

Unterstützte Modelle

Die Referenzierung 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 3.5 Haiku 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 nach dem Prinzip “einmal erstellen, mehrfach verwenden” für die Arbeit mit Dateien:

  • Dateien hochladen in unseren sicheren Speicher und Erhalt einer eindeutigen file_id
  • Dateien herunterladen, die vom Code-Ausführungs-Tool erstellt wurden
  • Dateien referenzieren in Messages-Anfragen unter Verwendung der file_id, anstatt Inhalte erneut hochzuladen
  • Dateien verwalten mit Auflisten-, Abrufen- und Löschen-Operationen

Wie man die Files API verwendet

Um die Files API zu verwenden, müssen Sie den Beta-Feature-Header einfügen: anthropic-beta: files-api-2025-04-14.

Eine Datei hochladen

Laden Sie eine Datei hoch, auf die in zukünftigen API-Aufrufen verwiesen werden kann:

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"

Dateitypen und Inhaltsblöcke

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

DateitypMIME-TypInhaltsblocktypAnwendungsfall
PDFapplication/pdfdocumentTextanalyse, Dokumentenverarbeitung
Klartexttext/plaindocumentTextanalyse, Verarbeitung
Bilderimage/jpeg, image/png, image/gif, image/webpimageBildanalyse, visuelle Aufgaben
Datensätze, andereVariiertcontainer_uploadDaten analysieren, Visualisierungen erstellen

Dokumentenblöcke

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

{
  "type": "document",
  "source": {
    "type": "file",
    "file_id": "file_abc123"
  },
  "title": "Dokumenttitel", // Optional
  "context": "Kontext über das Dokument", // Optional  
  "citations": {"enabled": true} // Optional, aktiviert Zitierungen
}

Bildblöcke

Für Bilder verwenden Sie den image-Inhaltsblock:

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

Dateien verwalten

Dateien auflisten

Rufen Sie eine Liste Ihrer hochgeladenen Dateien ab:

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

Rufen Sie Informationen über eine bestimmte Datei ab:

curl https://api.anthropic.com/v1/files/file_abc123 \
  -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

Entfernen Sie eine Datei aus Ihrem Workspace:

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

Eine Datei herunterladen

Laden Sie Dateien herunter, die vom Code-Ausführungs-Tool erstellt wurden:

curl -X GET "https://api.anthropic.com/v1/files/file_abc123/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

Sie können nur Dateien herunterladen, die vom Code-Ausführungs-Tool erstellt wurden. Von Ihnen hochgeladene Dateien können nicht heruntergeladen werden.


Dateispeicherung und Limits

Speicherlimits

  • Maximale Dateigröße: 32 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 jedem 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 aber in aktiven Messages-API-Aufrufen und zugehörigen Tool-Verwendungen bestehen bleiben

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. Verwendung einer Bilddatei in einem Dokumentenblock)
  • Datei zu groß (413): Datei überschreitet das Limit von 500 MB
  • Speicherlimit überschritten (403): Ihre Organisation hat das Speicherlimit von 100 GB erreicht
  • Ungültiger Dateiname (400): Der Dateiname entspricht nicht den Längenanforderungen (1-255 Zeichen) oder enthält verbotene Zeichen (<, >, :, ", |, ?, *, \, / oder Unicode-Zeichen 0-31)
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "File not found: file_abc123"
  }
}

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 Eingabe-Tokens berechnet. Sie können nur Dateien herunterladen, die vom Code-Ausführungs-Tool erstellt wurden.

Ratenbegrenzungen

Während der Beta-Phase:

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