Files API

Files API позволяет загружать файлы и управлять ими для использования с Claude API без повторной загрузки содержимого при каждом запросе. Это особенно полезно при использовании инструмента выполнения кода для предоставления входных данных (например, наборов данных и документов) и последующего скачивания результатов (например, диаграмм). В дополнение к этому руководству вы можете изучить справочник API напрямую.

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

Ссылка на file_id в запросе Messages поддерживается на всех моделях, которые поддерживают данный тип файла. Изображения поддерживаются на всех текущих моделях Claude. Для PDF и других типов файлов с инструментом выполнения кода см. связанные страницы с информацией о поддержке моделей.

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

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

• Загружайте файлы в защищённое хранилище Anthropic и получайте уникальный file_id
• Скачивайте файлы, созданные навыками или инструментом выполнения кода
• Ссылайтесь на файлы в запросах Messages, используя file_id вместо повторной загрузки содержимого
• Управляйте своими файлами с помощью операций получения списка, извлечения и удаления

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

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

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

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

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

{
  "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 для файлов, которые вы загружаете. Скачивать можно только файлы, созданные навыками или инструментом выполнения кода. См. Скачивание файла.

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

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

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)

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

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

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

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

{
  "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:

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

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

Чтобы отправить файл в инструмент выполнения кода, используйте блок содержимого container_upload:

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

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

Для типов файлов, которые блок document не поддерживает (например, .docx и .xlsx), преобразуйте файлы в простой текст и включите содержимое непосредственно в ваше сообщение. Файлы, которые уже являются простым текстом, такие как .csv и .md, можно либо прочитать таким способом, либо загрузить через Files API с явным указанием типа содержимого text/plain. Чтобы анализировать наборы данных, а не читать их как текст, загрузите их для инструмента выполнения кода с помощью блока container_upload.

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

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:\n\n{text_content}\n\nPlease summarize this document.",
                }
            ],
        }
    ],
)

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

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

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

Получите список загруженных вами файлов. Эндпоинт поддерживает пагинацию: каждый запрос возвращает до limit файлов (по умолчанию 20, максимум 1 000), а курсор next_page из ответа позволяет получить следующую страницу, если передать его обратно в параметре page. Файлы упорядочены от новых к старым. См. справочник List Files API. SDK возвращает первую страницу и предоставляет вспомогательные средства автоматической пагинации. В примере для CLI общее количество ограничивается с помощью --max-items:

client = anthropic.Anthropic()
files = client.files.list()
print(files)

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

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

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

file = client.files.retrieve_metadata(file_id)
print(file)

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

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

client.files.delete(file_id)

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

Скачивайте файлы, созданные навыками или инструментом выполнения кода. Файлы, которые вы загружаете, скачать нельзя. file_id сгенерированного файла появляется в блоке содержимого bash_code_execution_tool_result ответа Messages, который его создал:

file_content = client.files.download(file_id)

file_content.write_to_file("downloaded_file.txt")

В Claude API поддерживаемые файлы изображений, видео и аудио, которые Claude создаёт с помощью инструмента выполнения кода, включая файлы, созданные навыками, при скачивании содержат подписанные учётные данные содержимого C2PA (Content Credentials). О том, что содержат эти учётные данные и как их проверить, см. в разделе Content Credentials в сгенерированных файлах.

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

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

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

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

• Файлы ограничены рабочим пространством, в которое они были загружены. Любой запрос в том же рабочем пространстве может ссылаться на них; никогда не принимайте идентификаторы файлов из ненадёжных источников (см. предупреждение о доступе в рабочем пространстве)
• Файлы нельзя изменять или переименовывать после загрузки. Чтобы изменить содержимое файла, загрузите новый файл и удалите старый
• Файлы сохраняются до тех пор, пока вы не удалите их с помощью эндпоинта DELETE /v1/files/{file_id} или пока не наступит их expires_at
• Удалённые файлы невозможно восстановить
• Файлы становятся недоступными через API вскоре после удаления, но они могут сохраняться в активных вызовах Messages API и связанных использованиях инструментов
• Файлы, удалённые пользователями, будут удалены в соответствии с политикой хранения данных Anthropic. О соответствии требованиям ZDR для всех функций см. API и хранение данных

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

Чтобы срок действия файла истекал автоматически, включите поле формы 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-дневного периода.

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

Если в вашей организации включён Compliance API, его 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, прежде чем полагаться на этот журнал аудита. На Claude Platform on AWS вместо этого проводите аудит операций с файлами с помощью событий данных AWS CloudTrail.

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

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

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

1. Удалите бета-заголовок. Уберите anthropic-beta: files-api-2025-04-14 из ваших запросов. В SDK вызывайте client.files вместо client.beta.files; сохранение client.beta.files работает только в выпусках SDK, которые больше не отправляют заголовок. Более ранние выпуски отправляют его из client.beta.files даже без аргумента betas.
2. Обновите пагинацию. Замените циклы с after_id/before_id на курсор page/next_page или используйте вспомогательные средства автоматической пагинации SDK, показанные в разделе Управление файлами.
3. Читайте expires_at. Поле появляется только без заголовка; null означает, что у файла нет срока действия (см. Истечение срока действия файла).

Пространство имён 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. Более ранние выпуски 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 ТБ

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

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

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

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

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

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

Вызовы API, связанные с файлами, ограничены приблизительно 500 запросами в минуту. Чтобы запросить более высокое ограничение скорости (rate limit), свяжитесь с отделом продаж.

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

Compatibility