Ендпойнти

Канонічним контрактом є специфікація OpenAPI 3.1 (YAML) — там ви знайдете повні схеми та всі відповіді про помилки. Ця сторінка стисло підсумовує кожен маршрут. Якщо ви тільки починаєте, пройдіть спершу основні процеси.

Несумісна зі зворотним боком зміна (травень 2026). POST /jobs і POST /jobs/batch більше не приймають давнє тіло окремого завдання. Тепер ви надсилаєте сесію — одну session_config (модель, сценерія, стиль, пропорції, поради) плюс список subjects[], де кожен продукт розгортається в images_count завдань генерації. Див. нотатку про міграцію у кінці сторінки.

Ідентичність

GET /me

Повертає дані вашої інсталяції та облікового запису продавця: стан кредитів, план, ліміт запитів, фактичні дозволи й актуальний перелік субобробників.

Дозвіл: будь-який дійсний ключ.

Завдання

POST /jobs

Замовте одну фотосесію. Тіло: {job_type?, session_config, subjects[]} — одна спільна конфігурація для всіх продуктів; сервер створює images_count завдань для кожного продукту. Відповідь: {order_id, status, subjects: [{product_ref, job_ids: [...]}]}.

Навчальні матеріали: сесія з готового пакшота, пакшот із фото, параметри сесії.

Дозвіл: plugin.jobs:create. Ідемпотентність: підтримується (заголовок Idempotency-Key, вікно 24 год).

Вимога прийнятого пакшота

Фотосесія (job_type пропущено або photo_shoot) вимагає, щоб кожен продукт мав прийнятий пакшот:

• Якщо ви пропустите subjects[].packshot_asset_id, сервер сам обере найновіший прийнятий пакшот продукту, вказаного через product_ref.
• Якщо ви вкажете packshot_asset_id явно, він має вказувати на прийнятий пакшот того самого продукту.
• Якщо продукт не має прийнятого пакшота, увесь виклик повертає 422 packshot_not_approved — нічого не створюється і жодні кредити не списуються.

Як довести продукт до прийнятого пакшота — крок за кроком у навчальному матеріалі „Пакшот із фото".

Генерація пакшотів

З job_type: "packshot" ви замовляєте варіанти пакшота зі звичайного фото. Кожен продукт у сесії має тоді мати packshot_asset_id (вхідне фото) та auto_register_packshot: true (згенерований варіант потрапляє до каталогу продукту). Варіанти не приймаються автоматично — обраний ви затверджуєте через POST /jobs/{id}/accept.

POST /jobs/batch

Замовте до 100 сесій за один виклик. Тіло: {batches: [...]} — кожен запис це незалежна сесія. Ліміти: 100 сесій і 5000 зображень загалом на виклик. Відповідь — HTTP 207 з результатом для кожної сесії. Навчальний матеріал: сесії гуртом.

Дозвіл: plugin.jobs:create. Ідемпотентність: немає в v1 — невдалі сесії повторюйте по одній через POST /jobs із власним Idempotency-Key.

GET /jobs

Повертає список ваших завдань генерації, від найновіших. Параметри: status, created_after, created_before, limit (за замовчуванням 50, макс. 200), cursor (посторінкове гортання).

Дозвіл: plugin.jobs:read.

GET /jobs/{id}

Повертає одне завдання: статус, дані продукту (product_label, product_ref, packshot_asset_id), оцінку (voting, voting_at) і — для завершених завдань — список outputs[] з адресами для завантаження зображень (дійсні щонайменше 7 днів). Навчальний матеріал: отримання результатів.

Дозвіл: plugin.jobs:read.

POST /jobs/{id}/accept

Записує прийняття завершеного завдання. Наслідок залежить від типу завдання:

• завдання packshot — згенерований пакшот стає прийнятим пакшотом продукту й розблоковує фотосесії (див. вимогу прийнятого пакшота),
• завдання photo_shoot — виключно зворотний зв'язок; не змінює кредитів, файлів чи каталогу.

Повертає 204. 404, коли завдання належить іншій інсталяції; 409 job_not_completed, коли завдання не завершилося. Повторна оцінка перезаписує попередню.

Дозвіл: plugin.jobs:read.

POST /jobs/{id}/reject

Записує відхилення завершеного завдання. Той самий контракт, що й accept — зокрема наслідок для каталогу при завданнях packshot: відхилений варіант не використовуватиметься у фотосесіях.

Дозвіл: plugin.jobs:read.

POST /jobs/{id}/refresh-url

Повертає свіжі адреси для завантаження завершеного завдання — використайте, коли попередні минули (через 7 днів). 409 job_not_completed, коли завдання ще триває; 410, коли файли вже видалено згідно з політикою зберігання.

Дозвіл: plugin.jobs:read.

DELETE /jobs/{id}

Скасовує завдання, що ще не стартувало, і вивільняє резервацію кредитів. 409 job_not_cancelable, коли завдання вже виконується або завершилося.

Дозвіл: plugin.jobs:cancel.

Сесії (замовлення)

GET /orders/{id}

Повертає всю сесію: конфігурацію (session_config), стан для кожного продукту (jobs_total, jobs_completed, jobs_failed), згенеровані зображення та підсумок кредитів (summary). Сесії інших інсталяцій повертають 404.

Дозвіл: plugin.jobs:read.

POST /orders/{id}/clone

Створює нову сесію з конфігурацією та продуктами вихідної сесії. Порожнє тіло копіює продукти 1:1; тіло з subjects[] — це повна заміна списку: клонуються лише перелічені продукти, кожен із новою images_count. Оцінки не переносяться; кредити нараховуються заново. Навчальний матеріал: повторна сесія.

Дозвіл: plugin.jobs:create. Ідемпотентність: обов'язкова — заголовок Idempotency-Key є обов'язковим.

Файли

POST /assets/upload

Повертає тимчасову адресу для завантаження файлу (фото продукту). Тіло: {mode: "presigned", filename, content_type, size_bytes} (макс. 50 МБ). Надішліть байти на повернутий upload_url методом PUT протягом 2 годин. Повернутий asset_id ви вкажете під час реєстрації фото чи пакшота.

Дозвіл: plugin.assets:upload.

Стилі (пресети)

GET /presets

Повертає список стилів, доступних продавцеві — з назвою, описом, мініатюрою, галереєю прикладів, вартістю в кредитах і підказками щодо вхідних фото. Навчальний матеріал: параметри сесії.

Дозвіл: plugin.catalog:read або plugin.jobs:read (старіші інсталяції зберігають доступ).

Довідкові дані

З цих ендпойнтів ви побудуєте екран вибору параметрів сесії — див. навчальний матеріал про параметри. Усі вимагають дозволу plugin.catalog:read.

GET /models

Повертає моделі, доступні продавцеві — власні акаунта та з каталогу Qamera. Кожен запис: id, name, thumbnail, source ('account' / 'marketplace'). Відхилені та архівні позиції відфільтровано.

GET /sceneries

Сценерії — та сама форма й правила, що й у /models.

GET /ai-models

Повертає AI-моделі, які може використати обліковий запис продавця (список залежить від плану). Кожен запис: id ("provider/model" — потрапляє до subjects[].ai_model), output_type, supported_aspect_ratios[], base_credit_cost. Кожен повернутий запис пройде у POST /jobs.

Кешуйте лише приватно: Cache-Control: private, max-age=300, Vary: X-Api-Key.

GET /aspect-ratios

Повертає підтримувані пропорції зображення — рівно одна має default: true. Кешуйте сміливо: Cache-Control: public, max-age=3600.

GET /pricing

Повертає прайс-лист у кредитах за (job_type, provider, model) — запис model: "*" це ціна провайдера за замовчуванням. Узгоджений із base_credit_cost з /ai-models. Кешування: Cache-Control: public, max-age=300.

Каталог продуктів

Постійний каталог продуктів продавця, їхніх джерельних фото та пакшотів. Записи ви ідентифікуєте власними, стабільними ідентифікаторами (external_ref) — саме вони пов'язують ваш магазин із Qamera AI. Масові ендпойнти приймають до 100 елементів на виклик. Записи інших інсталяцій повертають 404.

POST /images

Реєструє джерельні фото продуктів (завантажені раніше через /assets/upload). Створює продукт автоматично, коли product_ref новий і ви вказали product_metadata.display_name. Повторний виклик із тим самим external_ref повертає наявний рядок (status: "existing"). Навчальний матеріал: пакшот із фото.

Дозвіл: plugin.catalog:write.

POST /packshots

Реєструє готові пакшоти. Пакшоти, завантажені цим шляхом, приймаються автоматично — одразу задовольняють вимогу для фотосесій. source_image_ref (необов'язковий) пов'язує пакшот із джерельним фото. Навчальний матеріал: сесія з готового пакшота.

Дозвіл: plugin.catalog:write.

GET /products

Повертає список ваших продуктів (гортання курсором): id, external_ref, display_name, sku, image_count, packshot_count. Видалені продукти за замовчуванням пропущено.

Дозвіл: plugin.catalog:read.

GET /products/{id_or_ref}

Повертає один продукт із вкладеними фото та пакшотами (до 100 кожних; прапори images_truncated / packshots_truncated сигналізують, що їх більше). У шляху ви вкажете UUID або власний external_ref. Кожен вкладений пакшот також містить свою оцінку (voting, voting_at) — ті самі поля, що й у GET /packshots.

Дозвіл: plugin.catalog:read.

DELETE /products/{id_or_ref}

Видаляє продукт (м'яко — фото й пакшоти залишаються). Той самий external_ref ви можете потім зареєструвати знову як новий продукт.

Дозвіл: plugin.catalog:write.

GET /packshots

Повертає список ваших пакшотів (гортання курсором). Параметр product_ref звужує до одного продукту. Кожен пакшот містить свою оцінку: voting (pending, accepted або rejected) та voting_at (момент рішення). Пакшот із voting: "accepted" відповідає вимозі прийнятого пакшота — тут ви перевірите, який пакшот розблоковує фотосесії продукту. Пакшоти, зареєстровані через POST /packshots, прийняті одразу.

Дозвіл: plugin.catalog:read.

DELETE /packshots/{id_or_ref}

Видаляє запис пакшота з каталогу. Сам файл залишається — на нього можуть посилатися інші записи.

Дозвіл: plugin.catalog:write.

Інсталяція

POST /installations/{id}/rotate-hmac

Замінює секрет HMAC для підписування вебхуків. Попередній секрет діє ще 48 годин, тож повідомлення в дорозі не пропадуть. Новий секрет є у відповіді — ми показуємо його лише раз.

Дозвіл: plugin.installations.manage.

Вебхуки

POST /webhooks/{delivery_id}/replay

Повторно надсилає повідомлення webhook — використайте, коли ваш ендпойнт не працював у вікні автоматичних повторів. Навчальний матеріал: отримання результатів.

Дозвіл: plugin.webhooks:manage.

Міграція з попереднього формату v1

Давнє тіло POST /jobs ({job_type, provider, model, unit_cost, settings}) та давнє тіло POST /jobs/batch ({jobs: [...]}) більше не підтримуються й повертають 400 invalid_input.

Перехід на формат сесії:

1. Оберніть наявні параметри окремого завдання в один запис subjects[]: {packshot_asset_id, product_label, product_ref, images_count, ai_model: "provider/model"}.
2. Винесіть модель/сценерію/стиль/пропорції до session_config. Поле ai_model замінює давнє трио provider/model/unit_cost — вартість обчислюється на боці сервера.
3. У викликах batch змініть jobs на batches — кожен запис це одна повна сесія.
4. Повідомлення webhook містять тепер додаткові поля (packshot_asset_id, product_label, product_ref, voting, voting_at) — ви можете їх ігнорувати, якщо вони вам не потрібні.