Stagify.ai › Документация API

Stagify API

Панель API

Оформляйте фотографии недвижимости прямо из своего кода. Один HTTP-запрос возвращает одно готовое изображение. Предоплаченные кредиты по $0,15 за изображение, без подписки, без минимума и без счёта, который выйдет из-под контроля.

Базовый URL: https://stagify.ai/api/v1
Аутентификация: Bearer stg_live_…
Тип содержимого: multipart/form-data

Введение

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

Кредит, это целое изображение. Вы покупаете кредиты заранее, и каждый успешный рендер тратит один. Неудавшийся рендер возвращается автоматически, поэтому вы платите только за полученную фотографию. А так как баланс предоплачен, украденный ключ обойдётся вам максимум в остаток на нём. Счёта в конце месяца не будет.

Ключи предназначены для взаимодействия сервер-сервер. API не отправляет заголовки CORS, поэтому браузер не может обратиться к нему напрямую; это сделано намеренно, а ключ, доступный из браузерного JavaScript, это утёкший ключ. Ключ показывается один раз, хранится только его хеш, отзыв срабатывает немедленно.

Быстрый старт

Создайте ключ на странице ключей API, купите пакет кредитов и отправьте фотографию. В ответе придёт оформленное изображение в виде data URL.

curl https://stagify.ai/api/v1/renders \
  -H "Authorization: Bearer $STAGIFY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "image=@living-room.jpg" \
  -F "roomType=Living room" \
  -F "furnitureStyle=modern" \
  -F "labelVirtuallyStaged=true"

Рендер может занимать до нескольких минут. Установите тайм-аут чтения клиента в 300 секунд и повторяйте запрос с тем же Idempotency-Key. Именно это гарантирует, что за одну фотографию с вас не спишут дважды.

Пакеты кредитов

Загрузка цен…

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

POST /api/v1/renders, отправляется как multipart/form-data. Все допустимые значения ниже также отдаются в JSON по GET /api/v1/options, которому не нужен ключ API, клиент может заполнить свои списки вместо того, чтобы зашивать эту таблицу в код.

Поле	Тип	Примечания
`image`	file	Обязательно. Фотография комнаты. JPEG, PNG или WebP, до 25 МБ. Проверяется MIME-тип, а не расширение файла.
`roomType`	enum	`Bedroom`, `Living room`, `Dining room`, `Kitchen`, `Office`, `Bathroom`, `Outdoors`, `Dorm`. По умолчанию `Living room`. Учитываются регистр и пробелы, а нераспознанное значение не отклоняется. Оно записывается в подсказку как свободный текст, поэтому `Living Room`, это не `Living room`.
`furnitureStyle`	enum	`standard`, `modern`, `midcentury`, `scandinavian`, `luxury`, `coastal`, `farmhouse`, `custom`. По умолчанию `standard`, в него же молча превращается нераспознанное значение. `custom` использует ваш `additionalPrompt` вместо встроенного текста стиля.
`additionalPrompt`	string	Произвольные указания для этого рендера.
`removeFurniture`	boolean	Освободить комнату перед оформлением. Отправьте `true` или `on`; всё остальное, включая `1` и `yes`, считается ложью.
`keepFurniture`	string	Произвольный текст о том, что оставить, например `keep the dining table and the built-in shelves`. Читается только при включённом `removeFurniture`. 500 символов.
`furnitureImage`	file[]	До 5 референсных фотографий мебели для подражания. Те же форматы и ограничение размера, что и у `image`.
`labelVirtuallyStaged`	boolean	Впечатывает пометку «Virtually staged» в итоговое изображение.
`stampStyle`	enum	`dark`, `light`, `minimal`, `banner`. По умолчанию `dark`. Регистр не важен; нераспознанное значение возвращается к значению по умолчанию.
`stampScale`	number	От `0.7` до `1.6`, по умолчанию `1`. Значения вне диапазона обрезаются по границе, а не отклоняются.
`stampLang`	enum	Язык пометки: `english`, `spanish`, `french`, `german`, `chinese`, `korean`, `portuguese`, `russian`, `italian`, `japanese`, `dutch`. По умолчанию `english`.
`variations`	integer	Принимается только `1`. Для нескольких отправляйте параллельные запросы.

Идемпотентность

Рендер удерживает соединение минутами, поэтому по-настоящему болезненный сбой, это оборванный сокет уже после того, как работа выполнена: деньги списаны, а на руках ничего. Отправляйте заголовок Idempotency-Key в каждом запросе и повторяйте с тем же значением.

Что есть у нас	Что сделает повтор
Успешный запрос с теми же параметрами	Вернёт сохранённый результат с `X-Stagify-Replayed: true`. Повторного списания не будет.
Запрос ещё выполняется	`409 REQUEST_IN_FLIGHT`. Подождите и повторите.
Запрос, брошенный на середине рендера	Выполнится заново по уже сделанному списанию, до трёх попыток.
Тот же ключ с другими параметрами	`422 IDEMPOTENCY_KEY_REUSED`. Возьмите новый ключ.

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

Пометки об оформлении

Многие правила MLS и NAR требуют, чтобы виртуально оформленная фотография сообщала об этом. labelVirtuallyStaged впечатывает такую пометку в пиксели, а не добавляет её метаданными, которые следующий инструмент может удалить.

Если пометку нанести не удалось, изображение удерживается, а не выдаётся без маркировки, вызов отвечает 500 DISCLOSURE_STAMP_FAILED, а кредит возвращается. Отключить это поведение нельзя, и нет настройки на уровне ключа, которая тихо его выключит.

Ошибки

Любой сбой отвечает { "error": "…", "code": "…" }. Ветвитесь по code, никогда по сообщению. Сообщения меняются, коды, нет.

Статус	Код	Что делать
401	`API_KEY_MISSING` / `API_KEY_INVALID` / `API_KEY_REVOKED`	Проверьте заголовок `Authorization` или создайте новый ключ.
402	`INSUFFICIENT_CREDITS`	Пополните баланс. В теле ответа есть `credits_remaining`.
403	`ACCOUNT_SUSPENDED`	Обратитесь в поддержку.
400	`VARIATIONS_UNSUPPORTED`	Этот API отдаёт одно изображение на запрос. Отправляйте параллельные запросы.
409	`REQUEST_IN_FLIGHT`	Этот ключ идемпотентности ещё выполняется. Подождите и повторите.
409	`CONCURRENCY_LIMIT`	Слишком много одновременных рендеров. Повторите через несколько секунд.
422	`IDEMPOTENCY_KEY_REUSED`	Вы повторно использовали ключ с другими параметрами. Возьмите новый.
422	`NO_IMAGE_GENERATED`	Модель ничего не вернула. Средства возвращены; повторите или возьмите другое фото.
429	`RATE_LIMITED`	Снизьте темп и повторите.
500	`DISCLOSURE_STAMP_FAILED`	Пометку нанести не удалось, поэтому изображение удержано. Средства возвращены.
500	`RENDER_FAILED`	Средства возвращены. Укажите `ref`, если обращаетесь в поддержку.

Другие эндпоинты

GET /api/v1/options: допустимые значения каждого перечисления выше. Ключ API не нужен.
GET /api/v1/me: работает ли мой ключ? Возвращает аккаунт и баланс.
GET /api/v1/credits: баланс и суммарные показатели.
GET /api/v1/renders/{id}: статус одного рендера.

Каждый ответ несёт X-Stagify-Credits-Remaining, так что баланс видно без отдельных опросов.

Вопросы, повышенные лимиты или счёт вместо карты: team@stagify.ai.