Sesja z gotowego packshota

Co osiągniesz

Sprzedawca ma już packshot produktu — zdjęcie na czystym, neutralnym tle. W tym samouczku wgrasz ten plik, zarejestrujesz go jako packshot (zostanie zaakceptowany automatycznie), zamówisz sesję zdjęciową i odbierzesz gotowe zdjęcia.

Wymagania wstępne

• Klucz API instalacji (jak go zdobyć) z uprawnieniami: plugin.assets:upload, plugin.catalog:write, plugin.jobs:create, plugin.jobs:read.
• Plik packshota (JPEG/PNG/WebP, do 50 MB).

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

Przebieg

1. POST /assets/upload      → asset_id + tymczasowy adres do wgrania
2. PUT <upload_url>         → wyślij plik
3. POST /packshots          → zarejestruj packshot (zaakceptowany od razu)
4. POST /jobs               → zamów sesję zdjęciową
5. webhook / GET /jobs/{id} → odbierz gotowe zdjęcia
6. POST /jobs/{id}/accept   → (opcjonalnie) oceń wyniki

Kroki

1. Pobierz tymczasowy adres do wgrania pliku

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
  }'

Odpowiedź (HTTP 201):

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

Zapisz asset_id — użyjesz go w kroku 3. Adres upload_url jest ważny 2 godziny; jeśli wygaśnie, po prostu poproś o nowy.

2. Wyślij plik

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

3. Zarejestruj packshot

Packshoty wgrane przez Ciebie są akceptowane automatycznie — uznajemy, że skoro je wybrałeś, są gotowe do użycia. Jeśli produkt o podanym product_ref jeszcze nie istnieje w katalogu, podaj product_metadata.display_name, a zostanie utworzony.

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"
      }
    ]
  }'

Odpowiedź (HTTP 200):

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

Zapamiętaj product_ref (sklep1:produkt-7) — to nim wskażesz produkt w kroku 4. Ponowne wywołanie z tym samym external_ref zwróci status: "existing" zamiast tworzyć duplikat.

4. Zamów sesję zdjęciową

Nie musisz podawać packshot_asset_id — gdy go pominiesz, sesja użyje najnowszego zaakceptowanego packshota produktu (czyli tego z kroku 3). Konfigurację (styl, scenerię, modelkę) możesz pobrać z katalogu — zobacz samouczek o parametrach sesji.

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"
      }
    ]
  }'

Odpowiedź (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"
      ]
    }
  ]
}

Zapisz order_id (cała sesja) i job_ids (po jednym zadaniu na zdjęcie). Nagłówek Idempotency-Key sprawia, że ponowna wysyłka tego samego żądania (np. po time-oucie) nie utworzy drugiej sesji.

Wartość ai_model (para provider/model) pobierz z GET /ai-models — lista zależy od planu konta sprzedawcy.

5. Odbierz gotowe zdjęcia

Gdy zadanie się zakończy, wyślemy webhook na adres Twojej instalacji — szczegóły w samouczku o odbieraniu wyników. Możesz też odpytywać:

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

Zadanie zakończone ma status: "completed" i listę outputs[] z adresami do pobrania zdjęć. Adresy są ważne co najmniej 7 dni — po tym czasie pobierz świeże przez POST /jobs/{id}/refresh-url.

6. (Opcjonalnie) Oceń wyniki

Możesz zapisać ocenę sprzedawcy dla każdego zdjęcia. Dla sesji zdjęciowej to czysta informacja zwrotna — nie zmienia kredytów ani niczego w katalogu.

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

Zwraca 204 No Content. Analogicznie działa …/reject.

Częste błędy

Co dalej

• Packshot ze zdjęcia — gdy sprzedawca nie ma gotowego packshota.
• Parametry sesji — style, scenerie i modelki do wyboru.
• Odbieranie wyników — webhooki, ponowienia, odświeżanie adresów.