Sceneries

List and generate sceneries and backgrounds for product photography.

GET /api/external/sceneries

Returns a list of available sceneries and backgrounds.

Headers

Header	Required	Description
X-Api-Key	Yes	Your API key in the format `mk_live_xxx.secret`

Query Parameters

Field	Type	Required	Description
statusFilter	string	No	Filter by status: `all` (default) or `approved`

Response

{
  "sceneries": [
    {
      "id": "scenery_abc123",
      "name": "Modern Studio - White Background",
      "thumbnail": "https://cdn.example.com/sceneries/thumb_abc123.jpg",
      "status": "DONE",
      "voting": "APPROVED",
      "createdAt": "2026-03-20T13:00:00.000Z"
    }
  ],
  "count": 1
}

Error Responses

Code	Meaning
401	Missing or invalid API key
500	Internal server error

Notes

No credits are consumed by this endpoint.

Example

curl -X GET "https://app.qamera.ai/api/external/sceneries?statusFilter=approved" \
  -H "X-Api-Key: mk_live_abc123.secret456"

POST /api/external/sceneries/register-ideas

Registers a new scenery generation job. Credits are reserved immediately and consumed after processing completes.

Headers

Header	Required	Description
X-Api-Key	Yes	Your API key in the format `mk_live_xxx.secret`
Content-Type	Yes	`application/json`

Request Body

Field	Type	Required	Description
preferences	string	Yes	Text description of the desired scenery or background
count	number	No	Number of sceneries to generate (default: 10, max: 20)

Response

{
  "createdRecordIds": ["scenery_001", "scenery_002", "scenery_003"],
  "batchId": "batch_abc123",
  "orderId": "order_xyz789",
  "reservationId": "res_def456",
  "creditsReserved": 30
}

Error Responses

Code	Meaning
400	Invalid request body or missing preferences
401	Missing or invalid API key
402	Insufficient credits
500	Internal server error

Notes

Processing is asynchronous. The job is published to a message queue and processed by a worker.
Track the status of generated sceneries using the GET endpoint.
Credits are reserved at creation, consumed after successful processing, and refunded on failure.
Each request generates a correlationId for log tracing.
Maximum of 20 sceneries per request.

Example

curl -X POST "https://app.qamera.ai/api/external/sceneries/register-ideas" \
  -H "X-Api-Key: mk_live_abc123.secret456" \
  -H "Content-Type: application/json" \
  -d '{
    "preferences": "Minimalist Scandinavian living room with natural light and wooden furniture",
    "count": 5
  }'