---
title: Files API
url: https://platform.claude.com/docs/ru/build-with-claude/files
description: Загружайте файлы один раз, ссылайтесь на них по file_id в запросах Messages и скачивайте результаты, созданные навыками или инструментом выполнения кода.
featureMetadata:
  status: stable
  zdr:
    eligibility: not-eligible
    note: Файлы хранятся, пока их явно не удалят или пока не истечёт заданный для них срок хранения.
  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**: Использование зависит от продукта.

* **Messages API**: Ссылайтесь на загруженный файл по его `file_id` в блоке `document`, `image` или `container_upload`.
* **Managed Agents**: Монтируйте файлы в песочницу сессии или ссылайтесь на `file_id` в событии `user.message`.

Files API позволяет загружать файлы и управлять ими для использования с Claude API без повторной загрузки содержимого при каждом запросе. Это особенно полезно при использовании [инструмента выполнения кода](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/code-execution-tool) для предоставления входных данных (например, наборов данных и документов) и последующего скачивания результатов (например, диаграмм). В дополнение к этому руководству вы можете [изучить справочник API напрямую](https://platform.claude.com/docs/ru/api/files/upload).

## Поддержка типов файлов

Ссылка на `file_id` в запросе Messages поддерживается на всех моделях, которые поддерживают данный тип файла. [Изображения](https://platform.claude.com/docs/ru/build-with-claude/vision) поддерживаются всеми текущими моделями Claude. Для [PDF](https://platform.claude.com/docs/ru/build-with-claude/pdf-support) и [других типов файлов с инструментом выполнения кода](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/code-execution-tool#availability-feature-support) см. соответствующие страницы, чтобы узнать о поддержке моделей.

## Как работает Files API

Files API предоставляет подход «создать один раз — использовать многократно» для работы с файлами:

* **Загружайте файлы** в защищённое хранилище Anthropic и получайте уникальный `file_id`
* **Скачивайте файлы**, созданные навыками или инструментом выполнения кода
* **Ссылайтесь на файлы** в запросах [Messages](https://platform.claude.com/docs/ru/api/messages/create), используя `file_id` вместо повторной загрузки содержимого
* **Управляйте своими файлами** с помощью операций получения списка, извлечения и удаления

<Warning id="workspace-scoped-access" title="Загруженные файлы доступны всему вашему рабочему пространству">
  Файлы не привязаны к конечному пользователю, беседе или сеансу. Любой ключ API с доступом к рабочему пространству может получить доступ к любым файлам, загруженным в это рабочее пространство. Каждая сервисная учётная запись и каждый пользователь, чья роль в организации разрешает доступ к API, могут использовать рабочее пространство по умолчанию (Default Workspace) в дополнение к любому рабочему пространству, в которое вы их добавите, поэтому храните файлы, которые должны оставаться изолированными, в отдельном рабочем пространстве и обращайтесь к ним только с помощью [ключей, ограниченных этим рабочим пространством](https://platform.claude.com/docs/ru/manage-claude/workspaces#api-keys-and-resource-scoping). Никогда не принимайте значения `file_id` от конечных пользователей или других ненадёжных источников: идентификатор файла, предоставленный пользователем, позволил бы одному пользователю вашего приложения прочитать содержимое, загруженное другим пользователем. Рассматривайте идентификаторы файлов как серверные ссылки и храните сопоставление между вашими пользователями и их файлами в своём приложении.

  Если вы создаёте мультитенантное приложение на основе Files API, создайте отдельное [рабочее пространство](https://platform.claude.com/docs/ru/manage-claude/workspaces) для каждого арендатора (tenant). Рабочее пространство является границей изоляции для файлов, поэтому отдельное рабочее пространство для каждого арендатора обеспечивает жёсткую изоляцию данных этого арендатора от всех остальных. Каждая организация может иметь до 100 рабочих пространств; если вам нужно больше, свяжитесь с вашей командой по работе с клиентами.
</Warning>

## Как использовать Files API

### Загрузка файла

Загрузите файл, чтобы ссылаться на него в будущих вызовах API:

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

Ответ на загрузку файла включает:

```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/ru/api/files#file_metadata.downloadable) имеет значение `false` для загруженных вами файлов. Скачать можно только файлы, созданные [навыками](https://platform.claude.com/docs/ru/build-with-claude/skills-guide) или [инструментом выполнения кода](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/code-execution-tool). См. раздел [Скачивание файла](https://platform.claude.com/docs/ru/build-with-claude/files#downloading-a-file).

Справочник API описывает каждое поле объекта файла.

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

### Использование файла в сообщениях

После загрузки ссылайтесь на файл, передавая `id` из ответа на загрузку в качестве `file_id`:

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

### Типы файлов и блоки содержимого

Files API поддерживает различные типы файлов, которые соответствуют различным типам блоков содержимого:

| Тип файла                                                                                                                                                                               | MIME-тип                                             | Тип блока содержимого | Сценарий использования                |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | --------------------- | ------------------------------------- |
| PDF                                                                                                                                                                                     | `application/pdf`                                    | `document`            | Анализ текста, обработка документов   |
| Простой текст                                                                                                                                                                           | `text/plain`                                         | `document`            | Анализ текста, обработка              |
| Изображения                                                                                                                                                                             | `image/jpeg`, `image/png`, `image/gif`, `image/webp` | `image`               | Анализ изображений, визуальные задачи |
| Наборы данных, прочее (см. [Загрузка и анализ собственных файлов](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files)) | Различается                                          | `container_upload`    | Анализ данных, визуализация           |

#### Блоки документов

Для PDF и текстовых файлов используйте блок содержимого `document`:

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

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

#### Блоки загрузки в контейнер

Чтобы [отправить файл инструменту выполнения кода](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files), используйте блок контента `container_upload`:

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

### Работа с другими форматами файлов

Для типов файлов, которые не поддерживаются блоком `document` (например, .docx и .xlsx), преобразуйте файлы в обычный текст и включите содержимое непосредственно в сообщение. Файлы, которые уже являются обычным текстом, например файлы .csv и .md, можно либо прочитать таким образом, либо загрузить через Files API с явным указанием типа содержимого `text/plain`. Чтобы анализировать наборы данных, а не читать их как текст, загрузите их для инструмента выполнения кода с помощью блока `container_upload` (см. [Загрузка и анализ собственных файлов](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files)).

Следующие примеры читают текстовый файл и отправляют его содержимое как простой текст:

<CodeGroup>
  ```bash cURL
  # Кодируем текст файла как строку JSON, чтобы кавычки и переносы строк были безопасны
  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
  # Ссылка "@./path" встраивает содержимое файла непосредственно в поле.
  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()

  # Прочитать текстовый файл
  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();

  // Чтение текстового файла
  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();

  // Прочитать текстовый файл
  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()

  // Чтение текстового файла
  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();

  // Чтение текстового файла
  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();

  // Чтение текстового файла
  $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

  # Прочитать текстовый файл
  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>
  Для файлов .docx, содержащих изображения, сначала преобразуйте их в формат PDF, а затем используйте [поддержку PDF](https://platform.claude.com/docs/ru/build-with-claude/pdf-support), чтобы воспользоваться встроенным разбором изображений. Это позволяет использовать цитаты из PDF-документа.
</Note>

### Управление файлами

#### Получение списка файлов

Получите список загруженных вами файлов. Эндпоинт использует пагинацию: каждый запрос возвращает до [`limit`](https://platform.claude.com/docs/ru/api/files/list#list.limit) файлов (по умолчанию 20, максимум 1 000), а курсор [`next_page`](https://platform.claude.com/docs/ru/api/files/list#list.response.next_page) из ответа позволяет получить следующую страницу, если передать его обратно в параметре [`page`](https://platform.claude.com/docs/ru/api/files/list#list.page). Файлы упорядочены от новых к старым. См. [справочник API «Список файлов»](https://platform.claude.com/docs/ru/api/files/list). SDK возвращает первую страницу и предоставляет вспомогательные средства [автоматической пагинации](https://platform.claude.com/docs/ru/api/overview#pagination).

<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 автоматически разбивают вывод на страницы, поэтому --max-items ограничивает общее число
  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>

Чтобы проверить известный набор файлов одним запросом вместо постраничного перебора, передайте до 100 идентификаторов файлов в виде параметров запроса `ids[]`. Запрос с `ids[]` отличается от постраничного получения списка в трёх отношениях:

* `ids[]` нельзя комбинировать с `page` или `limit`.
* Ответ всегда состоит из одной страницы (`next_page` равен `null`).
* Если идентификатор не соответствует файлу в вашем рабочем пространстве, API исключает этот идентификатор из `data`, не возвращая ошибку. Чтобы найти идентификаторы, которые API исключил, сравните возвращённые идентификаторы с запрошенными.

#### Получение метаданных файла

Получите информацию о конкретном файле:

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

#### Удаление файла

Удалите файл из своего рабочего пространства:

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

### Скачивание файла

Скачивайте файлы, которые создали [навыки](https://platform.claude.com/docs/ru/build-with-claude/skills-guide) или [инструмент выполнения кода](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/code-execution-tool). Файлы, которые вы загружаете, скачать нельзя. `file_id` сгенерированного файла появляется в [блоке содержимого `bash_code_execution_tool_result`](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/code-execution-tool#retrieve-generated-files) ответа Messages, который создал этот файл. Используйте этот `file_id` в запросе на скачивание:

<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>
  Файл можно скачать только тогда, когда в его метаданных указано `"downloadable": true`, что справедливо для файлов, созданных навыками или инструментом выполнения кода. Попытка скачать загруженный вами файл возвращает ошибку 400.
</Note>

В Claude API поддерживаемые файлы изображений, видео и аудио, которые Claude создаёт с помощью инструмента выполнения кода, включая файлы, созданные навыками, при скачивании содержат подписанные учётные данные содержимого C2PA (Content Credentials). О том, что содержат эти учётные данные и как их проверить, см. в разделе [Content Credentials в сгенерированных файлах](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/code-execution-tool#content-credentials-on-generated-files).

## Хранение файлов и ограничения

### Ограничения хранилища

* **Максимальный размер файла:** 500 МБ на каждый файл
* **Общий объём хранилища:** 1 ТБ на каждую организацию

### Жизненный цикл файла

* Файлы привязаны к рабочему пространству, в которое они были загружены. Любой запрос в том же рабочем пространстве может ссылаться на них; никогда не принимайте идентификаторы файлов из ненадёжных источников (см. [предупреждение о доступе в рабочем пространстве](https://platform.claude.com/docs/ru/build-with-claude/files#workspace-scoped-access)).
* Файлы нельзя изменить или переименовать после загрузки. Чтобы изменить содержимое файла, загрузите новый файл и удалите старый.
* Файлы хранятся до тех пор, пока вы не удалите их с помощью эндпоинта `DELETE /v1/files/{file_id}` или пока не наступит их `expires_at`.
* Удалённые файлы невозможно восстановить.
* Файлы становятся недоступны через API вскоре после удаления, но могут сохраняться в активных вызовах Messages API и связанных с ними случаях использования инструментов.
* Файлы, удалённые пользователями, будут удалены в соответствии с [политикой хранения данных](https://privacy.claude.com/en/articles/7996866-how-long-do-you-store-my-organization-s-data) Anthropic.

### Истечение срока действия файла

Чтобы срок действия файла истекал автоматически, добавьте поле формы [`expires_in_seconds`](https://platform.claude.com/docs/ru/api/files/upload#upload.expires_in_seconds) при его загрузке. Значение — целое число секунд от 3 600 (1 час) до 7 776 000 (90 дней). Полученная временная метка [`expires_at`](https://platform.claude.com/docs/ru/api/files#file_metadata.expires_at) (RFC 3339) присутствует в каждом ответе с файлом и имеет значение `null` для файлов, загруженных без срока действия. Срок действия задаётся один раз при загрузке и не может быть изменён.

Когда файл достигает своего `expires_at`:

* Скачивание его содержимого (`GET /v1/files/{file_id}/content`) возвращает ошибку 404.
* Запрос Messages, ссылающийся на этот файл, завершается ошибкой до начала инференса.
* Его метаданные (`GET /v1/files/{file_id}`) остаются доступными для чтения в течение до 30 дней, при этом `expires_at` указывает на прошедшее время.
* В течение этого периода файл продолжает отображаться в ответах со списком файлов; чтобы отфильтровать файлы с истёкшим сроком действия, сравнивайте `expires_at` с текущим временем.

Удаление файла с истёкшим сроком действия с помощью `DELETE /v1/files/{file_id}` немедленно удаляет его метаданные, не дожидаясь окончания 30-дневного периода.

<Note>
  Истечение срока действия — это функция жизненного цикла, а не механизм гарантированного удаления. После `expires_at` содержимое файла больше нельзя получить через API, и оно больше не учитывается в вашей квоте хранилища; базовое содержимое может храниться ещё ограниченный период для проверки безопасности перед окончательным удалением, а метаданные файла остаются видимыми в течение до 30 дней после истечения срока действия. Чтобы удалить файл до запланированного истечения срока действия, используйте `DELETE /v1/files/{file_id}`.
</Note>

### Журнал аудита

Если в вашей организации включён [Compliance API](https://platform.claude.com/docs/ru/manage-claude/compliance-api), его [Activity Feed](https://platform.claude.com/docs/ru/manage-claude/compliance-activity-feed) (лента активности) записывает операции Files API, выполненные с помощью ключа API Claude или из Claude Console: каждая загрузка (`POST /v1/files`), скачивание содержимого (`GET /v1/files/{file_id}/content`) и удаление (`DELETE /v1/files/{file_id}`) отображаются как активность `platform_file_uploaded`, `platform_file_content_downloaded` или `platform_file_deleted`. Получение списка файлов и извлечение метаданных файлов не записываются. Операции, выполненные при выключенном Compliance API, не записываются и не могут быть восстановлены позже, поэтому [настройте Compliance API](https://platform.claude.com/docs/ru/manage-claude/compliance-api-access), прежде чем полагаться на этот журнал аудита. На [Claude Platform on AWS](https://platform.claude.com/docs/ru/build-with-claude/claude-platform-on-aws#monitoring-and-logging) вместо этого проводите аудит операций с файлами с помощью событий данных AWS CloudTrail.

## Миграция с `files-api-2025-04-14`

Files API вышел из бета-версии и не требует бета-заголовка. Миграция с `files-api-2025-04-14` необязательна: запросы, которые его отправляют, продолжают работать и продолжают возвращать формы ответов бета-версии, поэтому существующая интеграция продолжает работать, пока вы её не измените. Удаление заголовка переключает эти запросы на формы, описанные на этой странице:

|                                             | С `files-api-2025-04-14`                | Без заголовка                                                                            |
| ------------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------- |
| Ответ со списком                            | `{ data, has_more, first_id, last_id }` | `{ data, next_page }`; передайте `next_page` обратно в качестве параметра запроса `page` |
| Курсоры списка                              | `before_id`, `after_id`                 | `page` или до 100 `ids[]` (`before_id` и `after_id` возвращают ошибку 400)               |
| `expires_at` в объектах файлов              | Не возвращается                         | Всегда присутствует; `null`, если у файла нет срока действия                             |
| `Content-Type` в части с загружаемым файлом | Обязателен                              | Необязателен; при отсутствии тип определяется автоматически                              |

Для миграции:

1. **Удалите бета-заголовок.** Уберите `anthropic-beta: files-api-2025-04-14` из своих запросов. При использовании SDK вызывайте `client.files` (csharp, go: `client.Files`; java: `client.files()`; php: `$client->files`) вместо `client.beta.files` (csharp, go: `client.Beta.Files`; java: `client.beta().files()`; php: `$client->beta->files`); сохранение `client.beta.files` (csharp, go: `client.Beta.Files`; java: `client.beta().files()`; php: `$client->beta->files`) работает только в [выпусках SDK, которые больше не отправляют этот заголовок](https://platform.claude.com/docs/ru/build-with-claude/files#sdk-beta-namespace). Более ранние выпуски отправляют его из `client.beta.files` (csharp, go: `client.Beta.Files`; java: `client.beta().files()`; php: `$client->beta->files`), даже если вы не передаёте имена бета-функций.
2. **Обновите пагинацию.** Замените циклы с `after_id`/`before_id` на курсор `page`/`next_page` или используйте вспомогательные средства автоматической пагинации SDK, показанные в разделе [Управление файлами](https://platform.claude.com/docs/ru/build-with-claude/files#managing-files).
3. **Читайте `expires_at`.** Поле появляется только без заголовка; `null` означает, что у файла нет срока действия (см. [Истечение срока действия файла](https://platform.claude.com/docs/ru/build-with-claude/files#file-expiration)).

### Пространство имён beta в SDK

SDK предоставляет Files API в двух пространствах имён. На этой странице используется стабильное пространство имён, а функции Files, находящиеся в бета-версии, используют бета-пространство имён.

Начиная с выпуска вашего SDK, указанного в следующей таблице, бета-пространство имён отличается от такового в более ранних выпусках в двух отношениях:

* Больше не отправляет `files-api-2025-04-14`.
* Возвращает те же форматы, что и стабильное пространство имён, но с именами типов с префиксом `Beta`.

В таблице также приведены имена пространств имён каждого SDK и то, где бета-пространство имён принимает значения `anthropic-beta`:

| SDK        | Стабильное пространство имён | Бета-пространство имён                             | Бета-пространство имён изменено в выпуске | Куда передаются значения `anthropic-beta` |
| ---------- | ---------------------------- | -------------------------------------------------- | ----------------------------------------- | ----------------------------------------- |
| 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` (классы в `Anthropic\Beta`) | 0.45.0                                    | `betas`                                   |
| Ruby       | `client.files`               | `client.beta.files`                                | 1.67.0                                    | `betas`                                   |

Для функции Files, находящейся в бета-версии, используйте бета-пространство имён и передавайте значение `anthropic-beta` этой функции, как показано в таблице. Например, с бета-заголовком Managed Agents `scope_id` ограничивает список файлов файлами одного сеанса. Чтобы использовать `scope_id`, см. [Получение списка и скачивание файлов сессии](https://platform.claude.com/docs/ru/managed-agents/files#listing-and-downloading-session-files).

В выпусках, предшествующих выпуску вашего SDK в таблице, типы бета-пространства имён соответствуют форматам, которые возвращает `files-api-2025-04-14`. Если вы зависите от этих типов, оставайтесь на таком выпуске до завершения миграции с них.

Запросы, содержащие `anthropic-beta: managed-agents-2026-04-01` без `files-api-2025-04-14`, получают формы, описанные на этой странице, с одним послаблением для совместимости в `GET /v1/files`: `before_id` и `after_id` по-прежнему принимаются (не комбинируются с `page` или `ids[]`), а ответ со списком включает `has_more`, `first_id` и `last_id` наряду с `next_page`. Более поздние бета-версии Managed Agents получают обычную форму.

## Обработка ошибок

Распространённые ошибки при использовании Files API включают:

* **Файл не найден (404):** указанный `file_id` не существует, или у вас нет к нему доступа.
* **Недопустимый тип файла (400):** тип файла не соответствует типу блока контента (например, файл изображения используется в блоке документа).
* **Файл нельзя скачать (400):** загруженные вами файлы имеют `"downloadable": false` и не могут быть скачаны. Скачать можно только файлы, созданные навыками или инструментом выполнения кода.
* **Превышен размер контекстного окна (400):** файл больше размера «context window» (контекстного окна) (например, при использовании текстового файла размером 500 МБ в запросе `/v1/messages`).
* **Недопустимое имя файла (400):** имя файла не соответствует требованиям к длине (1–255 символов) или содержит запрещённые символы (`<`, `>`, `:`, `"`, `|`, `?`, `*`, `\`, `/` или символы Unicode 0–31).
* **Файл слишком большой (413):** файл превышает ограничение в 500 МБ.
* **Превышено ограничение хранилища (400):** ваша организация достигла ограничения хранилища в 1 ТБ.

```json Output
{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "File `file_011CNha8iCJcU1wXNR6q4V8w` not found."
  },
  "request_id": "req_011CQFYcrRp7mCHLDsAYT8Qt"
}
```

## Использование и тарификация

Операции Files API бесплатны:

* Загрузка файлов
* Скачивание файлов
* Получение списка файлов
* Получение метаданных файлов
* Удаление файлов

Содержимое файлов, используемое в запросах Messages, тарифицируется как входные токены.

### Ограничения скорости

Вызовы API, связанные с файлами, ограничены приблизительно 500 запросами в минуту. Чтобы запросить более высокое ограничение, [свяжитесь с отделом продаж](mailto:sales@anthropic.com).

## Следующие шаги

<CardGroup cols={3}>
  <Card title="Поддержка PDF" icon="file" href="https://platform.claude.com/docs/ru/build-with-claude/pdf-support">
    Обрабатывайте PDF с помощью Claude. Извлекайте текст, анализируйте диаграммы и понимайте визуальное содержимое ваших документов.
  </Card>

  <Card title="Инструмент выполнения кода" icon="terminal" href="https://platform.claude.com/docs/ru/agents-and-tools/tool-use/code-execution-tool">
    Запускайте код на Python и Bash в изолированном контейнере, чтобы анализировать данные, создавать файлы и итеративно совершенствовать решения.
  </Card>

  <Card title="Зрение" icon="image" href="https://platform.claude.com/docs/ru/build-with-claude/vision">
    Обрабатывайте и анализируйте визуальные входные данные и генерируйте текст и код из изображений.
  </Card>
</CardGroup>

## Доступность

Files API находится в доступе для всех моделей.

### Поддержка API

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

* Доступность: Доступно
* Использование: Ссылайтесь на загруженный файл по его `file_id` в блоке `document`, `image` или `container_upload`.

| Статус   | Облачные платформы                                                                                                                                                                                                                                                                                                                                                                                           |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Доступно | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/ru/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/ru/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Microsoft Foundry (hosted on Anthropic)](https://platform.claude.com/docs/ru/build-with-claude/claude-in-microsoft-foundry) |

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

* Доступность: Доступно
* Использование: Монтируйте загруженные файлы в песочницу сессии как ресурсы сессии (только для чтения, в `/mnt/session/uploads`) или ссылайтесь на `file_id` в блоке `image` или `document` события `user.message`. Файлы, которые агент записывает в `/mnt/session/outputs/`, можно скачать с помощью Files API.

| Статус   | Облачные платформы           |
| -------- | ---------------------------- |
| Доступно | Все поддерживаемые платформы |

### Обработка данных

[Обзор обработки данных](https://platform.claude.com/docs/ru/manage-claude/api-and-data-retention#feature-eligibility)

| Элемент     | Нулевое хранение данных                                                                                                                                                            | HIPAA          |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| Статус      | Не допускается                                                                                                                                                                     | Не допускается |
| Подробности | Файлы хранятся, пока их явно не удалят или пока не истечёт заданный для них срок хранения. [Подробнее](https://platform.claude.com/docs/ru/build-with-claude/files#data-retention) | —              |

Применимые конечные точки:

* `/v1/files`
