Martynov Labs Написать

Руководство по 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…   # скачать

Файлы

Загрузка

POST /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-Rangebytes <начало>-<конец>/<размер файла>, например bytes 0-5242879/73400320
X-File-NameИмя файла. Кириллицу удобно передавать в URL-кодировке вместе с X-File-Name-Encoding: url
X-File-TypeMIME-тип, необязательно
X-Upload-IdСвой идентификатор сессии загрузки, одинаковый для всех кусков одного файла

Пока файл не собран, сервер отвечает {"message": "chunk stored", "upload_id": "…"}. После последнего куска — {"message": "OK", "file_id": "…"}.

Повторы безопасны. Если соединение оборвалось и последний кусок ушёл повторно с тем же X-Upload-Id, сервер вернёт тот же file_id, а не ошибку. Сервер помнит завершённую загрузку 24 часа.

Скачивание

GET /get?id=<file_id>

Отдаёт файл для скачивания с исходным именем и типом. Токен не нужен. Если файл удалён — 410 Файл удалён, если идентификатора нет — 404.

Данные файла

GET /details/<file_id> нужен токен

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

{"message": "OK", "details": { … }}

Удаление

POST /deletefile нужен токен
{"file_id": "ab0a356a…"}

Удаляет файл из хранилища вместе с вариантами качества видео и нарезкой для потокового просмотра. Запись о файле и история операций остаются. Ответ: {"message": "OK", "file_id": "…", "freed_bytes": 12345}. Повторное удаление не ошибка: придёт "already_deleted": true.

Проверка наличия

POST /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": []}]}

Просмотр и картинки

GET /view/<file_id>
GET /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 отдаётся как обычная картинка.

AppCloud хранит картинку как есть: не уменьшает и не сжимает её. Превью нужного размера готовьте до загрузки.

Встраивание плеера

Страницы просмотра видео, аудио и камер можно вставить на свой сайт через iframe. Плеер подстраивается под размер блока.

<iframe src="https://ab0a.appcloud.robx.online/view/ab0a7f3e…"
  width="100%" height="480" frameborder="0"
  allow="autoplay; fullscreen" allowfullscreen></iframe>

Документы и PDF

Заполнить шаблон

POST /generatefile нужен токен

Подставляет значения в загруженный шаблон DOCX или XLSX. Как размечать шаблон, описано в руководстве по шаблонам.

{
  "id": "ab0a356a…",
  "format": "pdf",
  "values": {
    "fio": "Иванов Иван Иванович",
    "date": "15.03.2026",
    "amount": "150000.50",
    "items": ["Первый пункт", "Второй пункт"]
  }
}
ПолеОписание
idfile_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

POST /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

GET /video/qualities/<file_id>

Какие варианты качества готовы: {"qualities": ["360p", "480p", "720p", "1080p"]}. Пустой список — перекодирования не было.

GET /hls/<file_id>/master.m3u8
GET /hls/<file_id>/<качество>.m3u8

Плейлисты для своего плеера (hls.js, Safari, мобильные приложения). Мастер-плейлист содержит все готовые варианты качества. Если нарезки ещё нет — 404.

POST /video/transcode/<file_id> нужен токен

Запустить перекодирование вручную, например для видео, загруженного до появления этой функции. Ответ {"message": "transcoding started"} или {"message": "already transcoded", "qualities": […]}.

POST /video/generate_hls/<file_id> нужен токен

Только нарезать для потокового просмотра, без перекодирования.

Главы

GET /video/chapters/<file_id>
POST /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

POST /rtsp/start нужен токен
{"url": "rtsp://admin:password@192.168.1.100:554/stream1", "retain_minutes": 30}
ПолеОписание
urlRTSP-адрес камеры, обязательно
retain_minutesСколько последних минут хранить в записи. 0 — только трансляция, без записи
transcodetrue — перекодировать в H.264 (нужно для камер с H.265). По умолчанию поток копируется как есть
video_bitrateБитрейт, например "1000k" или "2M". Если задан, поток перекодируется

Ответ 201: stream_id, file_id, view_url (страница плеера) и hls_url (плейлист для своего плеера).

POST /rtsp/stop нужен токен

Тело {"stream_id": "…"}. После остановки по тому же file_id открывается запись, если retain_minutes был больше нуля.

GET /rtsp/status нужен токен

Список активных трансляций. С ?detailed=true — ещё и параметры видео.

POST /rtsp/diagnose нужен токен

Пошаговая проверка камеры: доступен ли адрес, открыт ли порт, отвечает ли RTSP, какой кодек и разрешение. Тело {"stream_id": "…"} или {"rtsp_url": "rtsp://…"}. В ответе health: ok, error или no_connection, и причина в error_classification, например auth_failed или unsupported_codec. Логин и пароль в ответе скрыты.

Страница /view/<file_id> сама понимает, что показать: идёт трансляция — плеер с пометкой LIVE, трансляция закончилась и есть запись — обычный плеер с перемоткой.

КамераТипичный RTSP-адрес
Hikvisionrtsp://admin:password@IP:554/Streaming/Channels/101
Dahuartsp://admin:password@IP:554/cam/realmonitor?channel=1&subtype=0
Reolinkrtsp://admin:password@IP:554/h264Preview_01_main

Чёрный экран в плеере обычно значит, что камера отдаёт H.265: запустите трансляцию с "transcode": true. Задержка в несколько секунд нормальна для потокового видео.

Распознавание

POST /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.

POST /receipt/recognize нужен токен

Кассовый чек: строка из QR-кода (qrraw), реквизиты чека (manual: fn, fd, fp, check_time, sum, type) или file_id загруженного чека. С "store": true разбор сохраняется рядом с файлом. Ответ: {"message": "OK", "details": {…}}.

POST /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}}
POST /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Ошибка на сервере или во внешнем сервисе распознавания

Нужен доступ или нашли ошибку в руководстве — напишите Дмитрию.