Session parameters

What you'll achieve

Before you submit a session, the merchant should be able to choose a style, scenery, model, and image aspect ratio. In this tutorial you'll fetch all the catalog data and learn which fields are useful for building a picker screen in your plugin — with thumbnails, galleries, and the cost in credits.

Prerequisites

• A plugin installation API key (how to get one) with the plugin.catalog:read permission.

In the examples, replace mk_live_… with your own key. The base address is https://qamera.ai.

Flow

GET /presets        → styles with thumbnails, galleries, and cost
GET /models         → models (account + marketplace)
GET /sceneries      → sceneries (account + marketplace)
GET /ai-models      → AI models available to the account's plan
GET /aspect-ratios  → image aspect ratios (one default)
GET /pricing        → credit pricing (optional, for the summary)

Your selected values then go into POST /jobs: preset_id, model_id, scenery_id, and aspect_ratio into session_config, and the provider/model pair into subjects[].ai_model.

Steps

1. Fetch the styles (presets)

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

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

For the picker screen you'll use:

• name and description_i18n — the style's name and description (pick the plugin's language),
• cover_url — the tile thumbnail,
• gallery[] — example results (public URLs, no authentication),
• credit_cost and is_free — the cost to show next to the tile,
• quantity_guidelines / quality_guidelines — hints for the merchant on what to photograph and how (may be empty).

You point to the chosen style in the session via the session_config.preset_id field (the id value).

2. Fetch models and sceneries

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"

Both lists share the same entry shape:

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

For the picker screen: name, thumbnail, and source — "account" means the merchant account's own resources, "marketplace" means Qamera's public catalog (you can split them into two tabs). Rejected and archived entries are filtered out server-side — everything you receive is safe to show.

You point to the chosen items via the session_config.model_id and session_config.scenery_id fields (the id values). Both fields are optional.

3. Fetch the AI models

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

The list is already filtered to the merchant account's plan — every returned entry will be accepted by POST /jobs. The id value (the provider/model pair) goes straight into subjects[].ai_model. The supported_aspect_ratios field limits the aspect ratio choice for a given model, and base_credit_cost is the cost of a single image.

4. Fetch the aspect ratios

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

Exactly one entry has default: true — mark it as the default choice. The selected value goes into session_config.aspect_ratio.

5. (Optional) Calculate the session cost

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

Returns a flat table {job_type, provider, model, credit_cost} (an entry with model: "*" is the default price for the whole provider). You calculate the session cost as the sum of credit_cost × images_count across products — show it to the merchant before submitting. The account's current credit balance is in GET /me (the credits_balance field).

Cache

This data changes rarely — don't fetch it every time the screen opens:

Common errors

Next steps

• Session from a packshot — use the chosen parameters in a session.
• Bulk sessions — the same configuration for many products.