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.

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.

Funktionsweise der Files API

Die Files API bietet einen einfachen Ansatz zum einmaligen Hochladen und mehrfachen Verwenden von Dateien:

• Dateien hochladen in unseren sicheren Speicher 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, anstatt Inhalte erneut hochzuladen
• Dateien verwalten mit List-, Retrieve- und Delete-Operationen

Verwendung der Files API

Hochladen einer Datei

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"

Die Antwort vom 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
}

Verwenden einer Datei in Nachrichten

Nachdem Sie die Datei hochgeladen haben, referenzieren Sie sie 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-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_011CNha8iCJcU1wXNR6q4V8w"
            }
          }
        ]
      }
    ]
  }'

Dateitypen und Inhaltsblöcke

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

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:

# Beispiel: Lesen einer Textdatei und Senden als Nur-Text
# Hinweis: Für Dateien mit Sonderzeichen sollten Sie Base64-Codierung 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-opus-4-6",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Here's the document content:\n\n${TEXT_CONTENT}\n\nPlease summarize this document."
        }
      ]
    }
  ]
}
EOF

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

Verwalten von Dateien

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"

Datei-Metadaten 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"

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"

Herunterladen einer Datei

Laden Sie Dateien herunter, die von Skills oder dem Code-Ausführungs-Tool 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

Dateispeicherung und Limits

Speicherlimits

• Maximale Dateigröße: 500 MB pro Datei
• Gesamtspeicher: 100 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 einem 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äß unserer Datenspeicherungsrichtlinie gelöscht.

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 die 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 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": "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.

Rate Limits

Während der Beta-Phase:

• Dateibezogene 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