Packshots

List, generate, and manage packshot images for your products.

GET /api/external/packshots

Returns a list of generated packshot 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`

Response

{
  "packshots": [
    {
      "id": "ps_abc123",
      "name": "White T-Shirt Packshot",
      "thumbnail": "https://cdn.example.com/packshots/thumb_abc123.jpg",
      "status": "DONE",
      "voting": "APPROVED",
      "createdAt": "2026-03-20T15: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 statusFilter=approved to retrieve only packshots that have been approved.

Example

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

POST /api/external/packshots/register-ideas

Registers a new packshot 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 generate packshots for
config.preset.id	string	No	ID of the preset to apply
config.scenery.id	string	No	ID of the scenery/background to use
config.model.id	string	No	ID of the AI model to use
count	number	No	Number of packshots to generate (default: 10, max: 50)

Response

{
  "createdRecordIds": ["ps_001", "ps_002", "ps_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 packshots 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 50 packshots per request.

Example

curl -X POST "https://qamera.ai/api/external/packshots/register-ideas" \
  -H "X-Api-Key: mk_live_abc123.secret456" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "product": { "id": "prod_abc123" },
      "preset": { "id": "preset_xyz" },
      "scenery": { "id": "scenery_001" }
    },
    "count": 10
  }'

POST /api/external/packshots/update-packshot

Approve, reject, or archive a generated packshot.

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
recordId	string	Yes	ID of the packshot to update
Voting	string	No	Set to `APPROVED` or `REJECTED`. Rejecting clears the vote and leaves the packshot in the list.
status	string	No	Set to `ARCHIVE` to archive the packshot

Response

{
  "success": true
}

Error Responses

Code	Meaning
400	Invalid request body, missing recordId, or a field this endpoint does not accept
401	Missing or invalid API key
404	Packshot not found
500	Internal server error

Notes

Setting Voting to APPROVED marks the packshot as approved.
Setting Voting to REJECTED clears the vote and returns the packshot to the un-rated state. It stays in the list — archiving is status: ARCHIVE and nothing else.
Setting status to ARCHIVE archives the packshot regardless of voting status.
The three fields above are the whole request body. Any other field is refused with 400 naming it, so a value this endpoint does not store is never accepted and discarded.
No credits are consumed by this endpoint.

Example

curl -X POST "https://qamera.ai/api/external/packshots/update-packshot" \
  -H "X-Api-Key: mk_live_abc123.secret456" \
  -H "Content-Type: application/json" \
  -d '{
    "recordId": "ps_abc123",
    "Voting": "APPROVED"
  }'