Files API
Lade Dateien einmal hoch, referenziere sie per file_id in Messages-Anfragen und lade Ausgaben herunter, die von Skills oder dem Code-Execution-Tool erstellt wurden.
Nutzung unterscheidet sich je nach Produkt
file_id in einem document-, image- oder container_upload-Block.file_id in einem Event user.message.Mit der Files API kannst du Dateien hochladen und verwalten, um sie mit der Claude API zu verwenden, ohne den Inhalt bei jeder Anfrage erneut hochladen zu müssen. Dies ist besonders nützlich, wenn du das Code-Ausführungstool verwendest, um Eingaben bereitzustellen (zum Beispiel Datensätze und Dokumente) und anschließend Ausgaben herunterzuladen (zum Beispiel Diagramme). Zusätzlich zu diesem Leitfaden kannst du die API-Referenz direkt erkundenVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren..
Unterstützung von Dateitypen
Das Referenzieren einer file_id in einer Messages-Anfrage wird auf allen Modellen unterstützt, die den jeweiligen Dateityp unterstützen. Bilder werden auf allen aktuellen Claude-Modellen unterstützt. Für PDFs und andere Dateitypen mit dem Code-Execution-Tool findest du die Modellunterstützung auf den verlinkten Seiten.
So funktioniert die Files API
Die Files API bietet einen 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_iderhalten - Dateien herunterladen, die von Skills oder dem Code-Ausführungstool erstellt wurden
- Dateien referenzieren in MessagesVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren.-Anfragen über die
file_id, anstatt den Inhalt erneut hochzuladen - Deine Dateien verwalten mit Operationen zum Auflisten, Abrufen und Löschen
Dateien sind nicht auf einen Endnutzer, eine Konversation oder eine Sitzung beschränkt. Jeder API-Key mit Zugriff auf einen Workspace kann auf alle Dateien zugreifen, die in diesen Workspace hochgeladen wurden. Jedes Dienstkonto und jeder Nutzer, dessen Organisationsrolle API-Zugriff erlaubt, kann zusätzlich zu allen Workspaces, denen du ihn hinzufügst, den Standard-Workspace verwenden. Bewahre Dateien, die getrennt bleiben müssen, daher in einem eigenen Workspace auf und greife auf sie nur mit Keys zu, die auf diesen Workspace beschränkt sind. Akzeptiere niemals file_id-Werte von Endnutzern oder anderen nicht vertrauenswürdigen Quellen: Eine vom Nutzer bereitgestellte Datei-ID würde es einem Nutzer deiner Anwendung ermöglichen, Inhalte zu lesen, die ein anderer Nutzer hochgeladen hat. Behandle Datei-IDs als serverseitige Referenzen und verwalte die Zuordnung zwischen deinen Nutzern und ihren Dateien in deiner Anwendung.
Wenn du eine mandantenfähige Anwendung auf Basis der Files API erstellst, lege für jeden Mandanten einen separaten Workspace an. Der Workspace ist die Isolationsgrenze für Dateien, sodass ein Workspace pro Mandant die Daten dieses Mandanten strikt von allen anderen Mandanten isoliert. Jede Organisation kann bis zu 100 Workspaces haben; wende dich an dein Account-Team, wenn du mehr benötigst.
So verwendest du die Files API
Eine Datei hochladen
Lade eine Datei hoch, um sie in späteren API-Aufrufen zu referenzieren:
uploaded = client.files.upload(
file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
)
file_id = uploaded.id
print(file_id)Die Antwort auf das 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,
"expires_at": null
}downloadableVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren. ist für von dir hochgeladene Dateien false. Nur Dateien, die von Skills oder dem Code-Execution-Tool erstellt wurden, können heruntergeladen werden. Siehe Eine Datei herunterladen.
Die API-Referenz beschreibt jedes Feld des Dateiobjekts.
Eine Datei in Nachrichten verwenden
Nach dem Hochladen referenzierst du die Datei, indem du die id aus der Upload-Antwort als file_id übergibst:
response = client.messages.create(
model="claude-opus-5-5",
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,
},
},
],
}
],
)
print(response)Dateitypen und Content-Blöcke
Die Files API unterstützt verschiedene Dateitypen, die verschiedenen Content-Block-Typen entsprechen:
| Dateityp | MIME-Typ | Content-Block-Typ | Anwendungsfall |
|---|---|---|---|
application/pdf | document | Textanalyse, Dokumentenverarbeitung | |
| Klartext | text/plain | document | Textanalyse, Verarbeitung |
| Bilder | image/jpeg, image/png, image/gif, image/webp | image | Bildanalyse, visuelle Aufgaben |
| Datensätze, Sonstige (siehe Eigene Dateien hochladen und analysieren) | Unterschiedlich | container_upload | Datenanalyse, Visualisierung |
Document-Blöcke
Verwende für PDFs und Textdateien 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
Verwende für Bilder den image-Content-Block:
{
"type": "image",
"source": {
"type": "file",
"file_id": "file_011CPMxVD3fHLUhvTqtsQA5w"
}
}Container-Upload-Blöcke
Um eine Datei an das Code-Ausführungstool zu senden, verwende den container_upload-Content-Block:
{
"type": "container_upload",
"file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
}Mit anderen Dateiformaten arbeiten
Für Dateitypen, die der document-Block nicht unterstützt (zum Beispiel .docx und .xlsx), konvertiere die Dateien in Klartext und füge den Inhalt direkt in deine Nachricht ein. Dateien, die bereits Klartext sind, wie .csv- und .md-Dateien, können entweder auf diese Weise eingelesen oder über die Files API mit einem expliziten text/plain-Content-Type hochgeladen werden. Um Datensätze zu analysieren, anstatt sie als Text zu lesen, lade sie für das Code-Ausführungstool mit einem container_upload-Block hoch (siehe Eigene Dateien hochladen und analysieren).
Die folgenden Beispiele lesen eine Textdatei und senden ihren Inhalt als Klartext:
client = anthropic.Anthropic()
# Textdatei lesen
with open("document.txt") as f:
text_content = f.read()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": f"""Here's the document content:
{text_content}
Please summarize this document.""",
}
],
}
],
)
for block in response.content:
if block.type == "text":
print(block.text)Dateien verwalten
Dateien auflisten
Rufe eine Liste deiner hochgeladenen Dateien ab. Der Endpunkt ist paginiert: Jede Anfrage gibt bis zu limitVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren. Dateien zurück (standardmäßig 20, höchstens 1.000), und der next_pageVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren.-Cursor der Antwort ruft die nächste Seite ab, wenn er als pageVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren.-Parameter wieder übergeben wird. Dateien sind nach Neuheit sortiert, die neuesten zuerst. Siehe die API-Referenz für „Dateien auflisten“Vorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren.. Das SDK gibt die erste Seite zurück und stellt Hilfsfunktionen für automatische Paginierung bereit.
client = anthropic.Anthropic()
files = client.files.list()
print(files)Um eine bekannte Menge von Dateien in einer einzigen Anfrage zu prüfen, anstatt zu paginieren, übergib bis zu 100 Datei-IDs als ids[]-Query-Parameter. Eine ids[]-Anfrage unterscheidet sich in drei Punkten von einer paginierten Liste:
- Du kannst
ids[]nicht mitpageoderlimitkombinieren. - Die Antwort ist immer eine einzelne Seite (
next_pageistnull). - Wenn eine ID nicht zu einer Datei in deinem Workspace aufgelöst werden kann, lässt die API diese ID aus
dataweg, ohne einen Fehler zurückzugeben. Um die IDs zu finden, die die API weggelassen hat, vergleiche die zurückgegebenen IDs mit den angefragten IDs.
Datei-Metadaten abrufen
Rufe Informationen zu einer bestimmten Datei ab:
file = client.files.retrieve_metadata(file_id)
print(file)Eine Datei löschen
Lösche eine Datei aus deinem Workspace:
client.files.delete(file_id)Eine Datei herunterladen
Lade Dateien herunter, die Skills oder das Code-Ausführungstool erstellt haben. Dateien, die du hochlädst, können nicht heruntergeladen werden. Die file_id einer generierten Datei erscheint im bash_code_execution_tool_result-Content-Block der Messages-Antwort, die die Datei erstellt hat. Verwende diese file_id in der Download-Anfrage:
file_content = client.files.download(file_id)
file_content.write_to_file("downloaded_file.txt")Auf der Claude API tragen unterstützte Bild-, Video- und Audiodateien, die Claude mit dem Code-Ausführungstool erzeugt, einschließlich von Skills erstellter Dateien, beim Herunterladen signierte C2PA Content Credentials. Unter Content Credentials bei generierten Dateien erfährst du, was die Credentials enthalten und wie du sie überprüfst.
Dateispeicher und Limits
Speicherlimits
- Maximale Dateigröße: 500 MB pro Datei
- Gesamtspeicher: 1 TB pro Organisation
Lebenszyklus von Dateien
- Dateien sind auf den Workspace beschränkt, in den sie hochgeladen wurden. Jede Anfrage im selben Workspace kann sie referenzieren; akzeptiere niemals Datei-IDs aus nicht vertrauenswürdigen Quellen (siehe die Warnung zum Workspace-Zugriff).
- Dateien können nach dem Hochladen nicht geändert oder umbenannt werden. Um den Inhalt einer Datei zu ändern, lade eine neue Datei hoch und lösche die alte.
- Dateien bleiben bestehen, bis du sie mit dem Endpunkt
DELETE /v1/files/{file_id}löschst oder sie ihrexpires_aterreichen. - 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-Nutzungen fortbestehen.
- Dateien, die Nutzer löschen, werden gemäß der Richtlinie zur Datenaufbewahrung von Anthropic gelöscht.
Ablauf von Dateien
Damit eine Datei automatisch abläuft, füge beim Hochladen ein expires_in_secondsVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren.-Formularfeld hinzu. Der Wert ist eine ganze Zahl von Sekunden zwischen 3.600 (1 Stunde) und 7.776.000 (90 Tage). Der resultierende expires_atVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren.-Zeitstempel (RFC 3339) erscheint in jeder Dateiantwort und ist null für Dateien, die ohne Ablaufdatum hochgeladen wurden. Das Ablaufdatum wird einmalig beim Hochladen festgelegt und kann nicht geändert werden.
Wenn eine Datei ihr expires_at erreicht:
- Das Herunterladen ihres Inhalts (
GET /v1/files/{file_id}/content) gibt einen 404-Fehler zurück. - Eine Messages-Anfrage, die die Datei referenziert, schlägt vor der Inferenz fehl.
- Ihre Metadaten (
GET /v1/files/{file_id}) bleiben bis zu 30 Tage lang lesbar, wobeiexpires_atin der Vergangenheit liegt. - Sie erscheint während dieses Zeitraums weiterhin in Listenantworten; vergleiche
expires_atmit der aktuellen Zeit, um abgelaufene Dateien herauszufiltern.
Das Löschen einer abgelaufenen Datei mit DELETE /v1/files/{file_id} entfernt ihre Metadaten sofort, anstatt auf das Verstreichen des 30-Tage-Fensters zu warten.
Audit-Protokollierung
Wenn in deiner Organisation die Compliance API aktiviert ist, zeichnet deren Activity Feed Files-API-Operationen auf, die mit einem Claude-API-Key oder aus der Claude Console durchgeführt werden: Jeder Upload (POST /v1/files), jeder Inhalts-Download (GET /v1/files/{file_id}/content) und jede Löschung (DELETE /v1/files/{file_id}) erscheint als Aktivität platform_file_uploaded, platform_file_content_downloaded oder platform_file_deleted. Das Auflisten von Dateien und das Abrufen von Datei-Metadaten werden nicht aufgezeichnet. Operationen, die stattfinden, während die Compliance API deaktiviert ist, werden nicht aufgezeichnet und können später nicht wiederhergestellt werden. Richte daher die Compliance API ein, bevor du dich auf diesen Audit-Trail verlässt. Auf Claude Platform on AWS auditierst du Dateioperationen stattdessen mit AWS-CloudTrail-Datenereignissen.
Migration von files-api-2025-04-14
Die Files API hat die Beta-Phase verlassen und benötigt keinen Beta-Header. Die Migration weg von files-api-2025-04-14 ist optional: Anfragen, die ihn senden, funktionieren weiter und geben weiterhin die Beta-Antwortformen zurück, sodass eine bestehende Integration weiter funktioniert, bis du sie änderst. Das Entfernen des Headers stellt diese Anfragen auf die auf dieser Seite dokumentierten Formen um:
Mit files-api-2025-04-14 | Ohne den Header | |
|---|---|---|
| Listenantwort | { data, has_more, first_id, last_id } | { data, next_page }; gib next_page als Query-Parameter page zurück |
| Listen-Cursor | before_id, after_id | page oder bis zu 100 ids[] (before_id und after_id geben einen 400-Fehler zurück) |
expires_at bei Dateiobjekten | Nicht zurückgegeben | Immer vorhanden; null, wenn die Datei keinen Ablauf hat |
Content-Type beim hochgeladenen Dateiteil | Erforderlich | Optional; der Typ wird erkannt, wenn er weggelassen wird |
So migrierst du:
- Entferne den Beta-Header. Entferne
anthropic-beta: files-api-2025-04-14aus deinen Anfragen. Rufe mit dem SDKclient.filesstattclient.beta.filesauf; die Beibehaltung vonclient.beta.filesfunktioniert nur mit den SDK-Versionen, die den Header nicht mehr senden. Frühere Versionen senden ihn vonclient.beta.filesaus, selbst wenn du keine Beta-Namen übergibst. - Aktualisiere die Paginierung. Ersetze
after_id/before_id-Schleifen durch denpage/next_page-Cursor oder verwende die SDK-Hilfsfunktionen zur automatischen Paginierung, die unter Dateien verwalten gezeigt werden. - Lies
expires_at. Das Feld erscheint nur ohne den Header;nullbedeutet, dass die Datei keinen Ablauf hat (siehe Ablauf von Dateien).
SDK-Beta-Namespace
Das SDK bietet die Files API in zwei Namespaces an. Diese Seite verwendet den stabilen Namespace, und Files-Funktionen, die sich in der Beta-Phase befinden, verwenden den Beta-Namespace.
Ab der Version deines SDK in der folgenden Tabelle unterscheidet sich der Beta-Namespace in zwei Punkten von dem in früheren Versionen:
- Es sendet
files-api-2025-04-14nicht mehr. - Es gibt dieselben Formen wie der stabile Namespace zurück, jedoch unter Typnamen mit dem Präfix
Beta.
Die Tabelle nennt außerdem die Namespace-Namen jedes SDK und wo der Beta-Namespace anthropic-beta-Werte entgegennimmt:
| SDK | Stabiler Namespace | Beta-Namespace | Beta-Namespace geändert in | anthropic-beta-Werte gehören in |
|---|---|---|---|---|
| Python | client.files | client.beta.files | 1.2.0 | betas |
| TypeScript | client.files | client.beta.files | 0.122.0 | betas |
| C# | client.Files | client.Beta.Files | 12.44.0 | Betas |
| Go | client.Files | client.Beta.Files | 1.68.0 | Betas |
| Java | client.files() | client.beta().files() | 2.59.0 | .addBeta() |
| PHP | $client->files | $client->beta->files (Klassen in Anthropic\Beta) | 0.45.0 | betas |
| Ruby | client.files | client.beta.files | 1.67.0 | betas |
Verwende für eine Files-Funktion, die sich in der Beta-Phase befindet, den Beta-Namespace und übergib den anthropic-beta-Wert der Funktion wie in der Tabelle gezeigt. Zum Beispiel beschränkt scope_id unter einem Managed-Agents-Beta-Header eine Dateiliste auf die Dateien einer Sitzung. Wie du scope_id verwendest, erfährst du unter Session-Dateien auflisten und herunterladen.
In Versionen vor der Version deines SDK in der Tabelle entsprechen die Typen des Beta-Namespace den Formen, die files-api-2025-04-14 zurückgibt. Wenn du von diesen Typen abhängst, bleibe bei einer solchen Version, bis du von ihnen wegmigrierst.
Anfragen, die anthropic-beta: managed-agents-2026-04-01 ohne files-api-2025-04-14 tragen, erhalten die Formen auf dieser Seite mit einem Kompatibilitätszugeständnis bei GET /v1/files: before_id und after_id werden weiterhin akzeptiert (nicht kombinierbar mit page oder ids[]), und die Listenantwort enthält has_more, first_id und last_id neben next_page. Spätere Managed-Agents-Beta-Versionen erhalten die einfache Form.
Fehlerbehandlung
Häufige Fehler bei der Verwendung der Files API sind:
- Datei nicht gefunden (404): Die angegebene
file_idexistiert nicht oder du hast keinen Zugriff darauf. - Ungültiger Dateityp (400): Der Dateityp passt nicht zum Content-Block-Typ (zum Beispiel bei Verwendung einer Bilddatei in einem Document-Block).
- Nicht herunterladbar (400): Dateien, die du hochlädst, haben
"downloadable": falseund können nicht heruntergeladen werden. Nur Dateien, die von Skills oder dem Code-Ausführungstool erstellt wurden, können heruntergeladen werden. - Überschreitet die Größe des Kontextfensters (400): Die Datei ist größer als die Größe des „context window“ (Kontextfenster) (zum Beispiel bei Verwendung einer 500 MB großen Klartextdatei in einer
/v1/messages-Anfrage). - Ungültiger Dateiname (400): Der Dateiname erfüllt die Längenanforderungen (1–255 Zeichen) nicht oder enthält verbotene Zeichen (
<,>,:,",|,?,*,\,/oder Unicode-Zeichen 0–31). - Datei zu groß (413): Die Datei überschreitet das Limit von 500 MB.
- Speicherlimit überschritten (400): Deine Organisation hat das Speicherlimit von 1 TB erreicht.
{
"type": "error",
"error": {
"type": "not_found_error",
"message": "File `file_011CNha8iCJcU1wXNR6q4V8w` not found."
},
"request_id": "req_011CQFYcrRp7mCHLDsAYT8Qt"
}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 Input-Token abgerechnet.
Ratenlimits
Dateibezogene API-Aufrufe sind auf etwa 500 Anfragen pro Minute begrenzt. Um ein höheres Limit anzufragen, kontaktiere den Vertrieb.
Nächste Schritte
Verarbeite PDFs mit Claude. Extrahiere Text, analysiere Diagramme und verstehe visuelle Inhalte aus deinen Dokumenten.
Führe Python- und Bash-Code in einem Sandbox-Container aus, um Daten zu analysieren, Dateien zu generieren und Lösungen iterativ zu verbessern.
Verarbeite und analysiere visuelle Eingaben und generiere Text und Code aus Bildern.
Verfügbarkeit
Claude API
- APIs
- Messages API
- Managed Agents
- Modelle
- Alle Modelle
Claude Platform on AWS
- APIs
- Messages API
- Managed Agents
- Modelle
- Alle Modelle
Claude Models on Google Cloud (Anthropic managed)
- APIs
- Messages API
- Managed Agents
- Modelle
- Alle Modelle
Microsoft Foundry (hosted on Anthropic)
- API
- Messages API
- Modelle
- Alle Modelle
Datenverarbeitung
Übersicht über die DatenverarbeitungZutreffende Endpunkte
/v1/files
Dateien werden aufbewahrt, bis sie ausdrücklich gelöscht werden oder ihr konfiguriertes Ablaufdatum erreichen. Mehr erfahren
War diese Seite hilfreich?