Files API

Die Files API ermöglicht es Ihnen, Dateien hochzuladen und zu verwalten, um sie mit der Claude API zu verwenden, ohne Inhalte bei jeder Anfrage erneut hochzuladen. 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 bei mehreren API-Aufrufen kontinuierlich erneut hochgeladen werden müssen. Sie können die API-Referenz direkt erkunden, zusätzlich zu diesem Leitfaden.

Die Files API befindet sich in der Beta-Phase. Teilen Sie Ihre Erfahrungen mit der Files API über das Feedback-Formular mit.

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

Unterstützte Modelle

Das Referenzieren einer file_id in einer Messages-Anfrage wird in allen Modellen unterstützt, die den angegebenen Dateityp unterstützen. Beispielsweise 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 Haiku 4.5 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 zum einmaligen Hochladen und mehrfachen Verwenden von Dateien:

Dateien hochladen zu Anthropics sicherer Speicherung und erhalten Sie eine eindeutige file_id
Dateien herunterladen, die von Skills oder dem Code-Ausführungs-Tool erstellt werden
Dateien referenzieren in Messages-Anfragen mit der file_id statt Inhalte erneut hochzuladen
Dateien verwalten mit List-, Retrieve- und Delete-Operationen

Wie man die Files API verwendet

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

Eine Datei hochladen

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

Die Antwort vom Hochladen einer Datei enthält:

Output

{
  "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 referenzieren Sie die Datei mit ihrer file_id:

Dateitypen und Inhaltsblöcke

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

Dateityp	MIME-Typ	Inhaltsblocktyp	Anwendungsfall
PDF	`application/pdf`	`document`	Textanalyse, Dokumentverarbeitung
Nur-Text	`text/plain`	`document`	Textanalyse, Verarbeitung
Bilder	`image/jpeg`, `image/png`, `image/gif`, `image/webp`	`image`	Bildanalyse, visuelle Aufgaben
Datensätze, andere

Arbeiten mit anderen Dateiformaten

Für Dateitypen, die nicht als document-Blöcke unterstützt werden (.csv, .txt, .md, .docx, .xlsx), konvertieren Sie die Dateien in Nur-Text und fügen Sie den Inhalt direkt in Ihre Nachricht ein:

Für .docx-Dateien mit Bildern konvertieren Sie diese zuerst in das PDF-Format und verwenden Sie dann PDF-Unterstützung, um die integrierte Bildanalyse zu nutzen. Dies ermöglicht die Verwendung von Zitaten aus dem PDF-Dokument.

Dokumentblöcke

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

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

Bildblöcke

Für Bilder verwenden Sie den image-Inhaltsblock:

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

Dateien verwalten

Dateien auflisten

Rufen Sie eine Liste Ihrer hochgeladenen Dateien ab:

Datei-Metadaten abrufen

Rufen Sie Informationen über eine bestimmte Datei ab:

Eine Datei löschen

Entfernen Sie eine Datei aus Ihrem Arbeitsbereich:

Eine Datei herunterladen

Laden Sie Dateien herunter, die von Skills oder dem Code-Ausführungs-Tool erstellt wurden:

Sie können nur Dateien herunterladen, die von Skills oder dem Code-Ausführungs-Tool erstellt wurden. Dateien, die Sie hochgeladen haben, können nicht heruntergeladen werden.

Dateispeicherung und Limits

Speicherlimits

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

Datei-Lebenszyklus

Dateien sind auf den Arbeitsbereich 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 Arbeitsbereich 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 zugänglich, können aber in aktiven Messages-API-Aufrufen und zugehörigen Tool-Verwendungen bestehen bleiben
Dateien, die Benutzer löschen, werden gemäß Anthropics Datenspeicherungsrichtlinie gelöscht.

Datenspeicherung

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

Für ZDR-Berechtigung über alle Funktionen hinweg siehe API und Datenspeicherung.

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 Dokumentblock)
Überschreitet Kontextfenstergröße (400): Die Datei ist größer als die Kontextfenstergröße (z. B. Verwendung einer 500-MB-Nur-Text-Datei in einer /v1/messages-Anfrage)
Ungültiger Dateiname (400): Der Dateiname erfüllt nicht die Längenanforderungen (1-255 Zeichen) oder enthält verbotene Zeichen (<, >, :, ", |, ?, *, \, / oder Unicode-Zeichen 0-31)
Datei überschreitet das 500-MB-Limit

Output

{
  "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 Eingabe-Token berechnet. Sie können nur Dateien herunterladen, die von Skills oder dem Code-Ausführungs-Tool erstellt wurden.

Ratenlimits

Während der Beta-Phase:

File-bezogene API-Aufrufe sind auf ungefähr 100 Anfragen pro Minute begrenzt
Kontaktieren Sie uns, wenn Sie höhere Limits für Ihren Anwendungsfall benötigen

response = client.beta.messages.create(
    model="claude-opus-4-6",
    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,
                    },
                },
            ],
        }
    ],
    betas=["files-api-2025-04-14"],
)
print(response)

import pandas as pd
# ...
# Beispiel: Lesen einer CSV-Datei
df = pd.read_csv("data.csv")
csv_content = df.to_string()

# Als Nur-Text in der Nachricht senden
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": f"Here's the CSV data:\n\n{csv_content}\n\nPlease analyze this data.",
                }
            ],
        }
    ],
)

print(response.content[0].text)