Files API

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

Поддерживаемые модели

Ссылка на file_id в запросе Messages поддерживается во всех моделях, которые поддерживают данный тип файла. Например, изображения поддерживаются во всех моделях Claude 3+, PDF во всех моделях Claude 3.5+, и различные другие типы файлов для инструмента выполнения кода в Claude Haiku 4.5 и всех моделях Claude 3.7+.

Files API в настоящее время не поддерживается на Amazon Bedrock или Google Vertex AI.

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

Files API предоставляет простой подход "загрузить один раз, использовать много раз" для работы с файлами:

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

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

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

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

Ответ от загрузки файла будет включать:

{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "type": "file",
  "filename": "document.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1024000,
  "created_at": "2025-01-01T00:00:00Z",
  "downloadable": false
}

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

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

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

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

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

Для типов файлов, которые не поддерживаются как блоки document (.csv, .txt, .md, .docx, .xlsx), преобразуйте файлы в простой текст и включите содержимое непосредственно в ваше сообщение:

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

Для 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"
  }
}

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

Список файлов

Получите список загруженных файлов:

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

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

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

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

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

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

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

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

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

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

• Файлы привязаны к рабочему пространству ключа API. Другие ключи API могут использовать файлы, созданные любым другим ключом API, связанным с тем же рабочим пространством
• Файлы сохраняются до их удаления
• Удалённые файлы не могут быть восстановлены
• Файлы становятся недоступными через API вскоре после удаления, но они могут сохраняться в активных вызовах Messages API и связанных использованиях инструментов
• Файлы, удаляемые пользователями, будут удалены в соответствии с политикой хранения данных Anthropic.

Хранение данных

Файлы, загруженные через Files API, сохраняются до явного удаления с помощью конечной точки DELETE /v1/files/{file_id}. Файлы хранятся для повторного использования при нескольких запросах API.

Для соответствия ZDR по всем функциям см. API и хранение данных.

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

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

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

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "File not found: file_011CNha8iCJcU1wXNR6q4V8w"
  }
}

Использование и выставление счётов

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

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

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

Ограничения частоты запросов

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

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