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-Execution-Tool 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ützte 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.



Wie die Files API funktioniert

Die Files API bietet einen „einmal erstellen, mehrfach verwenden"-Ansatz 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 über die file_id, anstatt den Inhalt 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:

uploaded = client.files.upload(
    file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
)
file_id = uploaded.id
print(file_id)

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
}

downloadable ist false für Dateien, die du hochlädst. Nur Dateien, die von Skills oder dem Code-Execution-Tool 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 unterschiedlichen Content-Block-Typen entsprechen:



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



Container-Upload-Blöcke

Um eine Datei an das Code-Execution-Tool zu senden, verwendest du den container_upload-Content-Block:

{
  "type": "container_upload",
  "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
}



Arbeiten mit anderen Dateiformaten

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-Execution-Tool mit einem container_upload-Block hoch.

Die folgenden Beispiele lesen eine Textdatei ein 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), und die Parameter before_id und after_id rufen die benachbarte Seite ab. Siehe die List-Files-API-Referenz. Die SDKs geben die erste Seite zurück und bieten Auto-Pagination-Helfer. Das CLI-Beispiel begrenzt die Gesamtzahl mit --max-items:

client = anthropic.Anthropic()
files = client.beta.files.list()
print(files)



Datei-Metadaten abrufen

Rufe Informationen über eine bestimmte 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-Execution-Tool 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")



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, der sie hochgeladen hat. Jeder API-Key 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
• 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 vorhanden sein
• Dateien, die Nutzer löschen, werden gemäß der Datenaufbewahrungsrichtlinie von Anthropic gelöscht. Zur ZDR-Eignung über alle Features hinweg siehe 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 (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-Execution-Tool erstellt wurden, können heruntergeladen werden
• Überschreitet Kontextfenstergröße (400): Die Datei ist größer als die Größe des Kontextfensters (zum Beispiel die Verwendung einer 500-MB-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 500-MB-Limit
• Speicherlimit überschritten (400): Deine Organisation hat das Speicherlimit von 500 GB 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 berechnet.



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



Nächste Schritte