Presets

List, create, and update photography presets with guidelines and reference images.

GET /api/external/presets

Returns a list of available presets. Presets are shared globally and define photography guidelines for generation jobs.

Headers

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

Query Parameters

Field	Type	Required	Description
maxRecords	number	No	Maximum number of presets to return (default: 20)

Response

{
  "presets": [
    {
      "id": "preset_abc123",
      "name": "E-commerce Standard",
      "guidelines": "Clean white background, centered product, soft shadows",
      "quantityGuidelines": "3-5 angles per product",
      "qualityGuidelines": "High resolution, consistent lighting, no reflections",
      "createdAt": "2026-03-15T10: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.
Returns both system presets and user-created presets.

Example

curl -X GET "https://app.qamera.ai/api/external/presets?maxRecords=50" \
  -H "X-Api-Key: mk_live_abc123.secret456"

POST /api/external/presets

Creates a new user preset with guidelines and optional reference images.

Headers

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

Request Body

Field	Type	Required	Description
name	string	Yes	Name of the preset
quantityGuidelines	string	Yes	Guidelines for the number and variety of images to generate
qualityGuidelines	string	Yes	Guidelines for image quality, lighting, and style
cover	file	No	Cover image for the preset
gallery	file[]	No	Gallery of reference images

Response

{
  "success": true,
  "presetId": "preset_new123"
}

Error Responses

Code	Meaning
400	Missing required fields (name, quantityGuidelines, or qualityGuidelines)
401	Missing or invalid API key
500	Internal server error

Notes

The created preset is of type USER, status published, and visibility private.
The preset is linked to the account associated with the API key.
No credits are consumed by this endpoint.

Example

curl -X POST "https://app.qamera.ai/api/external/presets" \
  -H "X-Api-Key: mk_live_abc123.secret456" \
  -F "name=My Custom Preset" \
  -F "quantityGuidelines=Generate 5 variations per product" \
  -F "qualityGuidelines=Bright studio lighting, minimal shadows, 4K resolution" \
  -F "cover=@/path/to/cover.jpg" \
  -F "gallery=@/path/to/ref1.jpg" \
  -F "gallery=@/path/to/ref2.jpg"

PUT /api/external/presets

Updates an existing user preset. You can modify guidelines, replace the cover image, and manage gallery images.

Headers

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

Request Body

Field	Type	Required	Description
presetId	string	Yes	ID of the preset to update
name	string	No	Updated preset name
quantityGuidelines	string	No	Updated quantity guidelines
qualityGuidelines	string	No	Updated quality guidelines
cover	file	No	New cover image (replaces existing)
gallery	file[]	No	New gallery images to add
existingGalleryIds	string	No	JSON string array of existing gallery image IDs to keep (e.g., `["id1","id2"]`)
removeCover	string	No	Set to `"true"` to remove the current cover image

Response

{
  "success": true
}

Error Responses

Code	Meaning
400	Missing presetId or invalid request
401	Missing or invalid API key
403	You do not own this preset
500	Internal server error

Notes

You can only update presets that belong to your account. Attempting to update another user's preset returns a 403 error.
The gallery supports a maximum of 6 images.
Use existingGalleryIds to specify which current gallery images to retain. Images not listed are removed.
Set removeCover to "true" to delete the cover image without uploading a replacement.
No credits are consumed by this endpoint.

Example

curl -X PUT "https://app.qamera.ai/api/external/presets" \
  -H "X-Api-Key: mk_live_abc123.secret456" \
  -F "presetId=preset_abc123" \
  -F "name=Updated Preset Name" \
  -F "qualityGuidelines=Soft natural lighting, warm tones, lifestyle feel" \
  -F "gallery=@/path/to/new_ref.jpg" \
  -F 'existingGalleryIds=["gallery_img_001","gallery_img_002"]' \
  -F "removeCover=false"