Сесії гуртом

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

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

Спершу оберіть правильний інструмент:

• Багато продуктів, одна конфігурація → одна сесія POST /jobs з багатьма записами в subjects[] (до 100 продуктів). Простіше й з підтримкою Idempotency-Key.
• Багато сесій із різними конфігураціями → POST /jobs/batch (до 100 сесій в одному виклику).

Передумови

• Ключ API інсталяції (як його отримати) з дозволами plugin.jobs:create, plugin.jobs:read.
• Кожен продукт має прийнятий пакшот — див. матеріал A або B.

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

Перебіг

1. Підготуйте сесії (продукти + конфігурація)
2. POST /jobs/batch  → до 100 сесій одночасно
3. HTTP 207          → результат для кожної сесії (accepted / failed)
4. Повторіть невдалі сесії поодинці через POST /jobs
5. Отримайте результати через вебхуки або опитування

Ліміти

Перевищення лімітів батча відхиляє весь виклик — жодна сесія не приймається. Див. batch_limit_exceeded.

Кроки

1. Надішліть батч сесій

Кожен запис у batches[] — це незалежна сесія: з власною конфігурацією й власними продуктами:

curl -X POST https://qamera.ai/api/v1/plugin/jobs/batch \
  -H "X-Api-Key: mk_live_xxxxxxxx.yyyyyyyy" \
  -H "Content-Type: application/json" \
  -d '{
    "batches": [
      {
        "session_config": { "aspect_ratio": "4:5" },
        "subjects": [
          { "product_label": "Kubek ceramiczny", "product_ref": "sklep1:produkt-7", "images_count": 4, "ai_model": "byteplus/seedream-4.5" },
          { "product_label": "Talerz deserowy", "product_ref": "sklep1:produkt-8", "images_count": 4, "ai_model": "byteplus/seedream-4.5" }
        ]
      },
      {
        "session_config": { "aspect_ratio": "9:16" },
        "subjects": [
          { "product_label": "Dzbanek szklany", "product_ref": "sklep1:produkt-9", "images_count": 6, "ai_model": "byteplus/seedream-4.5" }
        ]
      }
    ]
  }'

2. Прочитайте результат для кожної сесії (HTTP 207)

Батч завжди відповідає статусом 207 Multi-Status: кожна сесія пройшла або відпала незалежно. Індекси в results[] відповідають порядку в batches[].

{
  "results": [
    {
      "index": 0,
      "status": "accepted",
      "result": {
        "order_id": "00000000-0000-0000-0000-000000000123",
        "status": "pending",
        "subjects": [
          { "product_ref": "sklep1:produkt-7", "job_ids": ["…"] },
          { "product_ref": "sklep1:produkt-8", "job_ids": ["…"] }
        ]
      }
    },
    {
      "index": 1,
      "status": "failed",
      "error": {
        "code": "packshot_not_approved",
        "message_i18n": { "en": "No accepted packshot found for product_ref=\"sklep1:produkt-9\"…" },
        "retryable": false
      }
    }
  ],
  "accepted_count": 1,
  "failed_count": 1
}

Збережіть order_id кожної прийнятої сесії. Для невдалих сесій error.code підкаже, що виправити — тут продукт 9 не має прийнятого пакшота.

3. Повторіть невдалі сесії поодинці

Батч не підтримує заголовка Idempotency-Key — повтор усього батча після тайм-ауту міг би продублювати вже прийняті сесії. Безпечний підхід:

1. Надішліть батч один раз.
2. Сесії зі status: "failed" виправте й надішліть поодинці через POST /jobs, кожну з власним Idempotency-Key:

curl -X POST https://qamera.ai/api/v1/plugin/jobs \
  -H "X-Api-Key: mk_live_xxxxxxxx.yyyyyyyy" \
  -H "Idempotency-Key: sklep1-sesja-produkt-9-retry1" \
  -H "Content-Type: application/json" \
  -d '{
    "session_config": { "aspect_ratio": "9:16" },
    "subjects": [
      { "product_label": "Dzbanek szklany", "product_ref": "sklep1:produkt-9", "images_count": 6, "ai_model": "byteplus/seedream-4.5" }
    ]
  }'

Завдяки Idempotency-Key повторне надсилання того самого запиту (протягом 24 годин) поверне ту саму сесію замість створення другої.

4. Отримайте результати

Для гуртових замовлень вебхуки зручніші за опитування — ви отримаєте окреме сповіщення про кожне завершене завдання. Див. отримання результатів. Стан усієї сесії (скільки завдань завершено, скільки невдалих) перевірите одним викликом:

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

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

Що далі

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