---
title: Files API
url: https://platform.claude.com/docs/ru/build-with-claude/files
description: Загружайте файлы один раз, ссылайтесь на них по file_id в запросах Messages и скачивайте выходные файлы, созданные навыками или инструментом выполнения кода.
featureMetadata:
status: ga
zdr: not-eligible
supportedPlatforms:
Claude API: ga
Claude Platform on AWS: ga
Microsoft Foundry:
availability: ga
note: В [Microsoft Foundry](https://platform.claude.com/docs/ru/build-with-claude/claude-in-microsoft-foundry) для Files API требуется [развёртывание Hosted on Anthropic](https://platform.claude.com/docs/ru/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure).
---
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#compatibility) см. связанные страницы с информацией о поддержке моделей.
## Как работает Files API
Files API предоставляет подход «создать один раз — использовать многократно» для работы с файлами:
* **Загружайте файлы** в защищённое хранилище Anthropic и получайте уникальный `file_id`
* **Скачивайте файлы**, созданные навыками или инструментом выполнения кода
* **Ссылайтесь на файлы** в запросах [Messages](https://platform.claude.com/docs/ru/api/messages/create), используя `file_id` вместо повторной загрузки содержимого
* **Управляйте своими файлами** с помощью операций получения списка, извлечения и удаления
**Загруженные файлы доступны всему вашему рабочему пространству (workspace), а не ограничены конечным пользователем, разговором или сеансом.** Любой ключ 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) для каждого арендатора. Рабочее пространство является границей изоляции для файлов, поэтому отдельное рабочее пространство для каждого арендатора обеспечивает жёсткую изоляцию данных каждого арендатора от всех остальных. Каждая организация может иметь до 100 рабочих пространств; свяжитесь с вашей командой по работе с клиентами, если вам нужно больше.
## Как использовать Files API
### Загрузка файла
Загрузите файл, на который можно будет ссылаться в будущих вызовах API:
```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.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
```
Ответ на загрузку файла включает:
```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` имеет значение `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).
### Использование файла в сообщениях
После загрузки ссылайтесь на файл, передавая `id` из ответа на загрузку в качестве `file_id`:
```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 <
{
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
```
### Типы файлов и блоки содержимого
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`. Чтобы анализировать наборы данных, а не читать их как текст, загрузите их для [инструмента выполнения кода](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files) с помощью блока `container_upload`.
Следующие примеры читают текстовый файл и отправляют его содержимое как простой текст:
```bash cURL
# Чтение текстового файла
# Примечание: для файлов со специальными символами рекомендуется кодирование base64
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 @- < 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()
{
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()
// Чтение текстового файла
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:\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();
// Прочитать текстовый файл
$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
# Прочитать текстовый файл
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
```
Для файлов .docx, содержащих изображения, сначала преобразуйте их в формат PDF, а затем используйте [поддержку PDF](https://platform.claude.com/docs/ru/build-with-claude/pdf-support), чтобы воспользоваться встроенным разбором изображений. Это позволяет использовать цитаты из PDF-документа.
### Управление файлами
#### Получение списка файлов
Получите список загруженных вами файлов. Эндпоинт поддерживает пагинацию: каждый запрос возвращает до `limit` файлов (по умолчанию 20, максимум 1 000), а курсор `next_page` из ответа позволяет получить следующую страницу, если передать его обратно в параметре `page`. Файлы упорядочены от новых к старым. См. [справочник List Files API](https://platform.claude.com/docs/ru/api/files/list). SDK возвращает первую страницу и предоставляет вспомогательные средства [автоматической пагинации](https://platform.claude.com/docs/ru/api/overview#pagination). В примере для CLI общее количество ограничивается с помощью `--max-items`:
```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
```
Чтобы проверить известный набор файлов одним запросом вместо постраничного перебора, передайте до 100 идентификаторов файлов в виде параметров запроса `ids[]`. Запрос с `ids[]` всегда возвращает одну страницу (`next_page` равен `null`), а любой идентификатор, который не соответствует файлу в вашем рабочем пространстве, молча исключается из `data`; сравните возвращённые идентификаторы с запрошенными, чтобы обнаружить отсутствующие. `ids[]` нельзя комбинировать с `page` или `limit`.
#### Получение метаданных файла
Получите информацию о конкретном файле:
```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
```
#### Удаление файла
Удалите файл из вашего рабочего пространства:
```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)
```
### Скачивание файла
Скачивайте файлы, созданные [навыками](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, который его создал:
```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)
```
Файл можно скачать только тогда, когда в его метаданных указано `"downloadable": true`, что справедливо для файлов, созданных навыками или инструментом выполнения кода. Попытка скачать загруженный вами файл возвращает ошибку 400.
В 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. О соответствии требованиям ZDR для всех функций см. [API и хранение данных](https://platform.claude.com/docs/ru/manage-claude/api-and-data-retention)
### Истечение срока действия файла
Чтобы срок действия файла истекал автоматически, включите поле формы `expires_in_seconds` при его загрузке. Значение — целое число секунд от 3 600 (1 час) до 7 776 000 (90 дней). Результирующая временная метка `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-дневного периода.
Истечение срока действия — это функция жизненного цикла, а не средство гарантированного удаления. После `expires_at` содержимое файла больше нельзя получить через API, и оно освобождается из вашей квоты хранилища; базовое содержимое может храниться в течение ограниченного периода после этого для проверки безопасности перед окончательным удалением, а метаданные файла остаются видимыми до 30 дней после истечения срока действия. Чтобы удалить файл до запланированного истечения срока действия, используйте `DELETE /v1/files/{file_id}`.
### Журнал аудита
Если в вашей организации включён [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` вместо `client.beta.files`; сохранение `client.beta.files` работает только в [выпусках SDK, которые больше не отправляют заголовок](https://platform.claude.com/docs/ru/build-with-claude/files#sdk-beta-namespace). Более ранние выпуски отправляют его из `client.beta.files` даже без аргумента `betas`.
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
Начиная с 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 и C# SDK 12.44.0, `client.beta.files` больше не отправляет `files-api-2025-04-14` и возвращает те же формы, что и `client.files`, с именами типов с префиксом `Beta`. Он принимает аргумент `betas` для функций Files, которые всё ещё находятся в бета-версии, таких как фильтрация по `scope_id` под бета-заголовком [Managed Agents](https://platform.claude.com/docs/ru/managed-agents/files). Более ранние выпуски SDK типизированы под формы бета-версии; если вы зависите от этих типов, оставайтесь на более раннем выпуске до миграции.
Запросы, содержащие `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 запросами в минуту. Чтобы запросить более высокое ограничение скорости (rate limit), [свяжитесь с отделом продаж](mailto:sales@anthropic.com).
## Следующие шаги
Обрабатывайте PDF с помощью Claude. Извлекайте текст, анализируйте диаграммы и понимайте визуальное содержимое ваших документов.
Запускайте код Python и bash в изолированном контейнере для анализа данных, генерации файлов и итеративной работы над решениями.
Обрабатывайте и анализируйте визуальные входные данные и генерируйте текст и код из изображений.