Parametry sesji

Co osiągniesz

Zanim wyślesz sesję, sprzedawca powinien móc wybrać styl, scenerię, modelkę i proporcje zdjęć. W tym samouczku pobierzesz wszystkie dane katalogowe i dowiesz się, które pola nadają się do zbudowania ekranu wyboru w Twojej wtyczce — z miniaturami, galeriami i kosztem w kredytach.

Wymagania wstępne

• Klucz API instalacji (jak go zdobyć) z uprawnieniem plugin.catalog:read.

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

Przebieg

GET /presets        → style z miniaturami, galeriami i kosztem
GET /models         → modelki (konto + marketplace)
GET /sceneries      → scenerie (konto + marketplace)
GET /ai-models      → modele AI dostępne dla planu konta
GET /aspect-ratios  → proporcje obrazu (jedna domyślna)
GET /pricing        → cennik kredytowy (opcjonalnie, do podsumowania)

Wybrane wartości trafiają potem do POST /jobs: preset_id, model_id, scenery_id i aspect_ratio do session_config, a para provider/model do subjects[].ai_model.

Kroki

1. Pobierz style (presety)

curl https://qamera.ai/api/v1/plugin/presets \
  -H "X-Api-Key: mk_live_xxxxxxxx.yyyyyyyy"

Odpowiedź (HTTP 200):

{
  "presets": [
    {
      "id": "rec123",
      "slug": "fashion-flatlay",
      "name": "Fashion flatlay",
      "description_i18n": { "en": "Flatlay product on neutral background" },
      "credit_cost": 10,
      "output_type": "packshot",
      "is_free": false,
      "cover_url": "https://…/reference_assets/presets/rec123/cover.jpg",
      "quantity_guidelines": "Provide 3-5 photos per product.",
      "quality_guidelines": "Use natural daylight; avoid reflective surfaces.",
      "gallery": [
        "https://…/reference_assets/presets/rec123/g1.jpg",
        "https://…/reference_assets/presets/rec123/g2.jpg"
      ]
    }
  ]
}

Do ekranu wyboru wykorzystasz:

• name i description_i18n — nazwa i opis stylu (wybierz język wtyczki),
• cover_url — miniatura kafelka,
• gallery[] — przykładowe realizacje (adresy publiczne, bez uwierzytelniania),
• credit_cost i is_free — koszt do pokazania przy kafelku,
• quantity_guidelines / quality_guidelines — wskazówki dla sprzedawcy, co i jak sfotografować (mogą być puste).

Wybrany styl wskażesz w sesji polem session_config.preset_id (wartość id).

2. Pobierz modelki i scenerie

curl https://qamera.ai/api/v1/plugin/models \
  -H "X-Api-Key: mk_live_xxxxxxxx.yyyyyyyy"

curl https://qamera.ai/api/v1/plugin/sceneries \
  -H "X-Api-Key: mk_live_xxxxxxxx.yyyyyyyy"

Obie listy mają ten sam kształt wpisu:

{
  "models": [
    {
      "id": "5e1f8a2c-9b4d-4a3e-8f7c-0d2a6e8b1c34",
      "name": "Brand Mannequin A",
      "thumbnail": "https://…/reference_assets/mannequin/recAcct1/large.jpg",
      "voting": "APPROVED",
      "status": "DONE",
      "source": "account",
      "created_at": "2026-05-10T12:00:00.000Z"
    }
  ]
}

Do ekranu wyboru: name, thumbnail i source — "account" to zasoby własne konta sprzedawcy, "marketplace" to katalog publiczny Qamera (możesz je rozdzielić na dwie zakładki). Wpisy odrzucone i zarchiwizowane są odfiltrowane po stronie serwera — wszystko, co dostajesz, można pokazać.

Wybrane pozycje wskażesz polami session_config.model_id i session_config.scenery_id (wartości id). Oba pola są opcjonalne.

3. Pobierz modele AI

curl https://qamera.ai/api/v1/plugin/ai-models \
  -H "X-Api-Key: mk_live_xxxxxxxx.yyyyyyyy"

{
  "ai_models": [
    {
      "id": "byteplus/seedream-4.5",
      "provider": "byteplus",
      "model": "seedream-4.5",
      "output_type": "image",
      "supported_aspect_ratios": ["9:16", "16:9", "1:1", "4:3", "3:4"],
      "base_credit_cost": 10
    }
  ]
}

Lista jest już przefiltrowana pod plan konta sprzedawcy — każdy zwrócony wpis przejdzie w POST /jobs. Wartość id (para provider/model) trafia wprost do subjects[].ai_model. Pole supported_aspect_ratios ogranicza wybór proporcji dla danego modelu, a base_credit_cost to koszt jednego zdjęcia.

4. Pobierz proporcje obrazu

curl https://qamera.ai/api/v1/plugin/aspect-ratios \
  -H "X-Api-Key: mk_live_xxxxxxxx.yyyyyyyy"

{
  "aspect_ratios": [
    { "value": "1:1", "label": "Square", "default": false },
    { "value": "4:5", "label": "Portrait", "default": true },
    { "value": "9:16", "label": "Story/Reel", "default": false },
    { "value": "16:9", "label": "Landscape", "default": false },
    { "value": "3:4", "label": "Classic Portrait", "default": false }
  ]
}

Dokładnie jeden wpis ma default: true — zaznacz go jako domyślny wybór. Wybrana wartość trafia do session_config.aspect_ratio.

5. (Opcjonalnie) Policz koszt sesji

curl https://qamera.ai/api/v1/plugin/pricing \
  -H "X-Api-Key: mk_live_xxxxxxxx.yyyyyyyy"

Zwraca płaską tabelę {job_type, provider, model, credit_cost} (wpis model: "*" to cena domyślna dla całego dostawcy). Koszt sesji policzysz jako sumę credit_cost × images_count po produktach — pokaż ją sprzedawcy przed wysłaniem. Aktualny stan kredytów konta znajdziesz w GET /me (pole credits_balance).

Pamięć podręczna (cache)

Te dane zmieniają się rzadko — nie pobieraj ich przy każdym otwarciu ekranu:

Częste błędy

Co dalej

• Sesja z gotowego packshota — użyj wybranych parametrów w sesji.
• Sesje hurtowo — ta sama konfiguracja dla wielu produktów.