Загрузка файлов
Картинки для карточек агентов, первых экранов, онбординга и пейволла загружаются одним методом. Он возвращает адрес, который вы подставляете в нужное поле. Картинку агента можно отдать и прямо в запросе агента.
Как устроена загрузка
Большинство картинок в настройках — это адреса, а не файлы. Сначала файл загружается методом upload/image, он возвращает url. Затем этот адрес записывается в поле нужной сущности: image у агента, image_url у слайда онбординга, header_logo у бота и так далее.
Несколько загрузок устроены иначе и сами записывают результат: аватар бота, аватар поддержки, файлы базы знаний, вложения обращений и HTML-шаблоны. Они описаны на своих страницах, сводка — в конце этой.
Загрузить картинку или видео
Принимает файл, сжимает растровую картинку и возвращает её адрес. Сам по себе метод ничего в ассистенте не меняет.
POST /assistants/{assistantId}/upload/image
Тело — multipart/form-data.
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
assistantId | integer | да | id ассистента, в пути |
image | file | да | Файл. Форматы и размеры зависят от context, см. таблицу ниже |
context | string | нет | card (по умолчанию) или content. Любое другое значение считается card |
context | Форматы | Размер | Ширина после сжатия | Папка | Для чего |
|---|---|---|---|---|---|
card | jpeg, jpg, png, webp, gif, svg, mp4, webm | до 5 МБ; gif до 4 МБ; mp4 и webm до 8 МБ | до 480 px | welcome-cards/ | Небольшие картинки: карточки агентов, аватары на первом экране, логотипы шапки, слайды онбординга, картинка пейволла, короткое видео-превью карточки |
content | jpeg, jpg, png, webp, gif | до 5 МБ | до 1600 px | welcome-content/ | Крупные картинки в сообщениях: баннер в начале заготовленного ответа агента, картинки галереи первого сообщения |
Формат определяется по расширению имени файла, поэтому имя должно заканчиваться на правильное расширение.
Что происходит с файлом
| Файл | Обработка |
|---|---|
| jpeg, png, статичный webp | Уменьшается до ширины из таблицы, если шире; пережимается (jpeg — качество 82, png — палитра). Рядом кладётся копия в webp |
| gif, анимированный webp | Сохраняется как есть, чтобы не сломать анимацию |
| svg | Сохраняется как есть |
| mp4, webm | Сохраняются как есть, без пережатия |
Копию в webp браузер получает автоматически по тому же адресу, если присылает Accept: image/webp. Меняться адрес не должен: в поля пишите url из ответа как есть.
Исходник в большем разрешении не хранится. Если крупную картинку загрузить с context=card, она сожмётся до 480 px и будет мылить в сообщении — придётся загрузить заново с content.
Пример
curl -s -X POST "$BASE/assistants/$ASSISTANT/upload/image" \
-H "Authorization: Bearer $KEY" \
-F "image=@card.png" \
-F "context=card"{
"success": true,
"url": "https://framesuite.app/storage/welcome-cards/bab2163d-f0d0-4963-8c0a-8db7ba4b97e8.png",
"path": "welcome-cards/bab2163d-f0d0-4963-8c0a-8db7ba4b97e8.png"
}| Поле | Описание |
|---|---|
url | Полный адрес файла. Его и записывайте в настройки |
path | Путь внутри хранилища, для справки |
Имя файла на сервере случайное (UUID), исходное имя не сохраняется. Файл не привязан к ассистенту: списка загруженных файлов и метода удаления нет, неиспользуемые файлы просто остаются в хранилище.
Ошибки
| HTTP | Когда |
|---|---|
404 | {"error": "Project not found or access denied"} — ассистент чужой или не существует |
405 | Запрос не POST |
422 | {"success": false, "error": "The image field is required."} — файла нет в поле image |
422 | {"success": false, "error": "The image field must be a file of type: jpeg, jpg, png, gif, webp, svg, mp4, webm."} — неподходящий формат |
422 | {"success": false, "error": "The image may not be greater than 4096 kilobytes."} — файл больше лимита для своего формата |
Картинка агента
Картинку агента не обязательно загружать отдельно: POST /assistants/{assistantId}/agents и PUT /assistants/{assistantId}/agents/{agentId} принимают её прямо в поле — data URL (data:image/png;base64,…), файлом multipart или внешней ссылкой https://…. Сервер сохраняет файл тем же путём, что upload/image (те же форматы, лимиты, папки и сжатие), и записывает в поле свой адрес. Способы, лимиты и тексты ошибок — Агенты → Картинка в запросе агента.
curl -s -X PUT "$BASE/assistants/$ASSISTANT/agents/$AGENT" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"image": "https://example.com/avatar.png"}'Запасной путь — два шага: загрузить файл через upload/image с context=card и записать url в поле агента.
URL=$(curl -s -X POST "$BASE/assistants/$ASSISTANT/upload/image" \
-H "Authorization: Bearer $KEY" \
-F "image=@tile.png" | jq -r .url)
curl -s -X PUT "$BASE/assistants/$ASSISTANT/agents/$AGENT" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d "{\"image\": \"$URL\"}"| Поле агента | Что туда | context (и при передаче в запросе агента) |
|---|---|---|
image | Картинка или видео карточки, аватар на экране-профиле. Строка до 1024 символов | card |
image_poster | Статичная картинка-заставка к видео-превью: png, jpg, webp или gif, не видео | card |
reference_image | Картинка-образец, по которой модель рисует | card |
character_avatar, image_references | Аватар персонажа, галерея лендинга action: image | card |
prepared_images | Галерея картинок в первом сообщении агента: до 5 объектов {"url": …, "alt": …} | content |
out_of_credits_image | Картинка в сообщении «закончились кредиты» | content |
Подробно о полях — Свойства config.
Все загрузки в API
| Что | Метод | Поле файла | Форматы и лимиты | Где описано |
|---|---|---|---|---|
| Картинки и видео для настроек | POST /assistants/{assistantId}/upload/image | image | См. выше | Эта страница |
| Аватар бота | POST /assistants/{assistantId}/bot/avatar | avatar | jpeg, jpg, png, webp до 10 МБ; обрезается в квадрат 256×256 и сразу записывается в bot_avatar | Настройки бота и шапка |
| Аватар поддержки и картинка пустого окна обращений | POST /assistants/{assistantId}/support/avatar | avatar | jpeg, jpg, png, gif, webp до 5 МБ; context=avatar записывает в support_avatar, context=empty только возвращает адрес | Поддержка и обращения |
| Картинки агента | Прямо в POST и PUT агента или через upload/image | image и другие поля картинок | data URL, файл или внешняя ссылка; лимиты как у upload/image | Агенты |
| Файлы базы знаний агента | POST /agents/{agentId}/knowledge | files[] или текст в теле | txt, md, csv, json, html, yml, pdf, docx, doc, rtf; до 10 МБ на файл, до 200 файлов | База знаний |
| Вложения обращения | POST /assistants/{assistantId}/tickets/attachments | files[] | Картинки, pdf, doc, docx, ppt, pptx, odp, txt, md, csv, json; до 5 файлов, до 50 МБ каждый | Поддержка и обращения |
| Свой HTML-шаблон файлом | POST /assistants/{assistantId}/custom-templates/{slot}/templates | file или files[] | Один html, zip или html с ассетами (css, js, картинки, шрифты); до 5 МБ вместе | Свои HTML-шаблоны |