Files API

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

​

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

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

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

​

Как работает API файлов

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

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

​

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

​

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

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

curl -X POST https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -F "file=@/path/to/document.pdf"

​

Типы файлов и блоки контента

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

​

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

Для PDF и текстовых файлов используйте блок контента document:

{
  "type": "document",
  "source": {
    "type": "file",
    "file_id": "file_abc123"
  },
  "title": "Document Title", // Опционально
  "context": "Context about the document", // Опционально  
  "citations": {"enabled": true} // Опционально, включает цитирование
}

​

Блоки изображений

Для изображений используйте блок контента image:

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

​

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

​

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

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

curl https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

​

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

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

curl https://api.anthropic.com/v1/files/file_abc123 \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

​

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

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

curl -X DELETE https://api.anthropic.com/v1/files/file_abc123 \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

​

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

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

curl -X GET "https://api.anthropic.com/v1/files/file_abc123/content" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  --output downloaded_file.txt

​

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

​

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

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

​

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

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

​

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

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

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

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

​

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

Операции API файлов бесплатны:

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

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

​

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

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

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