Files API

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 erkunden.

Unterstützung von Dateitypen

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-Ausführungstool 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_id erhalten
• Dateien herunterladen, die von Skills oder dem Code-Ausführungstool erstellt wurden
• Dateien referenzieren in Messages-Anfragen über die file_id, anstatt den Inhalt erneut hochzuladen
• Deine Dateien verwalten mit Operationen zum Auflisten, Abrufen und Löschen

So verwendest du die Files API

Eine Datei hochladen

Lade eine Datei hoch, um sie in zukünftigen 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
}

downloadable ist false für Dateien, die du hochlädst. Nur Dateien, die von Skills oder dem Code-Ausführungstool erstellt wurden, können heruntergeladen werden. Siehe Eine Datei herunterladen.

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",
    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:

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 gelesen 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.

Die folgenden Beispiele lesen eine Textdatei und senden ihren Inhalt als Klartext:

client = anthropic.Anthropic()

# Lies die Textdatei
with open("document.txt") as f:
    text_content = f.read()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": f"Here's the document content:\n\n{text_content}\n\nPlease 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 limit Dateien zurück (standardmäßig 20, maximal 1.000), und der next_page-Cursor der Antwort ruft die nächste Seite ab, wenn er als page-Parameter zurückgegeben wird. Dateien sind nach Neuheit sortiert, die neuesten zuerst. Siehe die API-Referenz zum Auflisten von Dateien. Die SDKs geben die erste Seite zurück und bieten Hilfsfunktionen zur automatischen Paginierung. Das CLI-Beispiel begrenzt die Gesamtzahl mit --max-items:

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 gibt immer eine einzelne Seite zurück (next_page ist null), und jede ID, die nicht zu einer Datei in deinem Workspace aufgelöst werden kann, wird stillschweigend aus data weggelassen; vergleiche die zurückgegebenen IDs mit den angefragten IDs, um fehlende Treffer zu erkennen. ids[] kann nicht mit page oder limit kombiniert werden.

Datei-Metadaten abrufen

Rufe Informationen zu einer bestimmten Datei ab:

file = client.files.retrieve_metadata(file_id)
print(file)

Eine Datei löschen

Entferne eine Datei aus deinem Workspace:

client.files.delete(file_id)

Eine Datei herunterladen

Lade Dateien herunter, die von Skills oder dem Code-Ausführungstool erstellt wurden. 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 sie erstellt hat:

file_content = client.files.download(file_id)

file_content.write_to_file("downloaded_file.txt")

Auf der Claude API tragen unterstützte Bild- und Videodateien, die Claude mit dem Code-Ausführungstool erzeugt, einschließlich von Skills erstellter Dateien, signierte C2PA Content Credentials, wenn du sie herunterlädst. Unter Content Credentials bei generierten Dateien erfährst du, was das Credential enthält und wie du es verifizierst.

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 ihr expires_at erreichen
• 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 weiterbestehen
• Dateien, die Nutzer löschen, werden gemäß der Datenaufbewahrungsrichtlinie von Anthropic gelöscht. Zur ZDR-Berechtigung über alle Funktionen hinweg siehe API und Datenaufbewahrung

Ablauf von Dateien

Damit eine Datei automatisch abläuft, füge beim Hochladen ein Formularfeld expires_in_seconds hinzu. Der Wert ist eine ganze Zahl von Sekunden zwischen 3.600 (1 Stunde) und 7.776.000 (90 Tage). Der resultierende expires_at-Zeitstempel (RFC 3339) erscheint in jeder Dateiantwort und ist null für Dateien, die ohne Ablauf hochgeladen wurden. Der Ablauf 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, wobei expires_at in der Vergangenheit liegt
• Sie erscheint während dieses Zeitfensters weiterhin in Listenantworten; vergleiche expires_at mit 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 weiterhin 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:

So migrierst du:

1. Entferne den Beta-Header. Entferne anthropic-beta: files-api-2025-04-14 aus deinen Anfragen. Rufe in den SDKs client.files statt client.beta.files auf; client.beta.files beizubehalten funktioniert nur mit den SDK-Releases, die den Header nicht mehr senden. Frühere Releases senden ihn von client.beta.files aus auch ohne betas-Argument.
2. Aktualisiere die Paginierung. Ersetze after_id/before_id-Schleifen durch den page/next_page-Cursor oder verwende die SDK-Hilfsfunktionen zur automatischen Paginierung, die unter Dateien verwalten gezeigt werden.
3. Lies expires_at. Das Feld erscheint nur ohne den Header; null bedeutet, dass die Datei keinen Ablauf hat (siehe Ablauf von Dateien).

SDK-Beta-Namespace

Ab Python SDK 1.2.0, TypeScript SDK 0.122.0, Go SDK 1.68.0, Java SDK 2.59.0, Ruby SDK 1.67.0 und C# SDK 12.44.0 sendet client.beta.files files-api-2025-04-14 nicht mehr und gibt dieselben Formen wie client.files zurück, mit Typnamen mit Beta-Präfix. Es akzeptiert ein betas-Argument für Files-Funktionen, die sich noch in der Beta-Phase befinden, wie etwa die scope_id-Filterung unter einem Managed Agents-Beta-Header. Frühere SDK-Releases sind auf die Beta-Formen typisiert; wenn du von diesen Typen abhängig bist, bleibe bei einem früheren Release, bis du migrierst.

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_id existiert nicht oder du hast keinen Zugriff darauf
• Ungültiger Dateityp (400): Der Dateityp passt nicht zum Content-Block-Typ (zum Beispiel die Verwendung einer Bilddatei in einem Document-Block)
• Nicht herunterladbar (400): Dateien, die du hochlädst, haben "downloadable": false und 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 das „context window“ (Kontextfenster) (zum Beispiel die 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)
• 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 „rate limit“ (Ratenlimit) anzufragen, kontaktiere den Vertrieb.

Nächste Schritte

Compatibility