Документация API

Не хотите писать интеграцию? Виджет примерки ставится одним тегом <script> на витрину — без бэкенда и без вызовов API.

Аутентификация

Передайте ваш API ключ в заголовке X-Api-Key. Ключи начинаются с префикса tn_live_.

X-Api-Key: tn_live_xxxxxxxxxxxxxxxx

Модель списания кредитов

Каждый вызов B2B-функции списывает кредиты с квоты текущего периода в момент отправки. При окончательной ошибке кредиты возвращаются автоматически.

Функция	Формула кредитов
Try-On	1 кредит за вызов
Описание	1 кредит за вызов
Model Shoot	варианты × 3 + (2 если генерируется модель) + (1 если своё фото фона)
Видео	по длительности: 5с = 1, 8с = 2, 10с = 3, 15с = 4 (управляется в админке)
Видео-примерка	по длительности: 5с = 1, 8с = 2, 10с = 3, 15с = 4 (отдельный баланс tryon_video)

Возврат: окончательная ошибка провайдера → автовозврат всех кредитов; промежуточные сбои (внутренние повторы) — без возврата; провал QA model-shoot — без возврата (генерация состоялась).

Загрузка изображений

POST /api/v1/b2b/uploads/ — multipart-загрузка одного изображения (поле file; JPEG, PNG или WebP, до 10 МБ). Кредиты не списываются. Возвращает upload_id (передайте как garment_upload_id) и публичный url (подходит как *_image_url). Нужно, потому что все submit-эндпоинты принимают только публичные HTTPS-ссылки — теперь не требуется свой хостинг. Ссылка живёт expires_in секунд.

curl -X POST https://api.try-nova.shop/api/v1/b2b/uploads/ \
  -H "X-Api-Key: tn_live_..." \
  -F "file=@garment.jpg"

# => { "data": { "upload_id": "9f2c...", "url": "https://...", "expires_in": 900 } }
# Pass upload_id as garment_upload_id, or use url as garment_image_url.

Каталог поз и фонов

GET /api/v1/b2b/public/presets/ — без авторизации. Возвращает допустимые значения pose_preset_ids и background_preset вместе с картинками-превью и подписями. Запрашивайте их, а не хардкодьте: список меняется, и неверный id даёт 400. Параметры: locale (ru/en) и gender (male — мужской набор поз; фоны не зависят от пола).

# No API key needed — this is a public catalogue.
curl "https://api.try-nova.shop/api/v1/b2b/public/presets/?locale=en&gender=female"

# => { "data": { "version": 3, "gender": "female",
#      "poses":       [{ "id": "front_full", "label": "Front", "image_url": "..." }, ...],
#      "backgrounds": [{ "id": "studio_white", "label": "White studio", ... }, ...] } }

Свои модели (saved models)

POST /api/v1/b2b/models/generate/ — создать модель с нужными параметрами (асинхронно; списывается надбавка за генерацию, по умолчанию 2 кредита). Опрос: GET /api/v1/b2b/models/jobs/{request_id}/. Затем передавайте model.uuid как saved_model_id с model_source="saved" — повторное использование бесплатно. Список: GET /api/v1/b2b/models/. Это же решение, если в стоковой библиотеке нет нужного типа модели.

# 1. Generate a model (async, charges the generate surcharge once)
curl -X POST https://api.try-nova.shop/api/v1/b2b/models/generate/ \
  -H "X-Api-Key: tn_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"gender":"male","ethnicity":"south_asian","body_type":"athletic","age_range":"25-30","name":"Hero model"}'

# 2. Poll until status is "completed"
curl https://api.try-nova.shop/api/v1/b2b/models/jobs/<request_id>/ \
  -H "X-Api-Key: tn_live_..."

# 3. Reuse the model.uuid on any shoot or video — free from here on
curl -X POST https://api.try-nova.shop/api/v1/b2b/model-shoot/ \
  -H "X-Api-Key: tn_live_..." -H "Content-Type: application/json" \
  -d '{"garment_image_url":"https://...","model_source":"saved","saved_model_id":"<uuid>","model_gender":"male","pose_preset_ids":["front_full"],"variant_count":1}'

Виртуальная примерка (VTO)

POST /api/v1/b2b/tryon/ — отправить задачу примерки. output_format=image (1 кредит) или output_format=video (анимированный ролик; списывается с отдельного баланса tryon_video по длительности — передайте video_duration_seconds и motion_type). Используйте Idempotency-Key. Статус: GET /api/v1/b2b/tryon/{request_id}/ (result_image_url — кадр/постер, result_video_url — готовое видео).

# Image output (1 credit)
curl -X POST https://api.try-nova.shop/api/v1/b2b/tryon/ \
  -H "X-Api-Key: tn_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id" \
  -d '{"body_image_url":"https://...","garment_image_url":"https://..."}'

# Video output (charged from the tryon_video balance by duration)
curl -X POST https://api.try-nova.shop/api/v1/b2b/tryon/ \
  -H "X-Api-Key: tn_live_..." \
  -H "Content-Type: application/json" \
  -d '{"body_image_url":"https://...","garment_image_url":"https://...","output_format":"video","video_duration_seconds":8,"motion_type":"turn"}'

Генерация описания товара

POST /api/v1/b2b/tools/description/ — сгенерировать SEO-описание товара (1 кредит). Поддерживаются Wildberries, Ozon и др.

curl -X POST https://api.try-nova.shop/api/v1/b2b/tools/description/ \
  -H "X-Api-Key: tn_live_..." \
  -H "Content-Type: application/json" \
  -d '{"product_name":"Denim Jacket","product_attributes":{"color":"blue","size":"M"},"platform":"wildberries"}'

Model Shoot — фотосессия с моделью

POST /api/v1/b2b/model-shoot/ — сгенерировать фото товара на модели. Стоимость: варианты × 3 + 2 (если model_source=generate) + 1 (если background_custom_url). Проверка статуса: GET /api/v1/b2b/model-shoot/{request_id}/.

# You need a saved_model_id first — see "Your Own Models" above.
# model_source "stock" is retired and returns 400 STOCK_MODELS_UNAVAILABLE.
# pose_preset_ids must be DISTINCT and its length must equal variant_count;
# fetch valid pose/background ids from /api/v1/b2b/public/presets/.
curl -X POST https://api.try-nova.shop/api/v1/b2b/model-shoot/ \
  -H "X-Api-Key: tn_live_..." \
  -H "Content-Type: application/json" \
  -d '{"garment_image_url":"https://...","model_source":"saved","saved_model_id":"<uuid>","model_gender":"female","model_ethnicity":"european","model_body_type":"average","model_age_range":"25-30","background_preset":"studio_white","pose_preset_ids":["front_full","three_quarter","profile","walking"],"lighting_preset":"studio_softbox","variant_count":4}'

Генерация видео

POST /api/v1/b2b/video/ — сгенерировать рекламное видео. Поддерживаемые длительности и стоимость в кредитах управляются админом (по умолчанию 5с=1, 8с=2, 10с=3, 15с=4). Проверка статуса: GET /api/v1/b2b/video/{request_id}/.

curl -X POST https://api.try-nova.shop/api/v1/b2b/video/ \
  -H "X-Api-Key: tn_live_..." \
  -H "Content-Type: application/json" \
  -d '{"garment_image_url":"https://...","model_gender":"female","duration_seconds":8,"aspect_ratio":"9:16"}'

Аналитика и трекинг

1. Установите пиксель отслеживания

После интеграции API генерации один раз добавьте этот код на каждую страницу витрины, где показывается ассет TryNova:

<script src="https://pixel.try-nova.shop/pixel.js" data-key="YOUR_PIXEL_KEY"></script>

Пометьте каждый отрендеренный ассет идентификатором request_id, полученным при генерации:

<div data-trynova-asset="REQUEST_ID" data-trynova-sku="YOUR_SKU"> …asset… </div>

Согласие: пиксель ничего не сохраняет и не отправляет, пока не получено согласие. Добавьте data-consent="granted" в тег script либо вызовите TryNova.consent() после того, как пользователь примет ваш баннер cookie/согласия (TryNova.revoke() отзывает согласие). После этого показы и просмотры отслеживаются автоматически. События намерения отправляйте сами:

TryNova.track("add_to_cart", { assetId: "REQUEST_ID", sku: "YOUR_SKU" });

Покупки и возвраты не отправляются из браузера (ключ пикселя публичный) — см. шаг 2.

2. Отправляйте покупки и возвраты с сервера (обязательно для учёта выручки)

Ключ пикселя публичный — он виден в исходном коде страницы, поэтому им можно отправлять только низкодоверенные события (показы / просмотры / add-to-cart). Покупки и возвраты связаны с деньгами, поэтому их нужно отправлять с вашего бэкенда секретным API-ключом, а не ключом пикселя:

curl -X POST https://api.try-nova.shop/api/v1/b2b/events/ \
  -H "X-Api-Key: YOUR_SECRET_KEY" -H "Content-Type: application/json" \
  -d '{"event_id":"order-1234","asset_id":"REQUEST_ID","sku":"YOUR_SKU","event_type":"purchase","value":4990,"currency":"RUB","occurred_at":"2026-06-23T12:00:00Z"}'

Указывайте стабильный event_id (например, id заказа), чтобы повторные отправки были идемпотентны. Для возврата заказа используйте "event_type":"return".

3. Продаёте на маркетплейсе (Wildberries / Ozon / Amazon)?

Пиксель не может работать на страницах карточек маркетплейса, поэтому аналитика витрины пока не покрывает эти продажи. Подключение аккаунта маркетплейса для чтения просмотров, заказов и возвратов по SKU появится скоро (отдельный релиз).

Коды ошибок

Код	HTTP	Описание
`QUOTA_EXCEEDED`	429	Превышен лимит запросов или баланс исчерпан
`VALIDATION_ERROR`	400	Неверные параметры запроса
`FIELD_NOT_SUPPORTED`	400	Поле удалено из API (например, camera_angles или scene_vibe) — уберите его
`IDEMPOTENCY_CONFLICT`	409	Idempotency-Key повторно использован с другим телом запроса
`PROVIDER_ERROR`	502	Ошибка стороннего AI-провайдера
`NOT_FOUND`	404	Ресурс не найден