Die Claude Files API ermöglicht es, eine Datei einmalig nach https://api.anthropic.com/v1/files hochzuladen, eine file_id zurückzuerhalten und diese ID in jeder Messages-Anfrage zu referenzieren, anstatt den Inhalt jedes Mal erneut zu senden. Seit dem 20. August 2026 ist sie auf der Claude Platform allgemein verfügbar: kein Beta-Header, 1 TB Speicher pro Organisation und Ratenlimits, die fünfmal höher sind als in der Beta. Anthropic kündigte die Änderung im Beitrag zu Produktionsagenten an, zusammen mit der allgemeinen Verfügbarkeit von Computer Use, dem Browser-Tool und der Skills API.
Dieser Leitfaden behandelt den vollständigen Lebenszyklus: Hochladen, Referenzieren von Dateien in Nachrichten, Herunterladen generierter Ausgaben, Ablauf, das Workspace-Sicherheitsmodell und die Limits, auf die Sie in der Produktion stoßen werden. Da jeder Schritt hier ein HTTP-Aufruf ist, kann Ihr Coding-Agent den gesamten Ablauf in ein Apidog-CLI-Testszenario verwandeln, anstatt einen Haufen einmaliger curl-Befehle.
Was die Files API macht
Die Files API ist eine Speicherschicht für die Claude API, die einmal erstellt und vielfach verwendet wird. Sie löst ein konkretes Kostenproblem: Wenn Ihre App über Hunderte von Anfragen hinweg Fragen zu demselben 40-seitigen PDF stellt, verschwendet das erneute Hochladen dieses PDFs bei jeder Anfrage Bandbreite und verkompliziert Ihren Client-Code. Mit der Files API können Sie:
- Hochladen einer Datei in den Speicher von Anthropic und Erhalt einer eindeutigen
file_id - Referenzieren dieser ID in Messages-Anfragen über einen Content-Block
- Herunterladen von Dateien, die Skills oder das Codeausführungs-Tool generieren (Diagramme, Tabellenkalkulationen, Präsentationen)
- Verwalten von allem mit Listen-, Metadaten-Abruf- und Löschvorgängen
Die Endpoint-Oberfläche ist klein:
| Vorgang | Endpoint |
|---|---|
| Datei hochladen | POST /v1/files |
| Dateien auflisten | GET /v1/files |
| Dateimetadaten abrufen | GET /v1/files/{file_id} |
| Dateiinhalt herunterladen | GET /v1/files/{file_id}/content |
| Datei löschen | DELETE /v1/files/{file_id} |
Alles funktioniert mit den Standard-Headern x-api-key und anthropic-version: 2023-06-01. Wenn Sie mit der Messages API selbst noch nicht vertraut sind, behandelt unser Claude Opus 5 API-Leitfaden die Grundlagen von Authentifizierung und Anfrageaufbau.
Was sich bei der allgemeinen Verfügbarkeit geändert hat
Die Files API verbrachte Monate in der Beta hinter einem Header. Die allgemeine Verfügbarkeit am 20. August 2026 änderte vier Dinge, die für die Produktionsplanung relevant sind:
- Kein Beta-Header. Anfragen funktionieren mit Standard-Headern auf der Claude API.
- 5-mal höhere Ratenlimits. Dateivorgänge erlauben jetzt etwa 500 Anfragen pro Minute, höhere Limits sind über den Vertrieb erhältlich.
- 1 TB Speicher pro Organisation, mit einer Obergrenze von 500 MB pro Datei.
- Breitere Plattformabdeckung. Die Files API läuft direkt auf der Claude API, auf Claude Platform on AWS in der Beta und auf Microsoft Foundry bei Verwendung eines Hosted-on-Anthropic-Deployments. Sie ist nicht auf Amazon Bedrock oder Google Cloud Vertex AI verfügbar und kommt nicht für Vereinbarungen zur Null-Datenaufbewahrung infrage. Planen Sie entsprechend, wenn Sie eine strikte Aufbewahrungsrichtlinie haben.
Eine Datei hochladen
Uploads sind Multipart-Formularanfragen, kein JSON:
curl -X POST https://api.anthropic.com/v1/files \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-F "file=@/path/to/report.pdf"
Die Antwort liefert Ihnen alles, was Sie benötigen, um die Datei später zu referenzieren:
{
"id": "file_011CNha8iCJcU1wXNR6q4V8w",
"type": "file",
"filename": "report.pdf",
"mime_type": "application/pdf",
"size_bytes": 1024000,
"created_at": "2026-08-24T00:00:00Z",
"downloadable": false,
"expires_at": null
}
Zwei Felder verdienen Aufmerksamkeit. downloadable ist false für alles, was Sie hochladen; nur Dateien, die Claude durch Skills oder Codeausführung generiert, können wieder heruntergeladen werden. Und expires_at ist null, es sei denn, Sie legen beim Hochladen einen Ablauf fest (mehr dazu unten).
Im Apidog-CLI-Test weiter unten speichert der Upload-Schritt id als Variable, sodass jede nachfolgende Anfrage {{claude_file_id}} statt einer fest codierten Zeichenkette referenziert.
Dateien in Nachrichten referenzieren
Sobald hochgeladen, wird die Datei über einen von drei Content-Block-Typen in eine Messages-Anfrage eingebunden, je nach Datei:
| Dateityp | MIME-Typ | Content-Block |
|---|---|---|
| PDF, Klartext | application/pdf, text/plain |
document |
| Bilder | image/jpeg, image/png, image/gif, image/webp |
image |
| Datensätze und alles andere | variiert | container_upload (Codeausführungs-Tool) |
Eine PDF-Zusammenfassungsanfrage sieht so aus:
curl -X POST https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5",
"max_tokens": 1024,
"messages": [{
"role": "user",
"content": [
{"type": "text", "text": "Summarize this document."},
{"type": "document", "source": {"type": "file", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"}}
]
}]
}'
Der document-Block akzeptiert außerdem optionale Felder title, context und citations, sodass Sie die Zitationsausgabe für die hochgeladene Datei aktivieren können. Bei Bildern wechseln Sie den Blocktyp zu image mit derselben source-Struktur. Bei Tabellenkalkulationen, CSVs, die analysiert statt gelesen werden sollen, oder jedem Format, das der document-Block nicht annimmt, verwenden Sie container_upload, um die Datei an das Codeausführungs-Tool zu übergeben.
Ein Hinweis zu Formaten: .docx und .xlsx werden vom document-Block nicht direkt unterstützt. Konvertieren Sie Word-Dateien in PDF, um Bildparsing und Zitationen beizubehalten, oder extrahieren Sie den Klartext und senden Sie ihn inline.
Generierte Dateien herunterladen
Der Download-Endpoint existiert für Ausgaben, nicht für Eingaben. Wenn Claude mit Codeausführung ein Diagramm erstellt oder über einen Skill eine Tabellenkalkulation erzeugt, enthält die Antwort eine file_id innerhalb des Blocks bash_code_execution_tool_result. Diese ID ist herunterladbar:
curl "https://api.anthropic.com/v1/files/$FILE_ID/content" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
--output chart.png
Der Versuch, eine von Ihnen hochgeladene Datei herunterzuladen, gibt einen 400 zurück. Prüfen Sie das downloadable-Flag in den Metadaten, bevor Sie Wiederholungslogik darum herum bauen; das spart ein Support-Ticket. Diese Schleife aus Hochladen und Generieren ist das Rückgrat des kürzlich allgemein verfügbar gewordenen Skills-API-Workflows, bei dem Skills Office-Dokumente erzeugen, die Sie über denselben Endpoint herunterladen. Unser Leitfaden zu Claude Skills behandelt, was Skills sind und wie sie ausgeführt werden.
Ablauf und Datei-Lebenszyklus
Dateien bleiben bestehen, bis Sie sie löschen oder bis ein von Ihnen beim Hochladen festgelegter Ablauf eintritt:
- Übergeben Sie
expires_in_secondsbeim Hochladen als Formularfeld. Gültiger Bereich: 3.600 (1 Stunde) bis 7.776.000 (90 Tage). Er wird einmal festgelegt und kann später nicht geändert werden. - Nachdem
expires_atüberschritten ist, geben Inhaltsdownloads 404 zurück, und jede Messages-Anfrage, die die Datei referenziert, schlägt vor der Inferenz fehl. - Metadaten bleiben bis zu 30 Tage nach Ablauf lesbar, und abgelaufene Dateien erscheinen in diesem Zeitfenster weiterhin in Listenantworten. Vergleichen Sie
expires_atbeim Filtern mit der aktuellen Zeit. - Das Löschen einer Datei entfernt sie sofort und kann nicht rückgängig gemacht werden. Abgelaufener Inhalt wird aus Ihrem Speicherkontingent freigegeben, kann aber für eine Sicherheitsüberprüfung kurzzeitig aufbewahrt werden. Der Ablauf ist daher ein Lebenszykluswerkzeug, keine Garantie für die Löschung.
Das Sicherheitsmodell: Dateien sind workspace-gebunden
Dies ist die schärfste Kante der gesamten API. Hochgeladene Dateien sind für Ihren gesamten Workspace zugänglich, nicht auf einen Endbenutzer, eine Konversation oder eine Sitzung beschränkt. Jeder API-Schlüssel im selben Workspace kann jede dort hochgeladene Datei lesen, und alle Schlüssel teilen den Default Workspace Ihrer Organisation, sofern Sie sie nicht anderweitig zuweisen.
Die praktischen Regeln:
- Akzeptieren Sie niemals
file_id-Werte von Endbenutzern. Eine vom Benutzer bereitgestellte ID würde es einem Benutzer Ihrer App ermöglichen, die Uploads eines anderen Benutzers zu lesen. Behandeln Sie Datei-IDs als serverseitige Referenzen und bewahren Sie die Zuordnung von Benutzer zu Datei in Ihrer eigenen Datenbank auf. - Multi-Tenant aufbauen? Ein Workspace pro Tenant. Der Workspace ist die Isolationsgrenze. Jede Organisation erhält bis zu 100 Workspaces, und die Account-Teams von Anthropic können das erhöhen.
Wenn Sie bereits pro Tenant API-Schlüssel für die Kostenzuordnung verfolgen (ein Thema, das wir in wie Sie Ihre Claude-API-Rechnung senken vertiefen), bietet Ihnen dasselbe Workspace-Layout die Dateiisolation kostenlos.
Limits und Abrechnung
Die Zahlen, an denen Sie sich orientieren sollten:
| Limit | Wert |
|---|---|
| Maximale Dateigröße | 500 MB |
| Org-Speicher | 1 TB |
| Datei-API-Ratenlimit | ~500 Anfragen/Minute |
| Dateinamenlänge | 1 bis 255 Zeichen |
| Ablaufbereich | 1 Stunde bis 90 Tage |
Abrechnung ist benutzerfreundlich: Hochladen, Herunterladen, Auflisten und Löschen von Dateien sind alle kostenlos. Sie zahlen nur, wenn Dateiinhalt in eine Messages-Anfrage eingeht, wo er als gewöhnliche Eingabe-Token berechnet wird. Ein 100-seitiges PDF, das in zehn Anfragen referenziert wird, kostet zehnmal dieselben Eingabe-Token; die Files API spart Ihnen Bandbreite und Client-Komplexität, nicht Token-Ausgaben. Um bei den Token zu sparen, kombinieren Sie Dateireferenzen mit Prompt-Caching.
Achten Sie auf diese Fehler: 413, wenn eine Datei 500 MB überschreitet, 400, wenn Ihre Organisation die 1-TB-Obergrenze erreicht, 400, wenn der Dateityp nicht zu seinem Content-Block passt (zum Beispiel ein Bild in einem document-Block), und 404 für IDs außerhalb Ihres Workspace.
Lassen Sie Claude Code die Files API mit der Apidog CLI testen
Die Files API ist ein mehrstufiger, zustandsbehafteter Ablauf und verdient daher einen Regressionstest, keine Shell-Historie. Claude Code oder jeder Coding-Agent kann diesen Test über die Apidog CLI erstellen und ausführen. Einmal einrichten:
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com # pick your agent when prompted
Den Token erhalten Sie in Apidog unter Kontoeinstellungen, API Access Token. Geben Sie dem Agenten dann einen Prompt:
Use Apidog CLI on project <id>. Add the Files API endpoints (upload, list,
metadata, download, delete) and POST /v1/messages, with x-api-key from
{{ANTHROPIC_API_KEY}} and the anthropic-version header. Build a test scenario:
upload with expires_in_seconds=3600 and assert expires_at is set, save the id
as claude_file_id, reference it in a Messages call and assert 200, delete it,
then assert the metadata call returns 404. Run it and summarize any failures.
Die Befehle, die er ausführt, geprüft gegen Apidog CLI 2.2.7:
apidog cli-schema get endpoint-create
apidog endpoint create --project <id> --file files-upload.json
apidog test-scenario create --project <id> --name "Files API lifecycle" --priority 1
apidog test-scenario import-steps <scenarioId> --project <id> --source endpoint \
--ids <uploadId>,<messagesId>,<deleteId>,<metadataId> --sync manual
apidog cli-schema validate test-scenario-update --file lifecycle.json
apidog test-scenario update <scenarioId> --project <id> --file lifecycle.json
apidog run -t <scenarioId> --project <id> -e <envId> \
--env-var "ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY" -r cli,json
Der Agent wiederholt endpoint create für jeden Endpoint und schreibt dann die Variablenextraktion und Assertions in das Szenario, bevor er es ausführt. Ein späterer Wechsel der Testdateien bedeutet, einen Upload-Schritt zu ändern, nicht jede Anfrage. Fragen Sie auch nach einem Mock der Upload-Antwort (apidog mock create), und das Frontend-Team erhält die JSON-Struktur, bevor Ihr Backend-Proxy existiert. Dieselbe apidog run-Zeile mit -r junit lässt sich in CI einbinden; unser Leitfaden Apidog CLI in Claude Code behandelt die Agent-Einrichtung von Anfang bis Ende.
FAQ
Brauche ich noch einen Beta-Header? Nein. Seit der allgemeinen Verfügbarkeit am 20. August 2026 funktioniert die Files API auf der Claude API mit den Standard-Headern x-api-key und anthropic-version. Wenn Ihr SDK oder Proxy noch den alten Files-Beta-Header festlegt, entfernen Sie ihn beim Upgrade.
Kann ich den Inhalt einer Datei aktualisieren? Nein. Dateien sind nach dem Hochladen unveränderlich. Laden Sie eine neue Datei hoch, richten Sie Ihre Referenzen auf die neue ID und löschen Sie die alte.
Funktioniert die Files API auf Bedrock oder Vertex AI? Nein. Sie ist auf der Claude API, Claude Platform on AWS (Beta) und Microsoft Foundry mit einem Hosted-on-Anthropic-Deployment verfügbar. Auf Bedrock und Vertex benötigen Sie weiterhin Inline-Base64-Inhalt.
Ist die Files API dasselbe, was die Skills API für Ausgaben verwendet? Ja. Skills und das Codeausführungs-Tool schreiben ihre generierten Dokumente in denselben Dateispeicher, und Sie laden sie über GET /v1/files/{file_id}/content herunter. Die Skills-API-Seite dieses Workflows lässt sich gut mit automatisierter Testung kombinieren.
Fazit
Die allgemeine Verfügbarkeit der Files API beseitigt die letzte Ausrede, dasselbe Dokument bei jeder Anfrage per Base64 einzufügen. Einmal hochladen, per ID referenzieren, einen Ablauf festlegen und Tenant-Dateien in separaten Workspaces halten. Die API-Oberfläche umfasst fünf Endpoints, und jeder einzelne davon ist in Minuten testbar: Lassen Sie Ihren Coding-Agenten den Ablauf mit der Apidog CLI skripten, die file_id über eine Variable verketten und den gesamten Lebenszyklus in CI einchecken, bevor Ihre Benutzer die Edge Cases für Sie finden.