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

Файлы для сообщений и переменных старта: загрузка, статус обработки и получение содержимого. Загруженный файл принадлежит user_id, который его загрузил, и доступен только ему.

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

POST /v1/files

Content-Type: multipart/form-data

Поля формы

Поле	Тип	Обязательное	Описание
`file`	file	да	Файл. У части файла должен быть указан тип содержимого (`Content-Type`)
`user_id`	string	да	Идентификатор пользователя
`variable`	string	нет	Имя переменной старта типа `file` или `files`, для которой загружается файл

При загрузке проверяются только размер и формат файла:

Размер. Действует предел для типа файла из настроек агента (file_upload.max_size_mb), а если загрузка файлов у агента выключена — предел платформы. Сверх предела — 413 с кодом file_too_large, текст ошибки называет предел. Собственный предел файловой переменной проверяется позже — при отправке первого сообщения.
Формат. Формат, который платформа не принимает, и файл без указанного типа содержимого — 415 с кодом unsupported_file_type.
Один файл. За один запрос загружается один файл; несколько файлов в поле file — 400 с кодом too_many_files.

Разрешены ли файлы этого типа агенту и сколько их можно приложить, API проверяет позже — при отправке сообщения. Поэтому файл загружается, даже если загрузка файлов у агента сейчас выключена.

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

Ответ

201 — объект File:

Поле	Тип	Описание
`id`	string	Идентификатор файла — передайте его в `files` сообщения или в значение переменной старта
`name`	string	Имя файла
`extension`	string	Расширение
`mime_type`	string	Тип содержимого или `null`, если тип не определён
`size`	integer	Размер в байтах
`status`	string	`processing` — файл обрабатывается, `ready` — готов, `failed` — обработка не удалась
`created_at`	string	Время загрузки

Обработка нужна видеофайлам, если к агенту подключено распознавание речи (Sber Salute Speech): платформа извлекает из видео звуковую дорожку. Остальные файлы, в том числе видео без распознавания речи, сразу получают статус ready.

Видео, которое ещё обрабатывается, можно отправить в сообщении: агент подождёт окончания обработки ограниченное время. Если обработка не успела, агент скажет об этом в ответе, а видео можно отправить снова, когда его статус станет ready.

curl https://api.evo-ai.ru/v1/files \
  -H "Authorization: Bearer evo_agent_..." \
  -F "user_id=user-42" \
  -F "file=@contract.pdf;type=application/pdf"

{
  "id": "e2b7c4a1-9d38-4f60-8a15-3c6e0b9d2f47",
  "name": "contract.pdf",
  "extension": "pdf",
  "mime_type": "application/pdf",
  "size": 482133,
  "status": "ready",
  "created_at": "2026-09-24T10:14:31Z"
}

Ошибки

HTTP	Код	Когда
`400`	`no_file`	Поле `file` не передано
`400`	`too_many_files`	В поле `file` больше одного файла
`413`	`file_too_large`	Файл больше допустимого размера
`415`	`unsupported_file_type`	Формат не принимается или не указан тип содержимого

Статус файла

GET /v1/files/{file_id}/status?user_id={user_id}

Ответ

200 — объект FileStatus:

Поле	Тип	Описание
`status`	string	`processing`, `ready` или `failed`
`error`	object	При `failed` — `{code, message}` с кодом из таблицы ниже, иначе `null`

Код	Когда
`no_audio_track`	В видео нет аудиодорожки
`video_corrupted`	Видеофайл повреждён
`audio_too_long`	Аудиодорожка длиннее допустимого
`processing_timeout`	Обработка не уложилась в отведённое время
`processing_failed`	Обработка не удалась по иной причине

Если видео не удалось обработать, агент ответит, что не может прочитать файл, — отправка сообщения при этом ошибкой не завершается.

Ошибки

HTTP	Код	Когда
`404`	`file_not_found`	Файла нет, или этот `user_id` его не загружал

Содержимое файла

GET /v1/files/{file_id}/content

Возвращает сам файл: загруженный этим user_id или прикреплённый к сообщению в его диалогах, в том числе созданный агентом.

Параметры запроса

Параметр	Тип	Обязательный	Описание
`user_id`	string	да	Идентификатор пользователя
`download`	boolean	нет	`true` — отдать файл как вложение для скачивания, `false` — для просмотра. По умолчанию `false`

Ответ

200 — содержимое файла. С download=false файл приходит со своим типом содержимого, с download=true — как application/octet-stream для скачивания. HTML-файлы всегда отдаются как вложение для скачивания.

Ошибки

HTTP	Код	Когда
`404`	`file_not_found`	Файла нет, или этот `user_id` его не загружал и в его диалогах его нет

Оценки и подсказки вопросов

Базы знаний