Photo Shoots

List generated photo shoot images and register new photo shoot jobs.

GET /api/external/image-picker

Returns a list of generated photo shoot images.

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`
productId	string	No	Filter images by a specific product ID

Response

{
  "images": [
    {
      "id": "img_abc123",
      "name": "Fashion Shoot - White T-Shirt",
      "thumbnail": "https://cdn.example.com/images/thumb_abc123.jpg",
      "status": "DONE",
      "voting": "APPROVED",
      "createdAt": "2026-03-20T16: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.
Use productId to narrow results to a specific product.

Example

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

POST /api/external/image-picker/register-ideas

Registers a new photo shoot 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
config.product.id	string	Yes	ID of the product to photograph
config.model.id	string	No	ID of the AI model (mannequin) to use
config.scenery.id	string	No	ID of the scenery/background
config.preset.id	string	No	ID of the preset to apply
config.industry	string	No	Industry category (e.g., `fashion`)
config.suggestions	string	No	Free-text creative direction or suggestions
count	number	No	Number of images to generate (default: 10, max: 20)

Response

{
  "createdRecordIds": ["img_001", "img_002", "img_003"],
  "batchId": "batch_abc123",
  "orderId": "order_xyz789",
  "reservationId": "res_def456",
  "creditsReserved": 30
}

Error Responses

Code	Meaning
400	Invalid request body or missing required fields
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 images 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 images per request.

Example

curl -X POST "https://app.qamera.ai/api/external/image-picker/register-ideas" \
  -H "X-Api-Key: mk_live_abc123.secret456" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "product": { "id": "prod_abc123" },
      "model": { "id": "model_xyz" },
      "scenery": { "id": "scenery_001" },
      "industry": "fashion",
      "suggestions": "Outdoor urban setting, natural lighting"
    },
    "count": 10
  }'