---
title: Files API
url: https://platform.claude.com/docs/de/build-with-claude/files
description: Lade Dateien einmal hoch, referenziere sie per file_id in Messages-Anfragen und lade Ausgaben herunter, die von Skills oder dem Code-Execution-Tool erstellt wurden.
featureMetadata:
  status: stable
  zdr:
    eligibility: not-eligible
    note: Dateien werden aufbewahrt, bis sie ausdrücklich gelöscht werden oder ihr konfiguriertes Ablaufdatum erreichen.
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: stable
    Claude Platform on AWS: stable
    Claude Models on Google Cloud (Anthropic managed): stable
    Microsoft Foundry (hosted on Anthropic): stable
---

**API-Unterstützung**: Nutzung unterscheidet sich je nach Produkt.

* **Messages API**: Referenziere eine hochgeladene Datei über ihre `file_id` in einem `document`-, `image`- oder `container_upload`-Block.
* **Managed Agents**: Binde Dateien in die Sandbox der Sitzung ein oder referenziere eine `file_id` in einem Event `user.message`.

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-Ausführungstool](https://platform.claude.com/docs/de/agents-and-tools/tool-use/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](https://platform.claude.com/docs/de/api/files/upload).

## Unterstützung von Dateitypen

Das Referenzieren einer `file_id` in einer Messages-Anfrage wird auf allen Modellen unterstützt, die den jeweiligen Dateityp unterstützen. [Bilder](https://platform.claude.com/docs/de/build-with-claude/vision) werden auf allen aktuellen Claude-Modellen unterstützt. Für [PDFs](https://platform.claude.com/docs/de/build-with-claude/pdf-support) und [andere Dateitypen mit dem Code-Execution-Tool](https://platform.claude.com/docs/de/agents-and-tools/tool-use/code-execution-tool#availability-feature-support) findest du die Modellunterstützung auf den verlinkten Seiten.

## So funktioniert die Files API

Die Files API bietet einen Ansatz nach dem Prinzip „einmal erstellen, mehrfach verwenden“ 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-Ausführungstool erstellt wurden
* **Dateien referenzieren** in [Messages](https://platform.claude.com/docs/de/api/messages/create)-Anfragen über die `file_id`, anstatt den Inhalt erneut hochzuladen
* **Deine Dateien verwalten** mit Operationen zum Auflisten, Abrufen und Löschen

<Warning id="workspace-scoped-access" title="Hochgeladene Dateien sind für deinen gesamten Workspace zugänglich">
  Dateien sind nicht auf einen Endnutzer, eine Konversation oder eine Sitzung beschränkt. Jeder API-Key mit Zugriff auf einen Workspace kann auf alle Dateien zugreifen, die in diesen Workspace hochgeladen wurden. Jedes Dienstkonto und jeder Nutzer, dessen Organisationsrolle API-Zugriff erlaubt, kann zusätzlich zu allen Workspaces, denen du ihn hinzufügst, den Standard-Workspace verwenden. Bewahre Dateien, die getrennt bleiben müssen, daher in einem eigenen Workspace auf und greife auf sie nur mit [Keys zu, die auf diesen Workspace beschränkt sind](https://platform.claude.com/docs/de/manage-claude/workspaces#api-keys-and-resource-scoping). Akzeptiere niemals `file_id`-Werte von Endnutzern oder anderen nicht vertrauenswürdigen Quellen: Eine vom Nutzer bereitgestellte Datei-ID würde es einem Nutzer deiner Anwendung ermöglichen, Inhalte zu lesen, die ein anderer Nutzer hochgeladen hat. Behandle Datei-IDs als serverseitige Referenzen und verwalte die Zuordnung zwischen deinen Nutzern und ihren Dateien in deiner Anwendung.

  Wenn du eine mandantenfähige Anwendung auf Basis der Files API erstellst, lege für jeden Mandanten einen separaten [Workspace](https://platform.claude.com/docs/de/manage-claude/workspaces) an. Der Workspace ist die Isolationsgrenze für Dateien, sodass ein Workspace pro Mandant die Daten dieses Mandanten strikt von allen anderen Mandanten isoliert. Jede Organisation kann bis zu 100 Workspaces haben; wende dich an dein Account-Team, wenn du mehr benötigst.
</Warning>

## So verwendest du die Files API

### Eine Datei hochladen

Lade eine Datei hoch, um sie in späteren API-Aufrufen zu referenzieren:

<CodeGroup>
  ```bash cURL
  curl -X POST https://api.anthropic.com/v1/files \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -F "file=@/path/to/document.pdf"
  ```

  ```bash CLI
  ant files upload --file /path/to/document.pdf
  ```

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

  ```typescript TypeScript
  const uploaded = await client.files.upload({
    file: await toFile(createReadStream("/path/to/document.pdf"), undefined, {
      type: "application/pdf"
    })
  });
  console.log(uploaded.id);
  ```

  ```csharp C#
  var uploaded = await client.Files.Upload(
      new FileUploadParams
      {
          File = new BinaryContent
          {
              Stream = File.OpenRead("/path/to/document.pdf"),
              FileName = "document.pdf",
              ContentType = new("application/pdf")
          }
      });

  var fileId = uploaded.ID;
  Console.WriteLine(fileId);
  ```

  ```go Go
  f, err := os.Open("/path/to/document.pdf")
  if err != nil {
  	log.Fatal(err)
  }
  defer f.Close()

  response, err := client.Files.Upload(context.Background(),
  	anthropic.FileUploadParams{
  		File: anthropic.File(f, "document.pdf", "application/pdf"),
  	})
  if err != nil {
  	log.Fatal(err)
  }

  fileID := response.ID
  fmt.Println(fileID)
  ```

  ```java Java
  FileMetadata file = client.files().upload(
      FileUploadParams.builder()
          .file(MultipartField.<InputStream>builder()
              .value(Files.newInputStream(Path.of("/path/to/document.pdf")))
              .filename("document.pdf")
              .contentType("application/pdf")
              .build())
          .build()
  );

  String fileId = file.id();
  IO.println(fileId);
  ```

  ```php PHP
  $document = fopen('/path/to/document.pdf', 'rb')
      ?: throw new \RuntimeException('Could not open /path/to/document.pdf.');

  $file = $client->files->upload(
      file: FileParam::fromResource($document, contentType: 'application/pdf'),
  );

  $fileId = $file->id;
  echo $fileId;
  ```

  ```ruby Ruby
  file = client.files.upload(
    file: Anthropic::FilePart.new(
      Pathname("/path/to/document.pdf"),
      content_type: "application/pdf"
    )
  )

  file_id = file.id
  puts file_id
  ```
</CodeGroup>

Die Antwort auf das Hochladen einer Datei enthält:

```json Response
{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "type": "file",
  "filename": "document.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1024000,
  "created_at": "2025-01-01T00:00:00Z",
  "downloadable": false,
  "expires_at": null
}
```

[`downloadable`](https://platform.claude.com/docs/de/api/files#file_metadata.downloadable) ist für von dir hochgeladene Dateien `false`. Nur Dateien, die von [Skills](https://platform.claude.com/docs/de/build-with-claude/skills-guide) oder dem [Code-Execution-Tool](https://platform.claude.com/docs/de/agents-and-tools/tool-use/code-execution-tool) erstellt wurden, können heruntergeladen werden. Siehe [Eine Datei herunterladen](https://platform.claude.com/docs/de/build-with-claude/files#downloading-a-file).

Die API-Referenz beschreibt jedes Feld des Dateiobjekts.

(See `file_metadata` on `files` in [the API reference](https://platform.claude.com/docs/de/api/files#file_metadata).)

### Eine Datei in Nachrichten verwenden

Nach dem Hochladen referenzierst du die Datei, indem du die `id` aus der Upload-Antwort als `file_id` übergibst:

<CodeGroup>
  ```bash cURL
  curl -X POST https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-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"'"
              }
            }
          ]
        }
      ]
    }'
  ```

  ```bash CLI
  ant messages create <<YAML
  model: claude-opus-5-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
  YAML
  ```

  ```python Python
  response = client.messages.create(
      model="claude-opus-5-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)
  ```

  ```typescript TypeScript
  const response = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    messages: [
      {
        role: "user",
        content: [
          {
            type: "text",
            text: "Please summarize this document for me."
          },
          {
            type: "document",
            source: {
              type: "file",
              file_id: uploaded.id
            }
          }
        ]
      }
    ]
  });

  console.log(response);
  ```

  ```csharp C#
  var response = await client.Messages.Create(
      new MessageCreateParams
      {
          Model = Model.ClaudeOpus5_5,
          MaxTokens = 1024,
          Messages =
          [
              new UserMessageParam
              {
                  Content = new List<ContentBlockParam>
                  {
                      new TextBlockParam { Text = "Please summarize this document for me." },
                      new DocumentBlockParam
                      {
                          Source = new FileDocumentSource { FileID = fileId }
                      }
                  }
              }
          ]
      });

  Console.WriteLine(response);
  ```

  ```go Go
  msg, err := client.Messages.New(context.Background(),
  	anthropic.MessageNewParams{
  		Model:     anthropic.ModelClaudeOpus5_5,
  		MaxTokens: 1024,
  		Messages: []anthropic.MessageParam{
  			anthropic.NewUserMessage(
  				anthropic.NewTextBlock("Please summarize this document for me."),
  				anthropic.NewDocumentBlock(anthropic.FileDocumentSourceParam{
  					FileID: fileID,
  				}),
  			),
  		},
  	})
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Println(msg)
  ```

  ```java Java
  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_OPUS_5_5)
      .maxTokens(1024)
      .addUserMessageOfContentBlockParams(List.of(
          ContentBlockParam.ofText(TextBlockParam.builder()
              .text("Please summarize this document for me.")
              .build()),
          ContentBlockParam.ofDocument(DocumentBlockParam.builder()
              .fileSource(fileId)
              .build())
      ))
      .build();

  Message message = client.messages().create(params);
  IO.println(message);
  ```

  ```php PHP
  $response = $client->messages->create(
      maxTokens: 1024,
      messages: [
          [
              'role' => 'user',
              'content' => [
                  ['type' => 'text', 'text' => 'Please summarize this document for me.'],
                  [
                      'type' => 'document',
                      'source' => [
                          'type' => 'file',
                          'fileID' => $fileId,
                      ],
                  ],
              ],
          ],
      ],
      model: Model::CLAUDE_OPUS_5_5,
  );

  echo $response;
  ```

  ```ruby Ruby
  response = client.messages.create(
    model: Anthropic::Model::CLAUDE_OPUS_5_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
            }
          }
        ]
      }
    ]
  )

  puts response
  ```
</CodeGroup>

### Dateitypen und Content-Blöcke

Die Files API unterstützt verschiedene Dateitypen, die verschiedenen Content-Block-Typen entsprechen:

| Dateityp                                                                                                                                                                                     | MIME-Typ                                             | Content-Block-Typ  | Anwendungsfall                      |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------ | ----------------------------------- |
| PDF                                                                                                                                                                                          | `application/pdf`                                    | `document`         | Textanalyse, Dokumentenverarbeitung |
| Klartext                                                                                                                                                                                     | `text/plain`                                         | `document`         | Textanalyse, Verarbeitung           |
| Bilder                                                                                                                                                                                       | `image/jpeg`, `image/png`, `image/gif`, `image/webp` | `image`            | Bildanalyse, visuelle Aufgaben      |
| Datensätze, Sonstige (siehe [Eigene Dateien hochladen und analysieren](https://platform.claude.com/docs/de/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files)) | Unterschiedlich                                      | `container_upload` | Datenanalyse, Visualisierung        |

#### Document-Blöcke

Verwende für PDFs und Textdateien den `document`-Content-Block:

```json
{
  "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

Verwende für Bilder den `image`-Content-Block:

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

#### Container-Upload-Blöcke

Um [eine Datei an das Code-Ausführungstool zu senden](https://platform.claude.com/docs/de/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files), verwende den `container_upload`-Content-Block:

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

### Mit anderen Dateiformaten arbeiten

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-Ausführungstool mit einem `container_upload`-Block hoch (siehe [Eigene Dateien hochladen und analysieren](https://platform.claude.com/docs/de/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files)).

Die folgenden Beispiele lesen eine Textdatei und senden ihren Inhalt als Klartext:

<CodeGroup>
  ```bash cURL
  # Kodiere den Text der Datei als JSON-String, damit Anführungszeichen und Zeilenumbrüche sicher sind
  TEXT_JSON=$(jq -Rs . document.txt)

  curl https://api.anthropic.com/v1/messages \
    -H "content-type: application/json" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -d @- <<EOF
  {
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "Here's the document content:"},
          {"type": "text", "text": ${TEXT_JSON}},
          {"type": "text", "text": "Please summarize this document."}
        ]
      }
    ]
  }
  EOF
  ```

  ```bash CLI
  # Die Referenz "@./path" fügt den Dateiinhalt direkt inline in das Feld ein.
  ant messages create --model claude-opus-5-5 --max-tokens 1024 <<'YAML'
  messages:
    - role: user
      content:
        - type: text
          text: "Here's the document content:"
        - type: text
          text: "@./document.txt"
        - type: text
          text: "Please summarize this document."
  YAML
  ```

  ```python Python
  client = anthropic.Anthropic()

  # Textdatei lesen
  with open("document.txt") as f:
      text_content = f.read()

  response = client.messages.create(
      model="claude-opus-5-5",
      max_tokens=1024,
      messages=[
          {
              "role": "user",
              "content": [
                  {
                      "type": "text",
                      "text": f"""Here's the document content:

  {text_content}

  Please summarize this document.""",
                  }
              ],
          }
      ],
  )

  for block in response.content:
      if block.type == "text":
          print(block.text)
  ```

  ```typescript TypeScript
  import fs from "node:fs/promises";
  // ...
  const client = new Anthropic();

  // Lies die Textdatei
  const textContent = await fs.readFile("document.txt", "utf-8");

  const response = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    messages: [
      {
        role: "user",
        content: [
          {
            type: "text",
            text: `Here's the document content:

  ${textContent}

  Please summarize this document.`
          }
        ]
      }
    ]
  });

  const textBlock = response.content.find((block) => block.type === "text");
  console.log(textBlock?.text);
  ```

  ```csharp C#
  AnthropicClient client = new();

  // Lies die Textdatei
  string textContent = await File.ReadAllTextAsync("document.txt");

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 1024,
      Messages = [new UserMessageParam
      {
          Content = $"""
              Here's the document content:

              {textContent}

              Please summarize this document.
              """
      }]
  };

  var message = await client.Messages.Create(parameters);
  foreach (var block in message.Content)
  {
      if (block.TryPickText(out var textBlock))
      {
          Console.WriteLine(textBlock.Text);
      }
  }
  ```

  ```go Go
  client := anthropic.NewClient()

  // Lies die Textdatei
  textContent, err := os.ReadFile("document.txt")
  if err != nil {
  	log.Fatal(err)
  }

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 1024,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock(
  			fmt.Sprintf("Here's the document content:\n\n%s\n\nPlease summarize this document.", string(textContent)),
  		)),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }

  for _, block := range response.Content {
  	if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
  		fmt.Println(textBlock.Text)
  	}
  }
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  // Lies die Textdatei ein
  String textContent = Files.readString(Path.of("document.txt"));

  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_OPUS_5_5)
      .maxTokens(1024L)
      .addUserMessage(
          """
          Here's the document content:

          %s

          Please summarize this document.""".formatted(textContent)
      )
      .build();

  Message response = client.messages().create(params);
  response.content().stream()
      .flatMap(block -> block.text().stream())
      .forEach(textBlock -> IO.println(textBlock.text()));
  ```

  ```php PHP
  $client = new Client();

  // Textdatei lesen
  $textContent = file_get_contents('document.txt')
      ?: throw new \RuntimeException('Could not read document.txt.');

  $message = $client->messages->create(
      maxTokens: 1024,
      messages: [
          [
              'role' => 'user',
              'content' => [
                  [
                      'type' => 'text',
                      'text' => <<<TEXT
                          Here's the document content:

                          {$textContent}

                          Please summarize this document.
                          TEXT
                  ]
              ]
          ]
      ],
      model: Model::CLAUDE_OPUS_5_5,
  );

  foreach ($message->content as $block) {
      if ($block instanceof \Anthropic\Messages\TextBlock) {
          echo $block->text, PHP_EOL;
      }
  }
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  # Lies die Textdatei
  text_content = File.read("document.txt")

  message = client.messages.create(
    model: Anthropic::Model::CLAUDE_OPUS_5_5,
    max_tokens: 1024,
    messages: [
      {
        role: "user",
        content: [
          {
            type: "text",
            text: <<~TEXT.chomp
              Here's the document content:

              #{text_content}

              Please summarize this document.
            TEXT
          }
        ]
      }
    ]
  )

  message.content.each do |block|
    puts block.text if block.is_a?(Anthropic::Models::TextBlock)
  end
  ```
</CodeGroup>

<Note>
  Konvertiere .docx-Dateien, die Bilder enthalten, zuerst in das PDF-Format und nutze dann die [PDF-Unterstützung](https://platform.claude.com/docs/de/build-with-claude/pdf-support), um von der integrierten Bildanalyse zu profitieren. Dies ermöglicht die Verwendung von Zitaten aus dem PDF-Dokument.
</Note>

### Dateien verwalten

#### Dateien auflisten

Rufe eine Liste deiner hochgeladenen Dateien ab. Der Endpunkt ist paginiert: Jede Anfrage gibt bis zu [`limit`](https://platform.claude.com/docs/de/api/files/list#list.limit) Dateien zurück (standardmäßig 20, höchstens 1.000), und der [`next_page`](https://platform.claude.com/docs/de/api/files/list#list.response.next_page)-Cursor der Antwort ruft die nächste Seite ab, wenn er als [`page`](https://platform.claude.com/docs/de/api/files/list#list.page)-Parameter wieder übergeben wird. Dateien sind nach Neuheit sortiert, die neuesten zuerst. Siehe die [API-Referenz für „Dateien auflisten“](https://platform.claude.com/docs/de/api/files/list). Das SDK gibt die erste Seite zurück und stellt Hilfsfunktionen für [automatische Paginierung](https://platform.claude.com/docs/de/api/overview#pagination) bereit.

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/files \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21"
  ```

  ```bash CLI
  # List-Befehle paginieren automatisch, daher begrenzt --max-items die Gesamtanzahl
  ant files list --max-items 10
  ```

  ```python Python
  client = anthropic.Anthropic()
  files = client.files.list()
  print(files)
  ```

  ```typescript TypeScript
  const client = new Anthropic();
  const files = await client.files.list();
  console.log(files);
  ```

  ```csharp C#
  AnthropicClient client = new();

  var files = await client.Files.List();
  Console.WriteLine(files);
  ```

  ```go Go
  client := anthropic.NewClient()

  files, err := client.Files.List(context.TODO(), anthropic.FileListParams{})
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(files)
  ```

  ```java Java
  import com.anthropic.models.files.FileListPage;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      FileListPage files = client.files().list();
      IO.println(files);
  }
  ```

  ```php PHP
  $client = new Client();

  $files = $client->files->list();
  echo $files;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  files = client.files.list
  puts files
  ```
</CodeGroup>

Um eine bekannte Menge von Dateien in einer einzigen Anfrage zu prüfen, anstatt zu paginieren, übergib bis zu 100 Datei-IDs als `ids[]`-Query-Parameter. Eine `ids[]`-Anfrage unterscheidet sich in drei Punkten von einer paginierten Liste:

* Du kannst `ids[]` nicht mit `page` oder `limit` kombinieren.
* Die Antwort ist immer eine einzelne Seite (`next_page` ist `null`).
* Wenn eine ID nicht zu einer Datei in deinem Workspace aufgelöst werden kann, lässt die API diese ID aus `data` weg, ohne einen Fehler zurückzugeben. Um die IDs zu finden, die die API weggelassen hat, vergleiche die zurückgegebenen IDs mit den angefragten IDs.

#### Datei-Metadaten abrufen

Rufe Informationen zu einer bestimmten Datei ab:

<CodeGroup>
  ```bash cURL
  curl "https://api.anthropic.com/v1/files/$FILE_ID" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21"
  ```

  ```bash CLI
  ant files retrieve-metadata --file-id "$FILE_ID"
  ```

  ```python Python
  file = client.files.retrieve_metadata(file_id)
  print(file)
  ```

  ```typescript TypeScript
  const file = await client.files.retrieveMetadata(uploaded.id);
  console.log(file);
  ```

  ```csharp C#
  var file = await client.Files.RetrieveMetadata(fileId);
  Console.WriteLine(file);
  ```

  ```go Go
  metadata, err := client.Files.GetMetadata(context.TODO(), fileID, anthropic.FileGetMetadataParams{})
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Println(metadata)
  ```

  ```java Java
  FileMetadata metadata = client.files().retrieveMetadata(fileId);

  IO.println(metadata);
  ```

  ```php PHP
  $file = $client->files->retrieveMetadata($fileId);
  echo $file;
  ```

  ```ruby Ruby
  file = client.files.retrieve_metadata(file_id)
  puts file
  ```
</CodeGroup>

#### Eine Datei löschen

Lösche eine Datei aus deinem Workspace:

<CodeGroup>
  ```bash cURL
  curl -X DELETE "https://api.anthropic.com/v1/files/$FILE_ID" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21"
  ```

  ```bash CLI
  ant files delete --file-id "$FILE_ID"
  ```

  ```python Python
  client.files.delete(file_id)
  ```

  ```typescript TypeScript
  await client.files.delete(uploaded.id);
  ```

  ```csharp C#
  await client.Files.Delete(fileId);
  ```

  ```go Go
  _, err = client.Files.Delete(context.TODO(), fileID, anthropic.FileDeleteParams{})
  if err != nil {
  	log.Fatal(err)
  }
  ```

  ```java Java
  client.files().delete(fileId);
  ```

  ```php PHP
  $client->files->delete($fileId);
  ```

  ```ruby Ruby
  client.files.delete(file_id)
  ```
</CodeGroup>

### Eine Datei herunterladen

Lade Dateien herunter, die [Skills](https://platform.claude.com/docs/de/build-with-claude/skills-guide) oder das [Code-Ausführungstool](https://platform.claude.com/docs/de/agents-and-tools/tool-use/code-execution-tool) erstellt haben. 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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/code-execution-tool#retrieve-generated-files) der Messages-Antwort, die die Datei erstellt hat. Verwende diese `file_id` in der Download-Anfrage:

<CodeGroup>
  ```bash cURL
  curl -X GET "https://api.anthropic.com/v1/files/$FILE_ID/content" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -o downloaded_file.txt
  ```

  ```bash CLI
  ant files download --file-id "$FILE_ID" --output downloaded_file.txt
  ```

  ```python Python
  file_content = client.files.download(file_id)

  file_content.write_to_file("downloaded_file.txt")
  ```

  ```typescript TypeScript
  const content = await client.files.download(fileId);

  await writeFile("downloaded_file.txt", content.body!);
  ```

  ```csharp C#
  using var fileContent = await client.Files.Download(fileId);
  await using var source = await fileContent.ReadAsStream();
  await using var destination = File.Create("downloaded_file.txt");
  await source.CopyToAsync(destination);
  ```

  ```go Go
  func downloadFile(client anthropic.Client, fileID string) error {
  	resp, err := client.Files.Download(context.TODO(), fileID, anthropic.FileDownloadParams{})
  	if err != nil {
  		return err
  	}
  	defer resp.Body.Close()

  	out, err := os.Create("downloaded_file.txt")
  	if err != nil {
  		return err
  	}
  	defer out.Close()

  	_, err = io.Copy(out, resp.Body)
  	return err
  }
  ```

  ```java Java
  try (HttpResponse response = client.files().download(fileId)) {
      try (InputStream body = response.body()) {
          Files.copy(body, Path.of("downloaded_file.txt"),
              StandardCopyOption.REPLACE_EXISTING);
      }
  }
  ```

  ```php PHP
  $fileContent = $client->files->download($fileId);

  file_put_contents('downloaded_file.txt', $fileContent);
  ```

  ```ruby Ruby
  file_content = client.files.download(file_id)

  IO.copy_stream(file_content, "downloaded_file.txt")
  ```
</CodeGroup>

<Note>
  Eine Datei ist nur dann herunterladbar, wenn ihre Metadaten `"downloadable": true` anzeigen, was bei Dateien der Fall ist, die von Skills oder dem Code-Ausführungstool erstellt wurden. Das Herunterladen einer von dir hochgeladenen Datei gibt einen 400-Fehler zurück.
</Note>

Auf der Claude API tragen unterstützte Bild-, Video- und Audiodateien, die Claude mit dem Code-Ausführungstool erzeugt, einschließlich von Skills erstellter Dateien, beim Herunterladen signierte C2PA Content Credentials. Unter [Content Credentials bei generierten Dateien](https://platform.claude.com/docs/de/agents-and-tools/tool-use/code-execution-tool#content-credentials-on-generated-files) erfährst du, was die Credentials enthalten und wie du sie überprüfst.

## Dateispeicher und Limits

### Speicherlimits

* **Maximale Dateigröße:** 500 MB pro Datei
* **Gesamtspeicher:** 1 TB pro Organisation

### Lebenszyklus von Dateien

* Dateien sind auf den Workspace beschränkt, in den sie hochgeladen wurden. Jede Anfrage im selben Workspace kann sie referenzieren; akzeptiere niemals Datei-IDs aus nicht vertrauenswürdigen Quellen (siehe die [Warnung zum Workspace-Zugriff](https://platform.claude.com/docs/de/build-with-claude/files#workspace-scoped-access)).
* 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 oder sie ihr `expires_at` erreichen.
* Gelöschte Dateien können nicht wiederhergestellt werden.
* Dateien sind kurz nach dem Löschen über die API nicht mehr zugänglich, können aber in aktiven Messages-API-Aufrufen und zugehörigen Tool-Nutzungen fortbestehen.
* Dateien, die Nutzer löschen, werden gemäß der [Richtlinie zur Datenaufbewahrung](https://privacy.claude.com/en/articles/7996866-how-long-do-you-store-my-organization-s-data) von Anthropic gelöscht.

### Ablauf von Dateien

Damit eine Datei automatisch abläuft, füge beim Hochladen ein [`expires_in_seconds`](https://platform.claude.com/docs/de/api/files/upload#upload.expires_in_seconds)-Formularfeld hinzu. Der Wert ist eine ganze Zahl von Sekunden zwischen 3.600 (1 Stunde) und 7.776.000 (90 Tage). Der resultierende [`expires_at`](https://platform.claude.com/docs/de/api/files#file_metadata.expires_at)-Zeitstempel (RFC 3339) erscheint in jeder Dateiantwort und ist `null` für Dateien, die ohne Ablaufdatum hochgeladen wurden. Das Ablaufdatum wird einmalig beim Hochladen festgelegt und kann nicht geändert werden.

Wenn eine Datei ihr `expires_at` erreicht:

* Das Herunterladen ihres Inhalts (`GET /v1/files/{file_id}/content`) gibt einen 404-Fehler zurück.
* Eine Messages-Anfrage, die die Datei referenziert, schlägt vor der Inferenz fehl.
* Ihre Metadaten (`GET /v1/files/{file_id}`) bleiben bis zu 30 Tage lang lesbar, wobei `expires_at` in der Vergangenheit liegt.
* Sie erscheint während dieses Zeitraums weiterhin in Listenantworten; vergleiche `expires_at` mit der aktuellen Zeit, um abgelaufene Dateien herauszufiltern.

Das Löschen einer abgelaufenen Datei mit `DELETE /v1/files/{file_id}` entfernt ihre Metadaten sofort, anstatt auf das Verstreichen des 30-Tage-Fensters zu warten.

<Note>
  Der Ablauf ist eine Lebenszyklusfunktion und keine Kontrolle mit garantierter Löschung. Nach `expires_at` ist der Dateiinhalt nicht mehr über die API abrufbar und wird aus deinem Speicherkontingent freigegeben; der zugrunde liegende Inhalt kann danach für einen begrenzten Zeitraum zur Sicherheitsüberprüfung aufbewahrt werden, bevor er dauerhaft gelöscht wird, und die Dateimetadaten bleiben bis zu 30 Tage nach Ablauf sichtbar. Um eine Datei vor ihrem geplanten Ablauf zu löschen, verwende `DELETE /v1/files/{file_id}`.
</Note>

### Audit-Protokollierung

Wenn in deiner Organisation die [Compliance API](https://platform.claude.com/docs/de/manage-claude/compliance-api) aktiviert ist, zeichnet deren [Activity Feed](https://platform.claude.com/docs/de/manage-claude/compliance-activity-feed) Files-API-Operationen auf, die mit einem Claude-API-Key oder aus der Claude Console durchgeführt werden: Jeder Upload (`POST /v1/files`), jeder Inhalts-Download (`GET /v1/files/{file_id}/content`) und jede Löschung (`DELETE /v1/files/{file_id}`) erscheint als Aktivität `platform_file_uploaded`, `platform_file_content_downloaded` oder `platform_file_deleted`. Das Auflisten von Dateien und das Abrufen von Datei-Metadaten werden nicht aufgezeichnet. Operationen, die stattfinden, während die Compliance API deaktiviert ist, werden nicht aufgezeichnet und können später nicht wiederhergestellt werden. [Richte daher die Compliance API ein](https://platform.claude.com/docs/de/manage-claude/compliance-api-access), bevor du dich auf diesen Audit-Trail verlässt. Auf [Claude Platform on AWS](https://platform.claude.com/docs/de/build-with-claude/claude-platform-on-aws#monitoring-and-logging) auditierst du Dateioperationen stattdessen mit AWS-CloudTrail-Datenereignissen.

## Migration von `files-api-2025-04-14`

Die Files API hat die Beta-Phase verlassen und benötigt keinen Beta-Header. Die Migration weg von `files-api-2025-04-14` ist optional: Anfragen, die ihn senden, funktionieren weiter und geben weiterhin die Beta-Antwortformen zurück, sodass eine bestehende Integration weiter funktioniert, bis du sie änderst. Das Entfernen des Headers stellt diese Anfragen auf die auf dieser Seite dokumentierten Formen um:

|                                             | Mit `files-api-2025-04-14`              | Ohne den Header                                                                           |
| ------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------- |
| Listenantwort                               | `{ data, has_more, first_id, last_id }` | `{ data, next_page }`; gib `next_page` als Query-Parameter `page` zurück                  |
| Listen-Cursor                               | `before_id`, `after_id`                 | `page` oder bis zu 100 `ids[]` (`before_id` und `after_id` geben einen 400-Fehler zurück) |
| `expires_at` bei Dateiobjekten              | Nicht zurückgegeben                     | Immer vorhanden; `null`, wenn die Datei keinen Ablauf hat                                 |
| `Content-Type` beim hochgeladenen Dateiteil | Erforderlich                            | Optional; der Typ wird erkannt, wenn er weggelassen wird                                  |

So migrierst du:

1. **Entferne den Beta-Header.** Entferne `anthropic-beta: files-api-2025-04-14` aus deinen Anfragen. Rufe mit dem SDK `client.files` (csharp, go: `client.Files`; java: `client.files()`; php: `$client->files`) statt `client.beta.files` (csharp, go: `client.Beta.Files`; java: `client.beta().files()`; php: `$client->beta->files`) auf; die Beibehaltung von `client.beta.files` (csharp, go: `client.Beta.Files`; java: `client.beta().files()`; php: `$client->beta->files`) funktioniert nur mit den [SDK-Versionen, die den Header nicht mehr senden](https://platform.claude.com/docs/de/build-with-claude/files#sdk-beta-namespace). Frühere Versionen senden ihn von `client.beta.files` (csharp, go: `client.Beta.Files`; java: `client.beta().files()`; php: `$client->beta->files`) aus, selbst wenn du keine Beta-Namen übergibst.
2. **Aktualisiere die Paginierung.** Ersetze `after_id`/`before_id`-Schleifen durch den `page`/`next_page`-Cursor oder verwende die SDK-Hilfsfunktionen zur automatischen Paginierung, die unter [Dateien verwalten](https://platform.claude.com/docs/de/build-with-claude/files#managing-files) gezeigt werden.
3. **Lies `expires_at`.** Das Feld erscheint nur ohne den Header; `null` bedeutet, dass die Datei keinen Ablauf hat (siehe [Ablauf von Dateien](https://platform.claude.com/docs/de/build-with-claude/files#file-expiration)).

### SDK-Beta-Namespace

Das SDK bietet die Files API in zwei Namespaces an. Diese Seite verwendet den stabilen Namespace, und Files-Funktionen, die sich in der Beta-Phase befinden, verwenden den Beta-Namespace.

Ab der Version deines SDK in der folgenden Tabelle unterscheidet sich der Beta-Namespace in zwei Punkten von dem in früheren Versionen:

* Es sendet `files-api-2025-04-14` nicht mehr.
* Es gibt dieselben Formen wie der stabile Namespace zurück, jedoch unter Typnamen mit dem Präfix `Beta`.

Die Tabelle nennt außerdem die Namespace-Namen jedes SDK und wo der Beta-Namespace `anthropic-beta`-Werte entgegennimmt:

| SDK        | Stabiler Namespace | Beta-Namespace                                       | Beta-Namespace geändert in | `anthropic-beta`-Werte gehören in |
| ---------- | ------------------ | ---------------------------------------------------- | -------------------------- | --------------------------------- |
| Python     | `client.files`     | `client.beta.files`                                  | 1.2.0                      | `betas`                           |
| TypeScript | `client.files`     | `client.beta.files`                                  | 0.122.0                    | `betas`                           |
| C#         | `client.Files`     | `client.Beta.Files`                                  | 12.44.0                    | `Betas`                           |
| Go         | `client.Files`     | `client.Beta.Files`                                  | 1.68.0                     | `Betas`                           |
| Java       | `client.files()`   | `client.beta().files()`                              | 2.59.0                     | `.addBeta()`                      |
| PHP        | `$client->files`   | `$client->beta->files` (Klassen in `Anthropic\Beta`) | 0.45.0                     | `betas`                           |
| Ruby       | `client.files`     | `client.beta.files`                                  | 1.67.0                     | `betas`                           |

Verwende für eine Files-Funktion, die sich in der Beta-Phase befindet, den Beta-Namespace und übergib den `anthropic-beta`-Wert der Funktion wie in der Tabelle gezeigt. Zum Beispiel beschränkt `scope_id` unter einem Managed-Agents-Beta-Header eine Dateiliste auf die Dateien einer Sitzung. Wie du `scope_id` verwendest, erfährst du unter [Session-Dateien auflisten und herunterladen](https://platform.claude.com/docs/de/managed-agents/files#listing-and-downloading-session-files).

In Versionen vor der Version deines SDK in der Tabelle entsprechen die Typen des Beta-Namespace den Formen, die `files-api-2025-04-14` zurückgibt. Wenn du von diesen Typen abhängst, bleibe bei einer solchen Version, bis du von ihnen wegmigrierst.

Anfragen, die `anthropic-beta: managed-agents-2026-04-01` ohne `files-api-2025-04-14` tragen, erhalten die Formen auf dieser Seite mit einem Kompatibilitätszugeständnis bei `GET /v1/files`: `before_id` und `after_id` werden weiterhin akzeptiert (nicht kombinierbar mit `page` oder `ids[]`), und die Listenantwort enthält `has_more`, `first_id` und `last_id` neben `next_page`. Spätere Managed-Agents-Beta-Versionen erhalten die einfache Form.

## 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 bei 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-Ausführungstool erstellt wurden, können heruntergeladen werden.
* **Überschreitet die Größe des Kontextfensters (400):** Die Datei ist größer als die Größe des „context window“ (Kontextfenster) (zum Beispiel bei Verwendung einer 500 MB großen Klartextdatei in einer `/v1/messages`-Anfrage).
* **Ungültiger Dateiname (400):** Der Dateiname erfüllt die Längenanforderungen (1–255 Zeichen) nicht oder enthält verbotene Zeichen (`<`, `>`, `:`, `"`, `|`, `?`, `*`, `\`, `/` oder Unicode-Zeichen 0–31).
* **Datei zu groß (413):** Die Datei überschreitet das Limit von 500 MB.
* **Speicherlimit überschritten (400):** Deine Organisation hat das Speicherlimit von 1 TB erreicht.

```json Output
{
  "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 abgerechnet.

### Ratenlimits

Dateibezogene API-Aufrufe sind auf etwa 500 Anfragen pro Minute begrenzt. Um ein höheres Limit anzufragen, [kontaktiere den Vertrieb](mailto:sales@anthropic.com).

## Nächste Schritte

<CardGroup cols={3}>
  <Card title="PDF-Unterstützung" icon="file" href="https://platform.claude.com/docs/de/build-with-claude/pdf-support">
    Verarbeite PDFs mit Claude. Extrahiere Text, analysiere Diagramme und verstehe visuelle Inhalte aus deinen Dokumenten.
  </Card>

  <Card title="Code-Ausführungstool" icon="terminal" href="https://platform.claude.com/docs/de/agents-and-tools/tool-use/code-execution-tool">
    Führe Python- und Bash-Code in einem Sandbox-Container aus, um Daten zu analysieren, Dateien zu generieren und Lösungen iterativ zu verbessern.
  </Card>

  <Card title="Vision" icon="image" href="https://platform.claude.com/docs/de/build-with-claude/vision">
    Verarbeite und analysiere visuelle Eingaben und generiere Text und Code aus Bildern.
  </Card>
</CardGroup>

## Verfügbarkeit

Files API ist auf allen Modellen verfügbar.

### API-Unterstützung

#### [Messages API](https://platform.claude.com/docs/de/build-with-claude/working-with-messages)

* Verfügbarkeit: Verfügbar
* Nutzung: Referenziere eine hochgeladene Datei über ihre `file_id` in einem `document`-, `image`- oder `container_upload`-Block.

| Status    | Cloud-Plattformen                                                                                                                                                                                                                                                                                                                                                                                            |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Verfügbar | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/de/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/de/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Microsoft Foundry (hosted on Anthropic)](https://platform.claude.com/docs/de/build-with-claude/claude-in-microsoft-foundry) |

#### [Managed Agents](https://platform.claude.com/docs/de/managed-agents/overview)

* Verfügbarkeit: Verfügbar
* Nutzung: Binde hochgeladene Dateien als Sitzungsressourcen in die Sandbox der Sitzung ein (schreibgeschützt, unter `/mnt/session/uploads`), oder referenziere eine `file_id` in einem `image`- oder `document`-Block eines Events `user.message`. Dateien, die der Agent nach `/mnt/session/outputs/` schreibt, können mit der Files API heruntergeladen werden.

| Status    | Cloud-Plattformen              |
| --------- | ------------------------------ |
| Verfügbar | Alle unterstützten Plattformen |

### Datenverarbeitung

[Übersicht über die Datenverarbeitung](https://platform.claude.com/docs/de/manage-claude/api-and-data-retention#feature-eligibility)

| Element | Zero Data Retention                                                                                                                                                                                        | HIPAA            |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| Status  | Nicht berechtigt                                                                                                                                                                                           | Nicht berechtigt |
| Details | Dateien werden aufbewahrt, bis sie ausdrücklich gelöscht werden oder ihr konfiguriertes Ablaufdatum erreichen. [Mehr erfahren](https://platform.claude.com/docs/de/build-with-claude/files#data-retention) | —                |

Zutreffende Endpunkte:

* `/v1/files`
