---
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-Ausführungstool erstellt wurden.
featureMetadata:
  status: ga
  zdr: not-eligible
  supportedPlatforms:
    Claude API: ga
    Claude Platform on AWS: ga
    Microsoft Foundry:
      availability: ga
      note: Auf [Microsoft Foundry](https://platform.claude.com/docs/de/build-with-claude/claude-in-microsoft-foundry) erfordert die Files API ein [Hosted on Anthropic-Deployment](https://platform.claude.com/docs/de/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure).
---

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 von allen Modellen unterstützt, die den jeweiligen Dateityp unterstützen. [Bilder](https://platform.claude.com/docs/de/build-with-claude/vision) werden von 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-Ausführungstool](https://platform.claude.com/docs/de/agents-and-tools/tool-use/code-execution-tool#compatibility) 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">
  **Hochgeladene Dateien sind für deinen gesamten Workspace zugänglich und 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 Service-Konto und jeder Nutzer, dessen Organisationsrolle API-Zugriff erlaubt, kann zusätzlich zu jedem Workspace, dem du ihn hinzufügst, den Default Workspace verwenden. Bewahre daher Dateien, die getrennt bleiben müssen, in einem eigenen [Workspace](https://platform.claude.com/docs/de/manage-claude/workspaces#api-keys-and-resource-scoping) auf und greife nur mit Keys darauf zu, die auf diesen Workspace beschränkt sind. 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 halte die Zuordnung zwischen deinen Nutzern und ihren Dateien in deiner Anwendung.

  Wenn du eine mandantenfähige Anwendung auf Basis der Files API entwickelst, erstelle für jeden Mandanten einen separaten [Workspace](https://platform.claude.com/docs/de/manage-claude/workspaces). Der Workspace ist die Isolationsgrenze für Dateien, sodass ein Workspace pro Mandant die Daten jedes Mandanten hart 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 zukünftigen 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: 2023-06-01" \
    -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(fs.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();
  System.out.println(fileId);
  ```

  ```php PHP
  $file = $client->files->upload(
      file: FileParam::fromResource(fopen('/path/to/document.pdf', 'rb'), 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` ist `false` für Dateien, die du hochlädst. Nur Dateien, die von [Skills](https://platform.claude.com/docs/de/build-with-claude/skills-guide) oder dem [Code-Ausführungstool](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).

### 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: 2023-06-01" \
    -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 MessageParam
              {
                  Role = Role.User,
                  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)
      .addUserMessageOfBlockParams(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);
  System.out.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: 'claude-opus-5-5',
  );

  echo $response;
  ```

  ```ruby Ruby
  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
            }
          }
        ]
      }
    ]
  )

  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, andere](https://platform.claude.com/docs/de/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files) | Variiert                                             | `container_upload` | Daten analysieren, Visualisierungen erstellen |

#### 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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files) zu senden, 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 gelesen 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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files) mit einem `container_upload`-Block hoch.

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

<CodeGroup>
  ```bash cURL
  # Textdatei lesen
  # Hinweis: Bei Dateien mit Sonderzeichen solltest du eine Base64-Kodierung in Betracht ziehen
  TEXT_CONTENT=$(cat document.txt)

  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-5-5",
    "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
  ```

  ```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 \
    --transform 'content.#(type=="text").text' \
    --raw-output <<'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 einlesen
  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:\n\n{text_content}\n\nPlease 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:\n\n${textContent}\n\nPlease summarize this document.`
          }
        ]
      }
    ]
  });

  const textBlock = response.content.find(
    (block): block is Anthropic.TextBlock => 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()
      {
          Role = Role.User,
          Content = $"Here's the document content:\n\n{textContent}\n\nPlease 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
  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:\n\n" + textContent + "\n\nPlease summarize this document.")
      .build();

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

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

  // Lies die Textdatei
  $textContent = file_get_contents("document.txt");

  $message = $client->messages->create(
      maxTokens: 1024,
      messages: [
          [
              'role' => 'user',
              'content' => [
                  [
                      'type' => 'text',
                      'text' => "Here's the document content:\n\n{$textContent}\n\nPlease summarize this document."
                  ]
              ]
          ]
      ],
      model: 'claude-opus-5-5',
  );

  foreach ($message->content as $block) {
      if ($block->type === 'text') {
          echo $block->text, PHP_EOL;
      }
  }
  ```

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

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

  message = client.messages.create(
    model: "claude-opus-5-5",
    max_tokens: 1024,
    messages: [
      {
        role: "user",
        content: [
          {
            type: "text",
            text: "Here's the document content:\n\n#{text_content}\n\nPlease summarize this document."
          }
        ]
      }
    ]
  )

  message.content.each do |block|
    puts block.text if block.type == :text
  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` Dateien zurück (standardmäßig 20, höchstens 1.000), und der `next_page`-Cursor der Antwort ruft die nächste Seite ab, wenn er als `page`-Parameter zurückgegeben wird. Dateien werden nach Aktualität sortiert, die neuesten zuerst. Siehe die [List Files API-Referenz](https://platform.claude.com/docs/de/api/files/list). Das SDK gibt die erste Seite zurück und bietet Hilfsfunktionen für [automatische Paginierung](https://platform.claude.com/docs/de/api/overview#pagination). Das CLI-Beispiel begrenzt die Gesamtzahl mit `--max-items`:

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

  ```bash CLI
  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();
      System.out.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 gibt immer eine einzelne Seite zurück (`next_page` ist `null`), und jede ID, die nicht zu einer Datei in deinem Workspace aufgelöst werden kann, wird stillschweigend aus `data` weggelassen; vergleiche die zurückgegebenen IDs mit den angefragten IDs, um fehlende Treffer zu erkennen. `ids[]` kann nicht mit `page` oder `limit` kombiniert werden.

#### 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: 2023-06-01"
  ```

  ```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);

  System.out.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

Entferne 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: 2023-06-01"
  ```

  ```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 von [Skills](https://platform.claude.com/docs/de/build-with-claude/skills-guide) oder dem [Code-Ausführungstool](https://platform.claude.com/docs/de/agents-and-tools/tool-use/code-execution-tool) erstellt wurden. 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 sie erstellt hat:

<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: 2023-06-01" \
    --output 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(uploaded.id);

  const bytes = Buffer.from(await content.arrayBuffer());
  await fsp.writeFile("downloaded_file.txt", bytes);
  ```

  ```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)

  File.binwrite("downloaded_file.txt", file_content.read)
  ```
</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 nicht mehr über die API zugänglich, können aber in aktiven Messages-API-Aufrufen und zugehörigen Tool-Nutzungen weiterbestehen
* Dateien, die Nutzer löschen, werden gemäß der [Datenaufbewahrungsrichtlinie](https://privacy.claude.com/en/articles/7996866-how-long-do-you-store-my-organization-s-data) von Anthropic gelöscht. Zur ZDR-Berechtigung über alle Funktionen hinweg siehe [API und Datenaufbewahrung](https://platform.claude.com/docs/de/manage-claude/api-and-data-retention)

### Ablauf von Dateien

Damit eine Datei automatisch abläuft, füge beim Hochladen ein Formularfeld `expires_in_seconds` hinzu. Der Wert ist eine ganze Zahl von Sekunden zwischen 3.600 (1 Stunde) und 7.776.000 (90 Tage). Der resultierende `expires_at`-Zeitstempel (RFC 3339) erscheint in jeder Dateiantwort und ist `null` für Dateien, die ohne Ablauf hochgeladen wurden. Der Ablauf 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 Zeitfensters 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, 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 Datei-Metadaten bleiben bis zu 30 Tage nach Ablauf sichtbar. Um eine Datei vor ihrem geplanten Ablauf zu entfernen, 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 weiterhin 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 in den SDKs `client.files` statt `client.beta.files` auf; `client.beta.files` beizubehalten funktioniert nur mit den [SDK-Releases, die den Header nicht mehr senden](https://platform.claude.com/docs/de/build-with-claude/files#sdk-beta-namespace). Frühere Releases senden ihn von `client.beta.files` aus auch ohne `betas`-Argument.
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

Ab Python SDK 1.2.0, TypeScript SDK 0.122.0, Go SDK 1.68.0, Java SDK 2.59.0, Ruby SDK 1.67.0 und C# SDK 12.44.0 sendet `client.beta.files` `files-api-2025-04-14` nicht mehr und gibt dieselben Formen wie `client.files` zurück, mit Typnamen mit `Beta`-Präfix. Es akzeptiert ein `betas`-Argument für Files-Funktionen, die sich noch in der Beta-Phase befinden, wie etwa die `scope_id`-Filterung unter einem [Managed Agents](https://platform.claude.com/docs/de/managed-agents/files)-Beta-Header. Frühere SDK-Releases sind auf die Beta-Formen typisiert; wenn du von diesen Typen abhängig bist, bleibe bei einem früheren Release, bis du migrierst.

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 die 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 das „context window“ (Kontextfenster) (zum Beispiel die Verwendung einer 500 MB großen Klartextdatei in einer `/v1/messages`-Anfrage)
* **Ungültiger Dateiname (400):** Der Dateiname erfüllt nicht die Längenanforderungen (1–255 Zeichen) oder enthält unzulässige 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 „rate limit“ (Ratenlimit) 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>