Files API

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

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

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

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

Ссылка на 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 предоставляет простой подход «загрузи один раз, используй многократно» для работы с файлами:

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

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

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

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

Загрузите файл для использования в будущих вызовах 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 поддерживает различные типы файлов, соответствующие различным типам блоков содержимого:

Тип файла	MIME-тип	Тип блока содержимого	Вариант использования
PDF	`application/pdf`	`document`	Анализ текста, обработка документов
Обычный текст	`text/plain`	`document`	Анализ текста, обработка
Изображения	`image/jpeg`, `image/png`, `image/gif`, `image/webp`	`image`	Анализ изображений, визуальные задачи
Наборы данных и другие

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

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

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

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

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

{
  "type": "document",
  "source": {
    "type": "file",
    "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
  },
  "title": "Document Title", // Необязательно
  "context": "Context about the document", // Необязательно
  "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"

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

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

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

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

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

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

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

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

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

Файлы, загруженные через 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"
  }
}

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

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

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

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

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

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

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

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"

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-opus-4-6",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Please summarize this document for me."
          },
          {
            "type": "document",
            "source": {
              "type": "file",
              "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
            }
          }
        ]
      }
    ]
  }'

# Пример: Чтение текстового файла и отправка его как обычного текста
# Примечание: Для файлов со специальными символами рассмотрите кодирование 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-opus-4-6",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Here's the document content:\n\n${TEXT_CONTENT}\n\nPlease summarize this document."
        }
      ]
    }
  ]
}
EOF

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