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 bei der Verwendung des Code-Ausführungstools, 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, häufig verwendete Dokumente und Bilder bei mehreren API-Aufrufen kontinuierlich erneut hochladen zu müssen.

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

​
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ührungstool in Claude 3.5 Haiku plus 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 Erstellen und mehrfachen Verwenden für die Arbeit mit Dateien:

  • Dateien hochladen in unseren sicheren Speicher und eine eindeutige file_id erhalten
  • Dateien herunterladen, die vom Code-Ausführungstool erstellt wurden
  • Dateien referenzieren in Messages-Anfragen unter Verwendung der file_id anstatt Inhalte erneut hochzuladen
  • Ihre Dateien verwalten mit Auflisten-, Abrufen- und Löschoperationen

​
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:

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"

​
Eine Datei in Nachrichten verwenden

Nach dem Hochladen referenzieren Sie die Datei mit ihrer file_id:

curl -X POST https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Bitte fassen Sie dieses Dokument für mich zusammen."          
          },
          {
            "type": "document",
            "source": {
              "type": "file",
              "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
            }
          }
        ]
      }
    ]
  }'

​
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

​
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 Klartext und fügen Sie den Inhalt direkt in Ihre Nachricht ein:

# Beispiel: Eine Textdatei lesen und als Klartext senden
# Hinweis: Für Dateien mit Sonderzeichen sollten Sie Base64-Kodierung in Betracht ziehen
TEXT_CONTENT=$(cat document.txt | jq -Rs .)

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d @- <<EOF
{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Hier ist der Dokumentinhalt:\n\n${TEXT_CONTENT}\n\nBitte fassen Sie dieses Dokument zusammen."
        }
      ]
    }
  ]
}
EOF

Für .docx-Dateien, die Bilder enthalten, konvertieren Sie sie zuerst in das PDF-Format und verwenden Sie dann die 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": "Dokumenttitel", // Optional
  "context": "Kontext über das Dokument", // Optional  
  "citations": {"enabled": true} // Optional, aktiviert Zitate
}

​
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:

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"

​
Dateimetadaten abrufen

Rufen Sie Informationen über eine bestimmte Datei ab:

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

curl -X DELETE https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w \
  -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ührungstool erstellt wurden:

curl -X GET "https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w/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ührungstool erstellt wurden. Dateien, die Sie hochgeladen haben, können nicht heruntergeladen werden.

​
Dateispeicherung und Limits

​
Speicherlimits

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

​
Dateilebenszyklus

  • 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 über die API kurz nach dem Löschen nicht mehr zugänglich, aber sie können in aktiven Messages-API-Aufrufen und zugehörigen Tool-Verwendungen bestehen bleiben

​
Fehlerbehandlung

Häufige Fehler bei der Verwendung der Files API umfassen:

  • 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 Klartextdatei 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 zu groß (413): Datei überschreitet das 500 MB Limit
  • Speicherlimit überschritten (403): Ihre Organisation hat das 100 GB Speicherlimit erreicht
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Datei nicht gefunden: file_011CNha8iCJcU1wXNR6q4V8w"
  }
}

​
Nutzung und Abrechnung

File API-Operationen sind kostenlos:

  • Dateien hochladen
  • Dateien herunterladen
  • Dateien auflisten
  • Dateimetadaten abrufen
  • Dateien löschen

Dateiinhalte, die in Messages-Anfragen verwendet werden, werden als Eingabe-Token berechnet. Sie können nur Dateien herunterladen, die vom Code-Ausführungstool erstellt wurden.

​
Ratenlimits

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