Как добавить виртуальный стейджинг в своё приложение: API-туториал для разработчиков

Что вы строите: архитектура функции стейджинга

К концу этого туториала ваше приложение будет принимать от пользователя фотографию комнаты, отправлять её в API виртуального стейджинга и через 10–40 секунд возвращать обставленную, фотореалистичную версию этой комнаты. Это и есть вся функция. Всё остальное — вебхуки, повторы, бюджет кредитов, метки раскрытия — существует, чтобы сделать этот цикл надёжным на продакшен-масштабе.

Спрос давно сформирован. Мировой рынок виртуального стейджинга достиг $454 млн в 2025 году, и спрос продолжает расти по мере того, как объявления борются за внимание онлайн:

«Мировой рынок решений виртуального стейджинга, по прогнозам, вырастет с $454 млн в 2025 году до $4.73 млрд к 2035 году». — Business Research Insights

Если вы управляете платформой объявлений, инструментом доставки фотосъёмок, дашбордом управления недвижимостью или proptech-CRM, стейджинг всё чаще становится функцией, которую пользователи ожидают внутри вашего продукта, а не отдельным сервисом, куда они ходят сами.

Архитектурно каждый API стейджинга на рынке — Roomagen, AI HomeDesign, Decor8 и несколько других — следует одному и тому же паттерну асинхронных задач. Генерация занимает десятки секунд — слишком долго, чтобы держать HTTP-запрос открытым, — поэтому поток всегда один: отправить задачу, сразу получить ID задачи, а результаты — позже.

Этап	Кто выполняет	Типичная задержка
Загрузка и валидация фото	Ваше приложение	Меньше 1 секунды
Отправка задачи стейджинга	Ваш бэкенд → API стейджинга	Меньше 1 секунды
ИИ-генерация	Провайдер стейджинга	10–40 секунд
Уведомление о завершении	Вебхук (push) или поллинг (pull)	0–10 секунд
Хранение и показ результатов	Ваше приложение	Меньше 1 секунды

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

Перед началом: ключи, окружения и требования к изображениям

Прежде чем писать интеграционный код, нужны три вещи: API-ключ, план разделения окружений и изображения, соответствующие входным требованиям провайдера.

Получение ключа. API Roomagen находится в раннем доступе: вступите в список ожидания на roomagen.com/api; бесплатный тариф для разработчиков включает 50 вызовов в месяц с водяным знаком — достаточно, чтобы собрать и протестировать полную интеграцию, ничего не потратив. Ключи выглядят как rmg_live_... и передаются в заголовке X-Api-Key. Какого бы провайдера вы ни выбрали, действуют два одинаковых правила: храните ключ в серверной переменной окружения и никогда не включайте его в клиентский JavaScript или мобильный бинарник, откуда любой сможет его извлечь и опустошить ваши кредиты.

Окружения. Используйте отдельные ключи для разработки и продакшена, если провайдер их выдаёт. Во время разработки вывод с водяным знаком на самом деле полезен — он не даёт тестовым изображениям случайно попасть в живое объявление.

Входные изображения. Качество стейджинга сильно зависит от качества входа. Таблица ниже суммирует типичные ожидания API стейджинга на конкретном примере требований Roomagen.

Требование	Рекомендация
Формат	JPEG или PNG
Передача	Публичный image_url (предпочтительно) или image_base64
Разрешение	1024px+ по длинной стороне; чем выше вход, тем качественнее выход
Содержимое	Одна комната, съёмка без наклона, разумное освещение; широкий угол подходит
Состояние комнаты	Пустые комнаты обставляются наиболее предсказуемо; меблированным подходят инструменты редизайна

Одно практическое замечание: передавать URL лучше, чем base64, для любых нетривиальных размеров файла. Ваш бэкенд избегает накладных расходов на перекодирование, тела запросов остаются маленькими, а провайдер забирает изображение напрямую с вашего CDN или подписанного URL хранилища.

Наконец, проверяйте баланс кредитов программно. Roomagen предоставляет GET /api/v1/account, который возвращает image_credits, — опрашивайте его из админ-дашборда или ежедневного крона, чтобы никогда не удивляться посреди месяца. Большинство кредитных провайдеров предлагают аналогичный эндпоинт, а подключение алерта о низком балансе занимает десять минут сейчас против простоя потом.

Шаг 1: отправка задачи стейджинга

Ключевой вызов — один POST. Вы указываете, какой инструмент запустить, изображение, опции стилизации и опционально URL вебхука для уведомления о завершении.

curl -X POST https://api.roomagen.com/api/v1/jobs \
  -H "X-Api-Key: rmg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "virtual-staging",
    "image_url": "https://cdn.yourapp.com/rooms/123.jpg",
    "options": { "room_type": "living_room", "style": "scandinavian" },
    "webhook_url": "https://yourapp.com/hooks/roomagen"
  }'

Ответ приходит немедленно — до завершения генерации:

{ "job_id": "job_8f3ka92m", "status": "processing", "images_charged": 1 }

Тот же вызов из Node.js-бэкенда:

const res = await fetch("https://api.roomagen.com/api/v1/jobs", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.ROOMAGEN_API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    tool: "virtual-staging",
    image_url: imageUrl,
    options: { room_type: "living_room", style: "scandinavian" },
    webhook_url: "https://yourapp.com/hooks/roomagen"
  })
});
const { job_id } = await res.json();

Две вещи нужно сделать в момент прихода ответа. Во-первых, сохраните job_id в связке с вашей собственной записью — объявлением, фотографией, пользователем — прежде чем делать что-либо ещё. Эта строка — ваш якорь идемпотентности: если процесс упадёт, вы восстановите задачу по ID вместо повторной отправки и двойной оплаты. Во-вторых, запишите images_charged, чтобы ваш внутренний учёт совпадал с учётом провайдера.

Обратите внимание: tool — это просто слаг. Эндпоинт Roomagen GET /api/v1/tools перечисляет 40+ инструментов, использующих идентичный паттерн задач, — среди них виртуальный стейджинг для пустых комнат, сумеречная конвертация day-to-dusk, удаление объектов для расхламления, улучшение изображений для коррекции экспозиции и цвета, конвертация эскиза в план этажа и виртуальная реновация. Как только цикл задач ниже заработает для стейджинга, добавление кнопки «сумеречное фото» или «убрать беспорядок» в ваше приложение — это изменение одной строки в поле tool. Этот мультиинструментальный паттерн стоит проверять у любого оцениваемого провайдера: API с одним инструментом означают повторную интеграцию с нуля, когда ваш роадмап вырастет.

Именно для объявлений с пустыми комнатами virtual-staging — рабочая лошадка, тогда как меблированные комнаты лучше направлять сначала в инструмент редизайна или инструмент освобождения от мебели — различие, которое ваш UI может показать простым переключателем «комната пустая?».

Шаг 2: обработка завершения — вебхуки против поллинга

Ваша задача обрабатывается. Теперь нужно узнать, когда она закончится. Механизмов ровно два, и зрелые интеграции используют оба.

Параметр	Вебхуки (push)	Поллинг (pull)
Задержка	Почти мгновенно по завершении	До одного интервала опроса (5–10 с)
Инфраструктура	Нужен публичный HTTPS-эндпоинт	Ничего, кроме планировщика
Надёжность	Доставка может сорваться (ваш простой, сеть)	Устойчиво — вы контролируете цикл
Работа с безопасностью	Требуется проверка подписи	Только API-ключ
Нагрузка на сервер	Один запрос на задачу	N запросов на задачу
Лучше всего для	Продакшен на объёмах	Разработка, резерв, малые объёмы

Рекомендуемый паттерн: вебхуки как основной канал, поллинг как резерв. Регистрируйте webhook_url на каждой задаче и одновременно планируйте проверку поллингом — GET /api/v1/jobs/{id} каждые 5–10 секунд, — которая активируется, если вебхук не пришёл, скажем, за 60 секунд. Ограничьте поллинг жёстким таймаутом (2–3 минуты), после которого задача помечается в вашем UI как неудачная. Эта комбинация переживает сбои вебхуков с любой стороны, не добавляя ощутимых затрат. Руководства по вебхукам и GitHub, и Stripe сходятся в одних принципах: отвечай быстро, проверяй подписи, дедуплицируй и сверяйся поллингом.

Минимальный обработчик вебхука на Express с проверкой подписи:

app.post("/hooks/roomagen", express.raw({ type: "*/*" }), (req, res) => {
  const sig = req.get("X-Roomagen-Signature");
  const expected = crypto
    .createHmac("sha256", process.env.ROOMAGEN_WEBHOOK_SECRET)
    .update(req.body)
    .digest("hex");
  if (!sig || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const { job_id, status, result_urls } = JSON.parse(req.body);
  completeJob(job_id, status, result_urls); // must be idempotent
  res.sendStatus(200);
});

Здесь важны три детали. Во-первых, проверяйте подпись на сыром теле, до парсинга JSON: Roomagen подписывает полезные нагрузки HMAC-SHA256 (RFC 2104) и отправляет дайджест в X-Roomagen-Signature; большинство провайдеров используют аналогичную схему. Пропуск проверки означает, что любой, кто обнаружит URL вашего эндпоинта, сможет вбрасывать фальшивые события «completed» в ваше приложение. Во-вторых, используйте сравнение, устойчивое к атакам по времени, а не ===. В-третьих, делайте обработчик завершения идемпотентным: системы вебхуков повторяют доставку при сбое, так что одно и то же событие может прийти дважды, а поллинг мог уже завершить задачу. Обычно достаточно защиты вида UPDATE ... WHERE status = 'processing'.

При поллинге эндпоинт статуса возвращает всё нужное: status (processing, completed или failed), result_urls при успехе, error при сбое и processing_ms — стоит логировать для мониторинга задержек.

Шаг 3: доставка результатов пользователям

Завершённая задача возвращает result_urls — массив URL, указывающих на сгенерированные изображения. Устоите перед соблазном хотлинкать их.

Перехостите результаты в собственном хранилище. Скачайте каждый URL результата и запишите его в свой S3, R2 или GCS-бакет, затем отдавайте со своего CDN. URL результатов провайдера следует считать временным механизмом доставки, а не постоянной инфраструктурой: политики хранения различаются, и изображения вашего продукта не должны ломаться, если провайдер подчистит старые задачи или вы смените вендора. Шаг «скачать и сохранить» — пять строк кода, убирающих целую категорию будущих инцидентов.

Всегда храните оригинал. Сохраняйте исходное и обставленное фото как связанную пару. Это важно по трём причинам: ваш UI может предложить слайдер до/после (стабильно самый вовлекающий способ показать стейджинг), пользователи могут откатиться, а в контексте недвижимости США регуляции всё чаще требуют, чтобы неотредактированное изображение оставалось доступным. Результаты задач Roomagen спроектированы так, чтобы связывать оригинал и отредактированное изображение парой именно поэтому.

Помечайте обставленные изображения в контексте объявлений. Если ваши пользователи публикуются на MLS-платформах, раскрытие — больше не факультативная вежливость. Калифорнийский AB 723 требует раскрытия ИИ-изменённых изображений объявлений с 1 января 2026 года, а правила MLS по всей стране ожидают видимую метку «Virtually Staged». Roomagen предоставляет опциональный параметр метки раскрытия, отрисовывающий маркировку прямо на выходном изображении, — это путь наименьших усилий для соответствия последующей публикации. Юридические детали — отдельная тема; короткая версия для вашей интеграции такова: храните различие «обставлено/оригинал» в модели данных и показывайте метку везде, где обставленное изображение может попасть в объявление.

Дайте возможность повторной генерации. У генеративного вывода есть разброс; иногда диван получается не тот. Roomagen включает 1 бесплатную повторную генерацию на изображение, так что кнопка «Перегенерировать» рядом с каждым результатом ничего вам не стоит для первой попытки и резко снижает количество обращений в поддержку. Какого бы провайдера вы ни использовали, проверьте его политику повторной генерации и отразите её в UI, вместо того чтобы заставлять пользователей платить за подброс монеты.

Тот же конвейер доставки обслуживает любой инструмент, который вы добавите позже: план этажа, сгенерированный из эскиза, сумеречный экстерьер, замена неба или превью реновации кухни — всё возвращается как result_urls через тот же самый вебхук.

Продакшен-вопросы: лимиты запросов, повторы и бюджет кредитов

Интеграция выше работает. Эти четыре практики удерживают её в рабочем состоянии под нагрузкой.

Повторы и backoff. Считайте ответы 429 и 5xx на отправку задачи повторяемыми с экспоненциальным backoff (1с, 2с, 4с, потолок 30с). Критично: повторяйте только когда точно знаете, что задача не была создана, — если отправка ушла и запрос завис по таймауту, сверьте свои сохранённые записи и список задач аккаунта до повторной отправки, иначе заплатите за дублирующие генерации. Здесь якорь идемпотентности из шага 1 отрабатывает свою цену.

Экономика сбоев. Прежде чем моделировать маржу, поймите, во что обходятся сбои. В Roomagen инфраструктурные сбои никогда не тратят кредиты, а неудачные задачи возвращаются автоматически, так что статус failed — неудобство, а не расход. Не каждый провайдер работает так — некоторые берут плату за попытку, — поэтому этот пункт должен стоять в вашем чек-листе оценки рядом с ценой за изображение. Ваш UI должен различать «сбой, без списания, попробуйте снова» и «завершено, но не по вкусу — используйте бесплатную повторную генерацию».

Бюджет кредитов. Кредитные API вознаграждают за объёмные обязательства. Текущие пакеты Roomagen:

Месячный объём	Цена пакета	Фактическая цена за изображение
500 изображений	$125	$0.25
2,500 изображений	$550	$0.22
10,000 изображений	$2,000	$0.20
50,000+ изображений	Индивидуально	По договорённости

Для сравнения: API AI HomeDesign стоит около $0.24 за изображение, а Decor8 — около $0.20; надёжные провайдеры группируются в одном диапазоне, так что выбор чаще зависит от широты инструментов, качества вебхуков и функций комплаенса, чем от нескольких центов разницы. При бюджетировании умножайте ожидаемый объём примерно на 1.1×, чтобы покрыть повторные генерации сверх бесплатной и эксперименты пользователей, и помните математику маржи со стороны покупателя: агенты обычно платят $16–$69 за изображение сервисам ручного стейджинга, так что функция, стоящая вам $0.20–$0.25 за изображение, оставляет место для здорового ценообразования в любой упаковке.

Честная оговорка о зрелости. API Roomagen — новичок 2026 года, сейчас в раннем доступе через список ожидания: вы получаете современную эргономику (HMAC-вебхуки, автовозвраты, 40+ инструментов на одном эндпоинте), но не десятилетие проверенной истории аптайма и не большое публичное сообщество. Если вам нужна мгновенная self-serve регистрация уже сегодня, альтернативы выше продают доступ к API дольше. Общая архитектура этого туториала намеренно переносима между провайдерами именно поэтому: ваша таблица задач, обработчик вебхуков и конвейер хранения переживут смену вендора почти нетронутыми.

Типичные ошибки интеграций API стейджинга

Семь режимов отказа повторяются в интеграциях стейджинга снова и снова. Все они предотвратимы.

1. Блокировка потока запроса. Удержание HTTP-запроса пользователя открытым на 10–40 секунд генерации связывает ресурсы сервера и упирается в таймауты большинства балансировщиков. Отправьте задачу, верните 202 Accepted с ID вашей внутренней записи и дайте клиенту подписаться на обновления через WebSocket, SSE или простой опрос вашего собственного API.

2. Доверие только вебхукам. Ваше окно деплоя, ошибка конфигурации TLS или сбой доставки на стороне провайдера рано или поздно съедят вебхук. Без резервного поллинга такая задача навсегда зависнет в вашем UI в статусе «processing». Двухканальный паттерн из шага 2 почти ничего не стоит.

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

4. Хотлинк URL результатов. URL провайдера временны. Перехощивайте результаты в собственном хранилище по завершении, каждый раз.

5. Повторная отправка без проверок идемпотентности. Сетевые таймауты плюс наивные повторы равно двойные списания. Сохраняйте job_id сразу при отправке и пропускайте повторы через собственные записи.

6. Игнорирование раскрытия на рынках объявлений. Если обставленные изображения могут попасть в MLS через ваш продукт, непомеченное изображение — теперь юридический риск для ваших пользователей в Калифорнии и нарушение политики на крупных порталах. Проносите флаг стейджинга через модель данных и отрисовывайте метку.

7. Запуск без UX сбоев. 10–40 секунд — долгий срок в терминах UI, и небольшой процент задач будет падать. Спроектируйте состояние обработки (индикация прогресса, скелетон изображения), состояние сбоя (понятный повтор, «с вас не списано») и возможность повторной генерации до запуска, а не после первого тикета в поддержку.

Итог: запустите цикл, затем расширяйте

Добавление виртуального стейджинга в приложение — по-настоящему небольшая интеграция: один POST для создания задачи, один обработчик вебхуков с резервным поллингом и шаг хранения результатов. Рабочий прототип умещается в один вечер; продакшен-закалка — идемпотентное завершение, проверка подписи, дисциплина повторов, метки раскрытия — ещё день. При $0.20–$0.25 за изображение на объёмных пакетах, автоматическом возврате за неудачные задачи и доставке результатов за 10–40 секунд экономика сходится для всего — от портала доставки фотографа до национальной платформы объявлений.

Архитектура намеренно нейтральна к провайдеру: асинхронная отправка задач, двухканальная обработка завершения, перехощенные результаты и пара «обставлено/оригинал» в модели данных подойдут любому API стейджинга, который вы выберете сейчас или на который мигрируете позже.

Если хотите строить по рабочему примеру этого туториала — вступите в список ожидания API Roomagen: бесплатный тариф для разработчиков включает 50 вызовов в месяц с водяным знаком, чего хватает на весь цикл интеграции и тестирования из этого гида без платных обязательств. Дальше тот же эндпоинт задач даёт вам виртуальный стейджинг, day-to-dusk, удаление объектов, улучшение изображений и инструменты планов этажей за одной интеграцией.