Сесія з готового пакшота

Що ви отримаєте

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

Передумови

• Ключ API інсталяції (як його отримати) з дозволами: plugin.assets:upload, plugin.catalog:write, plugin.jobs:create, plugin.jobs:read.
• Файл пакшота (JPEG/PNG/WebP, до 50 МБ).

У прикладах замініть mk_live_… на свій ключ. Базова адреса — https://qamera.ai.

Перебіг

1. POST /assets/upload      → asset_id + тимчасова адреса для завантаження
2. PUT <upload_url>         → надішліть файл
3. POST /packshots          → зареєструйте пакшот (прийнятий одразу)
4. POST /jobs               → замовте фотосесію
5. webhook / GET /jobs/{id} → отримайте готові зображення
6. POST /jobs/{id}/accept   → (необов'язково) оцініть результати

Кроки

1. Отримайте тимчасову адресу для завантаження файлу

curl -X POST https://qamera.ai/api/v1/plugin/assets/upload \
  -H "X-Api-Key: mk_live_xxxxxxxx.yyyyyyyy" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "presigned",
    "filename": "kubek-packshot.jpg",
    "content_type": "image/jpeg",
    "size_bytes": 482310
  }'

Відповідь (HTTP 201):

{
  "asset_id": "9a3b8f4c-2e7a-4c1b-8d0a-1f6c2e9b3d51",
  "upload_url": "https://…/sign/…",
  "expires_at": "2026-06-03T14:00:00.000Z"
}

Збережіть asset_id — він знадобиться в кроці 3. Адреса upload_url дійсна 2 години; якщо вона спливе, просто попросіть нову.

2. Надішліть файл

curl -X PUT "$UPLOAD_URL" \
  --upload-file kubek-packshot.jpg \
  -H "Content-Type: image/jpeg"

3. Зареєструйте пакшот

Пакшоти, завантажені вами, приймаються автоматично — ми вважаємо, що раз ви їх обрали, вони готові до використання. Якщо продукту із вказаним product_ref ще немає в каталозі, передайте product_metadata.display_name, і його буде створено.

curl -X POST https://qamera.ai/api/v1/plugin/packshots \
  -H "X-Api-Key: mk_live_xxxxxxxx.yyyyyyyy" \
  -H "Content-Type: application/json" \
  -d '{
    "packshots": [
      {
        "external_ref": "sklep1:packshot-42",
        "product_ref": "sklep1:produkt-7",
        "product_metadata": { "display_name": "Kubek ceramiczny 300 ml" },
        "asset_id": "9a3b8f4c-2e7a-4c1b-8d0a-1f6c2e9b3d51"
      }
    ]
  }'

Відповідь (HTTP 200):

{
  "results": [
    {
      "external_ref": "sklep1:packshot-42",
      "product_id": "5e1f8a2c-9b4d-4a3e-8f7c-0d2a6e8b1c34",
      "packshot_id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
      "status": "created"
    }
  ]
}

Запам'ятайте product_ref (sklep1:produkt-7) — саме ним ви вкажете продукт у кроці 4. Повторний виклик із тим самим external_ref поверне status: "existing" замість створення дубліката.

4. Замовте фотосесію

Вам не потрібно вказувати packshot_asset_id — якщо ви його пропустите, сесія візьме найновіший прийнятий пакшот продукту (тобто той із кроку 3). Конфігурацію (стиль, сценерію, модель) можна отримати з каталогу — див. матеріал про параметри сесії.

curl -X POST https://qamera.ai/api/v1/plugin/jobs \
  -H "X-Api-Key: mk_live_xxxxxxxx.yyyyyyyy" \
  -H "Idempotency-Key: sklep1-zamowienie-1001" \
  -H "Content-Type: application/json" \
  -d '{
    "session_config": { "aspect_ratio": "4:5" },
    "subjects": [
      {
        "product_label": "Kubek ceramiczny 300 ml",
        "product_ref": "sklep1:produkt-7",
        "images_count": 4,
        "ai_model": "byteplus/seedream-4.5"
      }
    ]
  }'

Відповідь (HTTP 201):

{
  "order_id": "00000000-0000-0000-0000-000000000099",
  "status": "pending",
  "subjects": [
    {
      "product_ref": "sklep1:produkt-7",
      "job_ids": [
        "00000000-0000-0000-0000-0000000000a1",
        "00000000-0000-0000-0000-0000000000a2",
        "00000000-0000-0000-0000-0000000000a3",
        "00000000-0000-0000-0000-0000000000a4"
      ]
    }
  ]
}

Збережіть order_id (уся сесія) і job_ids (по одному завданню на зображення). Заголовок Idempotency-Key гарантує, що повторне надсилання того самого запиту (наприклад, після тайм-ауту) не створить другої сесії.

Значення ai_model (пара provider/model) візьміть з GET /ai-models — список залежить від плану акаунта продавця.

5. Отримайте готові зображення

Коли завдання завершиться, ми надішлемо вебхук на адресу вашої інсталяції — подробиці в матеріалі про отримання результатів. Можна також опитувати:

curl https://qamera.ai/api/v1/plugin/jobs/00000000-0000-0000-0000-0000000000a1 \
  -H "X-Api-Key: mk_live_xxxxxxxx.yyyyyyyy"

Завершене завдання має status: "completed" і список outputs[] з адресами для завантаження зображень. Адреси дійсні щонайменше 7 днів — після цього отримайте свіжі через POST /jobs/{id}/refresh-url.

6. (Необов'язково) Оцініть результати

Ви можете зберегти оцінку продавця для кожного зображення. Для фотосесії це суто зворотний зв'язок — він не змінює ані кредитів, ані чогось у каталозі.

curl -X POST https://qamera.ai/api/v1/plugin/jobs/00000000-0000-0000-0000-0000000000a1/accept \
  -H "X-Api-Key: mk_live_xxxxxxxx.yyyyyyyy"

Повертає 204 No Content. Аналогічно працює …/reject.

Поширені помилки

Що далі

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