Sesje hurtowo

Co osiągniesz

Sprzedawca chce obfotografować cały asortyment. W tym samouczku wyślesz wiele sesji w jednym wywołaniu, odczytasz wynik dla każdej z osobna (częściowy sukces) i dowiesz się, jak bezpiecznie ponawiać nieudane sesje.

Najpierw wybierz właściwe narzędzie:

• Wiele produktów, jedna konfiguracja → jedna sesja POST /jobs z wieloma wpisami w subjects[] (do 100 produktów). Prostsze i z obsługą Idempotency-Key.
• Wiele sesji o różnych konfiguracjach → POST /jobs/batch (do 100 sesji w jednym wywołaniu).

Wymagania wstępne

• Klucz API instalacji (jak go zdobyć) z uprawnieniami plugin.jobs:create, plugin.jobs:read.
• Każdy produkt ma zaakceptowany packshot — zobacz samouczek A lub B.

W przykładach zamień mk_live_… na swój klucz. Bazowy adres to https://qamera.ai.

Przebieg

1. Przygotuj sesje (produkty + konfiguracja)
2. POST /jobs/batch  → do 100 sesji naraz
3. HTTP 207          → wynik per sesja (accepted / failed)
4. Ponów nieudane sesje pojedynczo przez POST /jobs
5. Odbierz wyniki przez webhooki lub odpytywanie

Limity

Przekroczenie limitów batcha odrzuca całe wywołanie — żadna sesja nie zostaje przyjęta. Zobacz batch_limit_exceeded.

Kroki

1. Wyślij batch sesji

Każdy wpis w batches[] to niezależna sesja — z własną konfiguracją i własnymi produktami:

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. Odczytaj wynik per sesja (HTTP 207)

Batch zawsze odpowiada statusem 207 Multi-Status: każda sesja przeszła albo odpadła niezależnie. Indeksy w results[] odpowiadają kolejności w 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
}

Zapisz order_id każdej przyjętej sesji. Dla nieudanych sesji error.code mówi, co poprawić — tutaj produkt 9 nie ma zaakceptowanego packshota.

3. Ponów nieudane sesje pojedynczo

Batch nie obsługuje nagłówka Idempotency-Key — ponowienie całego batcha po time-oucie mogłoby zduplikować przyjęte już sesje. Bezpieczny wzorzec:

1. Wyślij batch raz.
2. Sesje z status: "failed" popraw i wyślij pojedynczo przez POST /jobs, każdą z własnym 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" }
    ]
  }'

Dzięki Idempotency-Key ponowna wysyłka tego samego żądania (w ciągu 24 godzin) zwróci tę samą sesję zamiast tworzyć drugą.

4. Odbierz wyniki

Przy hurtowych zamówieniach webhooki są wygodniejsze niż odpytywanie — dostaniesz osobne powiadomienie o każdym ukończonym zadaniu. Zobacz odbieranie wyników. Stan całej sesji (ile zadań ukończonych, ile nieudanych) sprawdzisz jednym wywołaniem:

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

Częste błędy

Co dalej

• Odbieranie wyników — webhooki przy dużej skali.
• Ponowna sesja — dogeneruj zdjęcia dla wybranych produktów.