Ziex Try-On для разработчиков¶

Ziex Try-On позволяет покупателю увидеть одежду на своём фото. Подключить примерку к магазину можно двумя способами:

Виджет на странице товара. Один тег script и один вызов TryOn.init(...). Браузер покупателя обращается к API Ziex Try-On напрямую, ваш сервер не участвует. Именно это делают за вас плагин для WooCommerce и модуль для 1С-Битрикс.
API с вашего сервера. Вы отправляете фото покупателя и одежду, получаете идентификатор задачи и читаете результат опросом или из вебхука. Подходит, когда фото приходят с бэкенда, из приложения или из сценария, который не является страницей товара.

Способы можно сочетать: виджет на странице, а ваш сервер читает задачи того же аккаунта.

Справочник API строится из опубликованного документа OpenAPI, /api/v1/openapi.json. Базовый адрес: https://api.ziex-tryon.com. Все пути API начинаются с /api/v1/tryon.

Ключи¶

Каждый запрос несёт ключ в заголовке X-API-Key. Ключей три вида, и разница между ними важна.

	Секретный ключ	Публикуемый ключ	Тестовые ключи
Вид	`tryon_…`	`pk_…`	`tryon_test_…` и `pk_test_…`
Где может лежать	Только на вашем сервере	На публичной странице	На сервере / на стенде разработки
Работает с	Всеми эндпоинтами	`POST /tryon`, `GET /tryon/status/{job_id}`, `GET /tryon/attempts/{key}`, `GET /tryon/result/{job_id}`, `GET /tryon/domain-check`	Теми же, что и живой ключ-образец
Нужен `Origin` / `Referer`	Нет	Да, и привязанный домен	Да для `pk_test_…`; см. Локальная разработка
`webhook_url` в запросе	Разрешён	Запрещён (`403 WEBHOOK_NOT_ALLOWED`)	Разрешён только для `tryon_test_…`
Фото покупателя	URL или загрузка	Только загрузка (`422 PHOTO_UPLOAD_REQUIRED` для URL)	Только загрузка, для обоих видов
Тратит тариф	Да	Да	Никогда

Секретный ключ (`tryon_…`)¶

Используйте его на сервере. Никогда не кладите его в код страницы, в мобильное приложение или в репозиторий, который могут читать другие: этот же ключ открывает вход в личный кабинет клиента https://app.ziex-tryon.com, где видны фото ваших покупателей и результаты. Секретный ключ, пришедший с браузерным заголовком Origin, не отклоняется, но аккаунт помечает такой ключ предупреждением.

Секретный ключ видит задачи всего вашего аккаунта (только живые).

Публикуемый ключ (`pk_…`)¶

Единственный ключ, который можно разместить на публичной странице. Это тот же ключ, что и секретный, но с меньшими правами, и он публичен по замыслу: любой может скопировать его из кода страницы. Поэтому он ограничен:

Он работает только со страницы в браузере: каждый запрос обязан нести Origin или Referer, а ключ должен быть привязан к домену вашего магазина. Принимаются сам домен, www. и любой поддомен; другой сайт получает 403 DOMAIN_NOT_ALLOWED. Ключ без привязанного домена получает 403 KEY_NOT_BOUND.
Он принимает только пять перечисленных эндпоинтов и читает только задачи, созданные этим ключом.
Он не может заказать вебхук: webhook_url в запросе — это 403 WEBHOOK_NOT_ALLOWED.
Фото покупателя нужно отправлять загрузкой (data URI), не ссылкой. Одежда может остаться ссылкой.
Он ограничен на пару (ключ, IP клиента): 10 созданных задач за 10 минут.
Он не открывает вход в личный кабинет.

Живые и тестовые ключи¶

Тестовый ключ (секретный tryon_test_…, публикуемый pk_test_…) проходит весь настоящий путь API — те же проверки, обработка изображений, идемпотентность и ответы, — но не тратит ни денег, ни тариф: «примерка» заканчивается имитацией результата через несколько секунд. У тестовых ключей своя изоляция: тестовый ключ видит только свои тестовые задачи, живой ключ их не видит никогда, а тестовый ключ не может войти в личный кабинет. Вы выпускаете их сами в личном кабинете, до 3 на аккаунт. См. Локальная разработка.

Жизнь задачи¶

POST /api/v1/tryon с фото покупателя (model_image) и одеждой (garment_image). Ответ — 201 с job_id, заголовком X-Job-Id и Location с адресом статуса. Отправляйте Idempotency-Key, чтобы повтор запроса никогда не создал вторую задачу.
Пока задача ждёт воркер, она pending, затем processing.
Она заканчивается как completed (с result_url) либо failed / interrupted (с error_code и безопасным error_message).
Итог вы узнаёте опросом GET /api/v1/tryon/status/{job_id} либо из вебхука, если передали webhook_url (только секретный ключ). Виджет опрашивает сам.

Каждая задача приходит в конечное состояние не позже чем через 45 минут, что бы ни случилось. Вебхуки доставляются по мере возможности: если ваш приёмник недоступен, эндпоинт статуса всё равно говорит правду, поэтому опрос остаётся запасным путём.

Если ответ на POST потерян (оборвалось соединение, истёк таймаут), не отправляйте запрос заново под новым ключом: спросите задачу через GET /api/v1/tryon/attempts/{idempotency_key}. Подробности — в обоих кратких руководствах.

Тариф, лимиты и возвраты глазами клиента¶

Тариф. Тариф даёт определённое число генераций за период. Созданная задача забирает одну; когда тариф исчерпан, POST /tryon отвечает 429 LIMIT_EXCEEDED с Retry-After до сброса периода. Цифра тарифа применяется с небольшим допуском в 10 %.
Лимиты частоты. Есть лимиты на IP (30 отправок в минуту плюс собственные ограничения частоты в nginx), часовой лимит ключа и суточные потолки (один ключ не может занять больше половины суточного потолка платформы). Каждый 429, 409 и 503 несёт Retry-After в секундах: подождите столько. Сервер, отправляющий запросы всех своих покупателей с одного адреса, делит один бюджет на IP.
Возвраты. Задача, закончившаяся failed или interrupted, автоматически возвращает генерацию в ваш тариф — вскоре после этого, один раз и только в том периоде, в котором она была списана. Задача completed не возвращается никогда. Запрос, отклонённый до создания задачи (плохое фото, лимит), ничего не списывает.
Стоимость. Ziex Try-On никогда не показывает, во сколько нам обходится генерация; cost_credits в статусе всегда null.
Фото. Загруженные фото и результаты хранятся 180 дней, затем удаляются. Тестовые загрузки хранятся 72 часа.

Куда дальше¶

Вы хотите…	Читайте
Поставить виджет на страницу чистым HTML	Краткое руководство A — чистый HTML
Отправлять примерки с вашего сервера	Краткое руководство B — серверный вызов
Разрабатывать на `localhost` или на тестовом хосте без затрат	Локальная разработка
Найти опции, события и `update()` виджета	Справочник виджета
Загружать виджет лениво, не теряя идущую примерку	Ленивая загрузка и подхват
Разрешить виджет под Content Security Policy	Content Security Policy
Найти каждый эндпоинт, поле и ошибку	Справочник API
Задать вопрос	Контакты

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