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

Files API в настоящее время находится в бета-версии. Пожалуйста, свяжитесь с нами через нашу форму обратной связи, чтобы поделиться своим опытом использования Files API.

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

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

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

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

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

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

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

Для использования Files API вам необходимо включить заголовок бета-функции: anthropic-beta: files-api-2025-04-14.

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

Загрузите файл для ссылки в будущих вызовах 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"

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

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

curl -X POST https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Пожалуйста, резюмируйте этот документ для меня."          
          },
          {
            "type": "document",
            "source": {
              "type": "file",
              "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
            }
          }
        ]
      }
    ]
  }'

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

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

Тип файлаMIME типТип блока контентаСлучай использования
PDFapplication/pdfdocumentАнализ текста, обработка документов
Обычный текстtext/plaindocumentАнализ текста, обработка
Изображенияimage/jpeg, image/png, image/gif, image/webpimageАнализ изображений, визуальные задачи
Наборы данных, другиеРазличаетсяcontainer_uploadАнализ данных, создание визуализаций

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

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

# Пример: Чтение текстового файла и отправка его как обычного текста
# Примечание: Для файлов со специальными символами рассмотрите кодирование base64
TEXT_CONTENT=$(cat document.txt | jq -Rs .)

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 @- <<EOF
{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Вот содержимое документа:\n\n${TEXT_CONTENT}\n\nПожалуйста, резюмируйте этот документ."
        }
      ]
    }
  ]
}
EOF

Для файлов .docx, содержащих изображения, сначала конвертируйте их в формат PDF, затем используйте поддержку PDF, чтобы воспользоваться встроенным парсингом изображений. Это позволяет использовать цитаты из PDF документа.

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

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

{
  "type": "document",
  "source": {
    "type": "file",
    "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
  },
  "title": "Заголовок документа", // Необязательно
  "context": "Контекст о документе", // Необязательно  
  "citations": {"enabled": true} // Необязательно, включает цитаты
}

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

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

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

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

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

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

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_011CNha8iCJcU1wXNR6q4V8w \
  -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_011CNha8iCJcU1wXNR6q4V8w \
  -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_011CNha8iCJcU1wXNR6q4V8w/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

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

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

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

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

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

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

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

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

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

​
Использование и биллинг

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

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

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

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

В течение бета-периода:

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