Sets

A set is a named, ordered group of templates. If every listing in your shop reuses the same mockups, save them once as a set and render the whole group with a single set_id instead of repeating the same list of template IDs in every request.

Sets are created and managed in the app under Sets. They belong to the account that owns the API key, and they can mix built-in templates with your own custom ones.

Finding a set ID

Either grab it from the app, or list your sets over the API.

Where	How
In the app	Open Sets, hover the set you want, then choose Copy set ID from its `...` menu.
Over the API	Call GET /api/v1/sets and read the `id` field. Useful when you want to discover sets programmatically rather than hard-coding one.

List your sets

curl -X GET "https://www.mockupanda.com/api/v1/sets" \
-H "Authorization: Bearer YOUR_API_KEY"

{
  "sets": [
    {
      "id": "2bed1943-2880-4d40-b3d6-3296aa71e11e",
      "name": "Warm bedrooms",
      "template_ids": [
        "bedroom-poster-01",
        "wall-diptych-01",
        "living-room-03"
      ],
      "template_count": 3,
      "created_at": "2026-03-04T09:07:11.495Z",
      "updated_at": "2026-03-19T16:22:40.118Z"
    },
    {
      "id": "3e97ad00-caf7-4855-a1fb-7836282131c0",
      "name": "Q4 listings",
      "template_ids": [
        "frame-wall-02",
        "tshirt-flat-01"
      ],
      "template_count": 2,
      "created_at": "2026-02-11T09:06:12.613Z",
      "updated_at": "2026-02-11T09:06:12.613Z"
    }
  ],
  "count": 2
}

This endpoint is free and does not consume credits.

Response fields

Field	Type	Description
`id`	string	Set ID. Pass this as set_id when generating.
`name`	string	Name you gave the set in the app.
`template_ids`	string[]	Template IDs in saved order. This order determines the order of generated results.
`template_count`	integer	Number of IDs stored in the set. See templates that no longer exist for why this can exceed the number of rendered results.

Fetch one set

curl -X GET "https://www.mockupanda.com/api/v1/sets/2bed1943-2880-4d40-b3d6-3296aa71e11e" \
-H "Authorization: Bearer YOUR_API_KEY"

{
  "id": "2bed1943-2880-4d40-b3d6-3296aa71e11e",
  "name": "Warm bedrooms",
  "template_ids": [
    "bedroom-poster-01",
    "wall-diptych-01",
    "living-room-03"
  ],
  "template_count": 3,
  "created_at": "2026-03-04T09:07:11.495Z",
  "updated_at": "2026-03-19T16:22:40.118Z"
}

A set that does not exist, or belongs to another account, returns 404 with code SET_NOT_FOUND. For details about the templates themselves, pass the IDs to GET /api/v1/templates.

Generate from a set

Pass set_id to generate instead of listing template IDs. Every template in the set renders from the same artwork, in saved order.

curl -X POST "https://www.mockupanda.com/api/v1/mockups/generate" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "set_id": "2bed1943-2880-4d40-b3d6-3296aa71e11e",
  "artwork_url": "https://example.com/artwork.jpg",
  "response_format": "json"
}'

{
  "success": true,
  "results": [
    {
      "template_id": "bedroom-poster-01",
      "image": "iVBORw0KGgoAAAANS...",
      "format": "jpeg",
      "content_type": "image/jpeg",
      "size_bytes": 184270
    },
    {
      "template_id": "living-room-03",
      "image": "iVBORw0KGgoAAAANS...",
      "format": "jpeg",
      "content_type": "image/jpeg",
      "size_bytes": 242630
    }
  ],
  "count": 2,
  "total_size_bytes": 426900,
  "duration_ms": 1840,
  "set_id": "2bed1943-2880-4d40-b3d6-3296aa71e11e",
  "set_name": "Warm bedrooms",
  "skipped_template_ids": ["wall-diptych-01"]
}

The response is the standard batch payload plus set_id and set_name. Requests that do not use a set are unchanged.

Rules

Rule	Detail
Response format	A set holding more than one template is a batch, so `response_format="json"` is required.
Template limit	A set counts toward the same limit of `12` templates per request. A larger set returns `TOO_MANY_TEMPLATE_IDS`.
Combining	You can send `set_id` together with `template_id` or `template_ids`. The set renders first, extras are appended, and duplicates are collapsed.
Billing	You are charged per rendered mockup, so a set of 3 costs the same as 3 template IDs.
Empty sets	A set with no templates returns `SET_EMPTY`.

Templates that no longer exist

A set stores template IDs, so it can outlive a template you later delete. Rather than failing the whole request, generation skips IDs that no longer resolve and lists them in skipped_template_ids. You are only charged for templates that actually render.

This leniency applies only to IDs stored in the set. An unknown ID you pass explicitly in template_id or template_ids is still a 404 TEMPLATE_NOT_FOUND, so typos surface immediately.

If none of a set's templates resolve, the request returns 404 with code SET_TEMPLATES_UNAVAILABLE.

Errors

Code	Status	Meaning
`SET_NOT_FOUND`	404	No set with that ID on this account.
`SET_EMPTY`	400	The set exists but contains no templates.
`SET_TEMPLATES_UNAVAILABLE`	404	Every template the set references has been deleted.
`TOO_MANY_TEMPLATE_IDS`	400	The set exceeds the `12` template limit for one request.
`BATCH_REQUIRES_JSON_RESPONSE`	400	The set holds more than one template but `response_format` was not `"json"`.