Руководство по API AppCloud
Как загрузить файл, показать его в браузере, заполнить шаблон со склонением ФИО по падежам, получить PDF, работать с видео и камерами. Как готовить сами шаблоны, описано отдельно: шаблоны и плейсхолдеры.
Начало работы
Адрес и токен
При подключении мы выдаём адрес сервера и токен. В примерах ниже сервер — https://ab0a.appcloud.robx.online, токен — ВАШ_ТОКЕН.
Токен передаётся в заголовке Authorization: просто значением или со словом Bearer. Токен нужен для всего, что меняет данные: загрузки, генерации, удаления, перекодирования. Скачивание и просмотр по идентификатору работают без токена, поэтому ссылку можно отдать пользователю или вставить в страницу.
Authorization: ВАШ_ТОКЕН
Authorization: Bearer ВАШ_ТОКЕН
API отвечает на запросы с любых сайтов (заголовок Access-Control-Allow-Origin: *), так что файлы можно загружать прямо из браузера.
Идентификатор файла
После загрузки файл получает идентификатор file_id. Первые четыре символа — сервер (нода), на котором лежит файл, остальное — его хеш: ab0a + 356a192b…. Храните file_id в своей базе целиком.
Запросы на скачивание и просмотр (/get, /view) с чужим сервером в идентификаторе сами перенаправляются куда нужно. Остальные запросы отправляйте на тот сервер, который записан в начале file_id, иначе придёт ошибка о неверном узле.
Ответы и ошибки
Почти все эндпоинты отвечают JSON. Успех — поле "message": "OK", ошибка — код 4xx или 5xx и текст в message. Без токена или с неверным токеном — 401 {"message": "unauthorized"}. Скачивание и просмотр при ошибке отвечают простым текстом. Полный список кодов — в конце.
Быстрый старт
Загрузить шаблон договора, заполнить его и получить ссылку на PDF:
# 1. Загрузить шаблон DOCX → в ответе file_id шаблона
curl -X POST https://ab0a.appcloud.robx.online/uploadfile \
-H "Authorization: ВАШ_ТОКЕН" \
-F "file=@dogovor.docx"
# {"message": "OK", "file_id": "ab0a356a192b7913b04c54574d18c28d46e6395428ab"}
# 2. Заполнить шаблон и сразу получить PDF
curl -X POST https://ab0a.appcloud.robx.online/generatefile \
-H "Authorization: ВАШ_ТОКЕН" \
-H "Content-Type: application/json" \
-d '{"id": "ab0a356a…", "format": "pdf", "values": {"fio": "Иванов Иван Иванович", "date": "15.03.2026"}}'
# {"message": "OK", "file_id": "ab0a9f2c…"}
# 3. Ссылки для пользователя
https://ab0a.appcloud.robx.online/view/ab0a9f2c… # открыть в браузере
https://ab0a.appcloud.robx.online/get?id=ab0a9f2c… # скачать
Файлы
Загрузка
/uploadfile нужен токенОбычная загрузка формой: Content-Type: multipart/form-data, файл в поле file. Тип файла берётся из формы, а если его нет — из расширения.
curl -X POST https://ab0a.appcloud.robx.online/uploadfile \
-H "Authorization: ВАШ_ТОКЕН" \
-F "file=@photo.jpg"
Ответ:
{"message": "OK", "file_id": "ab0a356a192b7913b04c54574d18c28d46e6395428ab"}
Загрузка частями
Большие файлы удобнее отправлять кусками. Тело запроса — байты очередного куска, без формы. Заголовки:
| Заголовок | Что передать |
|---|---|
Content-Range | bytes <начало>-<конец>/<размер файла>, например bytes 0-5242879/73400320 |
X-File-Name | Имя файла. Кириллицу удобно передавать в URL-кодировке вместе с X-File-Name-Encoding: url |
X-File-Type | MIME-тип, необязательно |
X-Upload-Id | Свой идентификатор сессии загрузки, одинаковый для всех кусков одного файла |
Пока файл не собран, сервер отвечает {"message": "chunk stored", "upload_id": "…"}. После последнего куска — {"message": "OK", "file_id": "…"}.
X-Upload-Id, сервер вернёт тот же file_id, а не ошибку. Сервер помнит завершённую загрузку 24 часа.Скачивание
/get?id=<file_id>Отдаёт файл для скачивания с исходным именем и типом. Токен не нужен. Если файл удалён — 410 Файл удалён, если идентификатора нет — 404.
Данные файла
/details/<file_id> нужен токенВозвращает служебные данные, которые AppCloud хранит рядом с файлом: главы видео, разбор чека или счёта, ссылки на готовый видео-кружок и т. п.
{"message": "OK", "details": { … }}
Удаление
/deletefile нужен токен{"file_id": "ab0a356a…"}
Удаляет файл из хранилища вместе с вариантами качества видео и нарезкой для потокового просмотра. Запись о файле и история операций остаются. Ответ: {"message": "OK", "file_id": "…", "freed_bytes": 12345}. Повторное удаление не ошибка: придёт "already_deleted": true.
Проверка наличия
/checkfiles нужен токенЕсть ли в хранилище файлы с таким содержимым. Сами файлы не передаются, только SHA-1 и размер. Удобно перед массовой загрузкой: отправить только то, чего ещё нет. До 10 000 файлов за запрос.
{"files": [{"sha1": "aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d", "size": 5}]}
Ответ по каждому файлу в том же порядке: status = found (есть, в file_ids — все копии), missing (нет) или deleted (был, но удалён).
{"message": "OK", "files": [{"sha1": "aaf4…", "size": 5, "status": "found",
"file_ids": ["ab0a356a…"], "filenames": ["отчёт.pdf"], "deleted": []}]}
Просмотр и картинки
/view/<file_id>/view?id=<file_id>Одна ссылка на любой файл. AppCloud сам выбирает, как его показать. Токен не нужен.
Что показывает /view
| Файл | Что открывается |
|---|---|
| Видео | Страница с плеером: потоковое воспроизведение, выбор качества, главы на полосе прокрутки |
| Аудио | Компактный плеер: воспроизведение, перемотка, скорость, громкость, скачивание. Рассчитан на встраивание высотой 72–120 px |
| Картинки | Картинка на странице |
| SVG | Встроенный редактор SVG |
| 3D: STL, OBJ, STEP, STP | Интерактивный просмотр модели |
| Word (.docx) | Документ с сохранённым оформлением |
| Excel (.xlsx, .xls) | Таблица с переключением листов |
| Остальное | Скачивание |
Документы и таблицы больше 50 МБ не открываются в браузере, а скачиваются. Параметр ?raw=1 всегда отдаёт сами байты файла без страницы просмотра. Заголовок Range поддерживается: ответ 206 с нужным куском, так работает перемотка видео.
Картинки
Картинка загружается как любой файл через /uploadfile. Для тега <img> на своём сайте берите адрес с ?raw=1: так приходят байты картинки с правильным типом.
<img src="https://ab0a.appcloud.robx.online/view/ab0a356a…?raw=1" alt="Фото">
Адрес /view/<file_id> без параметров откроет картинку на отдельной странице, /get?id=… — скачает её с исходным именем. SVG по ссылке /view открывается во встроенном редакторе, а с ?raw=1 отдаётся как обычная картинка.
Встраивание плеера
Страницы просмотра видео, аудио и камер можно вставить на свой сайт через iframe. Плеер подстраивается под размер блока.
<iframe src="https://ab0a.appcloud.robx.online/view/ab0a7f3e…"
width="100%" height="480" frameborder="0"
allow="autoplay; fullscreen" allowfullscreen></iframe>
Документы и PDF
Заполнить шаблон
/generatefile нужен токенПодставляет значения в загруженный шаблон DOCX или XLSX. Как размечать шаблон, описано в руководстве по шаблонам.
{
"id": "ab0a356a…",
"format": "pdf",
"values": {
"fio": "Иванов Иван Иванович",
"date": "15.03.2026",
"amount": "150000.50",
"items": ["Первый пункт", "Второй пункт"]
}
}
| Поле | Описание |
|---|---|
id | file_id шаблона |
format | Шаблон DOCX: docx или pdf. Шаблон XLSX (а также XLS и XLSM): xlsx, xls или pdf |
values | Значения для плейсхолдеров: объект или строка с JSON. ФИО — в именительном падеже, нужный падеж задаётся в шаблоне (см. Падежи) |
Ответ: {"message": "OK", "file_id": "…"} — новый файл, который открывается и скачивается как обычный.
/generatefile хранится как «рецепт» (шаблон + значения) и собирается заново при каждом открытии. Для подписи и архива зафиксируйте его через /topdf.Падежи
ФИО и должности передаются в values один раз, в именительном падеже. Нужный падеж указывается в самом шаблоне DOCX: после имени ключа в квадратных скобках ставится код падежа. Одно значение можно вывести в разных падежах в одном документе.
# values
{"fio": "Петрова Анна Сергеевна", "position": "Министр образования"}
# в шаблоне → в документе
Справка выдана {{fio['dat']}} → Справка выдана Петровой Анне Сергеевне
Заявление от {{fio['gen']}} → Заявление от Петровой Анны Сергеевны
{{position['dat']}} → Министру образования
| Код | Падеж | Вопрос | Иванов Иван Иванович |
|---|---|---|---|
nom | Именительный | кто? | Иванов Иван Иванович |
gen | Родительный | кого? | Иванова Ивана Ивановича |
dat | Дательный | кому? | Иванову Ивану Ивановичу |
acc | Винительный | кого? | Иванова Ивана Ивановича |
ins | Творительный | кем? | Ивановым Иваном Ивановичем |
pre | Предложный | о ком? | Иванове Иване Ивановиче |
- Каждое слово склоняется отдельно, род определяется по самому слову, регистр сохраняется:
ИВАНОВ→ИВАНОВУ. - Зависимое слово в родительном падеже не меняется: «Министр образования» → «Министру образования».
- Несклоняемые фамилии (Куликовских, Кравец и другие) берутся из списка исключений.
- Кавычки вокруг кода необязательны:
{{fio[dat]}}тоже работает. - Склонение работает только в шаблонах DOCX. В XLSX значение подставляется без изменений, поэтому форму в падеже передавайте отдельным ключом.
Даты и суммы раскладываются похожим способом, через суффикс после точки: {{date.month_name}} → «марта», {{amount.rub}} → рубли. Все суффиксы и подробности — в руководстве по шаблонам.
Зафиксировать PDF
/topdf нужен токен{"id": "ab0a9f2c…"}
Один раз собирает документ, переводит его в PDF и сохраняет обычным неизменным файлом. Нужен перед электронной подписью: подпись относится к конкретным байтам.
Принимает документы, собранные через /generatefile (DOCX, XLSX, PDF), и загруженные файлы DOCX и XLSX. Старый формат .xls нужно сначала пересохранить в XLSX. Ответ:
{"message": "OK", "file_id": "ab0a51c0…", "filename": "договор.pdf", "converted": true}
Для уже загруженного PDF новый файл не создаётся: вернётся исходный file_id и "converted": false.
Что умеет конвертер
PDF собирается своим конвертером, без офисных программ на сервере. Один и тот же документ всегда даёт побайтно одинаковый PDF.
- Из DOCX: шрифты как в Word, цвета, списки, таблицы с объединёнными ячейками, заливкой и границами, повтор строк-заголовков таблицы на новой странице, картинки, разрывы страниц, разделы со своим размером, ориентацией и полями, колонтитулы с номером страницы и числом страниц.
- Из XLSX: каждый видимый лист — страница A4 (длинный лист продолжается на следующих), ширины столбцов, высоты строк, объединённые ячейки, заливка, границы, шрифты, выравнивание и перенос слов. Картинки, диаграммы и повёрнутый текст не печатаются, скрытые листы, строки и столбцы — тоже.
Подробнее о шрифтах и таблицах — в руководстве по шаблонам.
Видео
Загрузка видео
Видео загружается через обычный /uploadfile. Сразу после загрузки AppCloud в фоне перекодирует его во все варианты качества ниже исходного и нарежет для потокового просмотра (HLS). Пока идёт обработка, /view уже показывает исходное видео.
Качество и HLS
/video/qualities/<file_id>Какие варианты качества готовы: {"qualities": ["360p", "480p", "720p", "1080p"]}. Пустой список — перекодирования не было.
/hls/<file_id>/master.m3u8/hls/<file_id>/<качество>.m3u8Плейлисты для своего плеера (hls.js, Safari, мобильные приложения). Мастер-плейлист содержит все готовые варианты качества. Если нарезки ещё нет — 404.
/video/transcode/<file_id> нужен токенЗапустить перекодирование вручную, например для видео, загруженного до появления этой функции. Ответ {"message": "transcoding started"} или {"message": "already transcoded", "qualities": […]}.
/video/generate_hls/<file_id> нужен токенТолько нарезать для потокового просмотра, без перекодирования.
Главы
/video/chapters/<file_id>/video/chapters/<file_id> нужен токенГлавы показываются в плеере метками на полосе прокрутки. time — секунды от начала, title — название. Читать главы можно без токена.
{"chapters": [
{"time": 0, "title": "Вступление"},
{"time": 120, "title": "Глава 1"},
{"time": 300, "title": "Глава 2"}
]}
Видео-кружки
Короткие круглые видео, как в мессенджерах. Загрузите видео с заголовком processOption: circle. AppCloud в фоне сделает из него MP4 и постер. Пока идёт обработка, в /details/<file_id> стоит "transcoding": true, после — появляются mp4_file_id и poster_file_id.
Камеры RTSP
/rtsp/start нужен токен{"url": "rtsp://admin:password@192.168.1.100:554/stream1", "retain_minutes": 30}
| Поле | Описание |
|---|---|
url | RTSP-адрес камеры, обязательно |
retain_minutes | Сколько последних минут хранить в записи. 0 — только трансляция, без записи |
transcode | true — перекодировать в H.264 (нужно для камер с H.265). По умолчанию поток копируется как есть |
video_bitrate | Битрейт, например "1000k" или "2M". Если задан, поток перекодируется |
Ответ 201: stream_id, file_id, view_url (страница плеера) и hls_url (плейлист для своего плеера).
/rtsp/stop нужен токенТело {"stream_id": "…"}. После остановки по тому же file_id открывается запись, если retain_minutes был больше нуля.
/rtsp/status нужен токенСписок активных трансляций. С ?detailed=true — ещё и параметры видео.
/rtsp/diagnose нужен токенПошаговая проверка камеры: доступен ли адрес, открыт ли порт, отвечает ли RTSP, какой кодек и разрешение. Тело {"stream_id": "…"} или {"rtsp_url": "rtsp://…"}. В ответе health: ok, error или no_connection, и причина в error_classification, например auth_failed или unsupported_codec. Логин и пароль в ответе скрыты.
Страница /view/<file_id> сама понимает, что показать: идёт трансляция — плеер с пометкой LIVE, трансляция закончилась и есть запись — обычный плеер с перемоткой.
| Камера | Типичный RTSP-адрес |
|---|---|
| Hikvision | rtsp://admin:password@IP:554/Streaming/Channels/101 |
| Dahua | rtsp://admin:password@IP:554/cam/realmonitor?channel=1&subtype=0 |
| Reolink | rtsp://admin:password@IP:554/h264Preview_01_main |
Чёрный экран в плеере обычно значит, что камера отдаёт H.265: запустите трансляцию с "transcode": true. Задержка в несколько секунд нормальна для потокового видео.
Распознавание
/speech/recognize нужен токенРечь в текст через Yandex SpeechKit. Форма с полем audio (WAV, PCM 16 бит, моно, 8, 16 или 48 кГц) или JSON {"file_id": "…"} для уже загруженной записи. Язык — поле lang, по умолчанию ru-RU. Ответ: {"message": "OK", "text": "…", "duration_sec": 12.5}. Запись длиннее 10 минут — 413, не WAV — 422.
/receipt/recognize нужен токенКассовый чек: строка из QR-кода (qrraw), реквизиты чека (manual: fn, fd, fp, check_time, sum, type) или file_id загруженного чека. С "store": true разбор сохраняется рядом с файлом. Ответ: {"message": "OK", "details": {…}}.
/invoice/recognize нужен токенСчёт на оплату, УПД, товарная накладная или акт из загруженного PDF с текстовым слоем (сканы без текста не распознаются). Тело {"file_id": "…", "store": true}. В ответе findoc — тип и номер документа, дата, продавец и покупатель с ИНН и банком, позиции, итог и НДС. Суммы — в копейках.
{"message": "OK", "recognized": true, "findoc": {
"format": "om-findoc/1", "doc_type": "invoice", "doc_type_title": "Счёт на оплату",
"number": "6494032", "date": "2026-05-12", "currency": "RUB",
"seller": {"name": "…", "inn": "…", "kpp": "…", "bank": {"name": "…", "bik": "…", "account": "…", "corr_account": "…"}},
"buyer": {"name": "…", "inn": "…", "kpp": "…"},
"items": [{"n": …, "title": "…", "qty": …, "unit": "…", "price": …, "sum": …, "vat_rate": …, "vat_sum": …}],
"total_sum": 659000, "vat_sum": 11721}}
/receipt/attach нужен токенСохранить рядом с файлом разбор чека, который ваш портал получил сам: {"file_id": "…", "details": {…}}. Потом разбор читается через /details.
Коды ответов
| Код | Когда |
|---|---|
| 200 | Успех |
| 201 | Трансляция с камеры запущена |
| 206 | Отдан кусок файла по заголовку Range |
| 302 | Файл лежит на другом сервере: /get и /view перенаправляют туда |
| 400 | Неверный запрос, неподдерживаемый формат или файл с другого сервера |
| 401 | Нет токена или токен неверный |
| 404 | Файла с таким идентификатором нет |
| 410 | Файл удалён |
| 413 | Слишком много: больше 10 000 файлов в /checkfiles или запись длиннее 10 минут |
| 422 | Распознавание речи: файл не WAV |
| 500, 502 | Ошибка на сервере или во внешнем сервисе распознавания |
Нужен доступ или нашли ошибку в руководстве — напишите Дмитрию.