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
}

Поле downloadable имеет значение false для загруженных вами файлов. Скачивать можно только файлы, созданные навыками или инструментом выполнения кода. См. раздел Скачивание файла.



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

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

response = client.messages.create(
    model="claude-opus-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",
    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), а параметры before_id и after_id позволяют получить соседнюю страницу. См. справочник по API List Files. SDK возвращают первую страницу и предоставляют вспомогательные функции автоматической пагинации. Пример для CLI ограничивает общее количество с помощью --max-items:

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



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

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

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



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



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

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



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

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



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

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

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

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



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

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

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

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



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

В период бета-тестирования:

• Вызовы API, связанные с файлами, ограничены примерно 100 запросами в минуту
• Свяжитесь с нами, если вам нужны более высокие лимиты для вашего сценария использования



Дальнейшие шаги