Параметри сесії

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

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

Передумови

• Ключ API інсталяції (як його отримати) з дозволом plugin.catalog:read.

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

Перебіг

GET /presets        → стилі з мініатюрами, галереями та вартістю
GET /models         → моделі (акаунт + маркетплейс)
GET /sceneries      → сценерії (акаунт + маркетплейс)
GET /ai-models      → AI-моделі, доступні для плану акаунта
GET /aspect-ratios  → пропорції зображення (одна за замовчуванням)
GET /pricing        → прайс кредитів (необов'язково, для підсумку)

Обрані значення потім потрапляють до POST /jobs: preset_id, model_id, scenery_id та aspect_ratio — до session_config, а пара provider/model — до subjects[].ai_model.

Кроки

1. Отримайте стилі (пресети)

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

Відповідь (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"
      ]
    }
  ]
}

Для екрана вибору ви використаєте:

• name і description_i18n — назва й опис стилю (оберіть мову плагіна),
• cover_url — мініатюра плитки,
• gallery[] — приклади реалізацій (публічні адреси, без автентифікації),
• credit_cost і is_free — вартість для показу на плитці,
• quantity_guidelines / quality_guidelines — підказки продавцеві, що і як сфотографувати (можуть бути порожні).

Обраний стиль вкажете в сесії полем session_config.preset_id (значення id).

2. Отримайте моделі та сценерії

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"

Обидва списки мають однакову форму запису:

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

Для екрана вибору: name, thumbnail і source — "account" це власні ресурси акаунта продавця, "marketplace" це публічний каталог Qamera (їх можна розділити на дві вкладки). Відхилені й заархівовані записи відфільтровуються на стороні сервера — усе, що ви отримуєте, можна показати.

Обрані позиції вкажете полями session_config.model_id і session_config.scenery_id (значення id). Обидва поля необов'язкові.

3. Отримайте 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
    }
  ]
}

Список уже відфільтровано під план акаунта продавця — кожен повернутий запис пройде в POST /jobs. Значення id (пара provider/model) потрапляє просто в subjects[].ai_model. Поле supported_aspect_ratios обмежує вибір пропорцій для конкретної моделі, а base_credit_cost — це вартість одного зображення.

4. Отримайте пропорції зображення

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

Рівно один запис має default: true — позначте його як вибір за замовчуванням. Обране значення потрапляє до session_config.aspect_ratio.

5. (Необов'язково) Порахуйте вартість сесії

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

Повертає пласку таблицю {job_type, provider, model, credit_cost} (запис model: "*" — це ціна за замовчуванням для всього постачальника). Вартість сесії порахуєте як суму credit_cost × images_count по продуктах — покажіть її продавцеві перед надсиланням. Поточний стан кредитів акаунта знайдете в GET /me (поле credits_balance).

Кеш (cache)

Ці дані змінюються рідко — не отримуйте їх щоразу, коли відкривається екран:

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

Що далі

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