Templates

A template is a named set of saved instructions you reuse across jobs. Each instruction inside a template is a preset: one saved scene and styling configuration, identified by preset_code.

Running a template means turning each of its presets into one instruction, so a template holding six presets produces six output images from the same input. Instead of rebuilding the same configuration every time, save it once and reference it by code.

Templates are called preset categories in the API. Their endpoints live under /preset/categories, and the presets they hold live under /preset.

Presets

A preset holds the actual instructions. Presets are typed: each one targets a specific kind of job, and the platform validates that a preset's instructions match the job you use it with.

Type	Used with
`flat_2_model`	Flat Lay on Model jobs
`model_swap`	Model Swap jobs
`create_packshot`	Packshot creation jobs
`identity_creation`	Identity generation jobs

A template normally holds presets of a single type, matching the job you intend to run it with.

Preset fields

Field	Description
`preset_code`	Stable identifier you should store in your integration
`name`	Human-readable label
`description`	Optional free-form description
`type`	One of the preset types above
`instruction_data`	JSON object holding the scene and styling instructions
`visibility`	`private`, `shared`, or `system`
`categories`	Templates the preset belongs to
`groups`	Names of the groups the preset is shared with
`created_by`	Email of the creator, `null` for system presets
`created_at`	Creation datetime (UTC, ISO 8601)
`updated_at`	Last update datetime (UTC, ISO 8601)

Only name, description, and instruction_data can be updated after creation. A preset's type is fixed, and template membership is changed through the assign and unassign endpoints rather than through an update.

Template fields

Field	Description
`id`	Stable identifier you should store in your integration
`name`	Display name, unique per user and compared case-insensitively
`description`	Optional free-form description
`thumbnail_url`	Optional cover image
`visibility`	`private`, `shared`, or `system`
`preset_count`	Number of presets currently in the template
`preset_types`	Distinct preset types present, usually exactly one
`preset_previews`	Up to 8 preset previews for building a cover, newest first
`groups`	Names of the groups the template is shared with
`created_by`	Email of the creator, `null` for system templates
`created_at`	Creation datetime (UTC, ISO 8601)

Read preset_count, preset_types, and preset_previews from the list or get endpoints. Responses that return a template as the result of another action, such as creating or duplicating one, do not include them.

Fetching a single template adds the presets it holds, plus a few fields describing your own access:

Field	Description
`viewer_role`	How you reach the template: `owner`, `team`, or `system`
`can_edit`	Whether you can rename or delete the template
`can_manage_presets`	Whether you can assign and unassign presets
`presets`	The presets you are allowed to read, newest first

Pass include_presets=false when you only need the template metadata.

preset_count is the total number of presets in the template, while presets only contains the ones you are allowed to read. On a shared template these two can legitimately disagree.

Building a template

There are three ways to build a template.

Manually

Create an empty template with a name, then create presets and assign them to it. You can also pass category_ids when creating a preset to file it into one or more templates in a single call.

Template names must be unique per user. Reusing a name you already have returns 409 Conflict.

From a set of reference images

If you have between 2 and 6 images that share a common visual style, the platform can extract a complete template in one call. The result is:

a new template named after your input, or auto-named from the type and the current date
one preset per image, in the same order as the file_ids you sent
consistent wording across presets for traits that look identical in every image, and per-image wording for traits that visibly differ

The response also returns shared_traits, the fields the platform treated as common to the whole set. This is the fastest way to bootstrap a coherent template from existing creative.

Batch extraction is only supported for the flat_2_model and create_packshot types. Any other type returns 400, along with the list of supported types.

By duplicating an existing template

Duplicating makes a deep copy: a new template you own, plus a fresh copy of every preset inside it with a new preset_code. You only need read access to the source, so this is how you fork a system template or a teammate's template and then edit it freely.

Set share_with_groups to true to carry the source presets' group sharing over to the copies. Duplication is capped at 50 presets and consumes no credits.

Creating presets

Besides writing instruction_data by hand, the platform can generate it for you.

From a reference image

Upload an image and the platform extracts a matching instruction_data payload. The response also includes a suggested name and description so you can save the preset in one step.

This is useful when you have a target look or scene in mind and want to recreate it consistently across future jobs.

From a text description

Provide a natural-language description of the scene or styling you want, and the platform generates a matching instruction_data payload.

Both extractions return a payload without saving anything. Send the resulting instruction_data to the create endpoint to persist it as a preset. Extracting a whole template from images is different: it saves the template and its presets for you.

Extracting from an image or from text consumes credits. Extracting a whole template from images consumes credits per image. See Credits for details.

Managing template contents

A single preset can belong to multiple templates, and you can assign or unassign at any time. Both operations require write access to the template and to the preset.

Deleting a template also deletes the presets that depend on it: the ones you own whose only remaining template is this one. Presets that also belong to another template are kept, as are presets owned by other users. The response reports how many presets were removed alongside the template.

Templates and presets can be:

private: only you can see them
shared: visible to members of your groups
system: platform-provided, available to all users

Sharing is group-based, and it applies to the presets a template holds rather than to the template itself. Sharing a template grants the target group access to each preset inside it, which is what makes the template visible to that group.

Sharing a template only shares the presets that exist at that moment. Presets added afterwards are not shared automatically, so share again after adding to a template your team already uses.

Two consequences worth planning for:

Only the owner of a preset can share it. Presets owned by someone else are skipped and returned in skipped_preset_codes.
Reaching a template does not grant access to everything inside it. A shared template can hold presets a teammate cannot read.

System templates and system presets are read-only. Attempting to modify, delete, or share one returns 403.

See Groups for how groups themselves work.

Browsing your library

The template list returns every template you can reach in one response. Narrow it with ownership (mine, shared, or default), type, and search, and order it with sort_by and order.

The preset list is paginated and supports the same filters, plus category_id to scope to a single template and created_by to scope to a teammate. search matches both preset names and the names of the templates they belong to, so searching for a template name returns its contents.

Pass group_by=category to receive presets already bucketed by template, with an Uncategorized bucket for presets that belong to none.

When you group by template, pagination applies to the templates rather than to the individual presets.

Referencing a template in a job

Job instructions carry preset_name, preset_code, and category_names as metadata. These fields record where an instruction came from and are surfaced when you read the job back. They do not affect processing: the instruction payload you submit is what gets rendered.

Job results also report the templates a preset currently belongs to, so you can navigate from an output image back to the template that produced it. Unlike category_names, which records the names as they were when the job was submitted, this reflects the template as it stands today.

See Flat Lay on Model and Create a packshot for the instruction payloads.

Good to know

Updating a template replaces description and thumbnail_url with whatever you send. Omitting them clears the stored values, so always send the fields you want to keep.
Deleting a preset or a template is not reversible through the API.
Presets can be deleted in bulk. The response reports how many were removed and lists the codes it could not delete, instead of failing the whole request.
Group names in the share endpoints are matched case-insensitively.

Account limits

Non-enterprise accounts have a maximum number of presets. If you reach the cap, the create endpoint returns 429. Delete unused presets or contact us to raise the limit.