Skip to main content
Uploading registers a Photoshop file as a reusable template. You do it once per template, and every render afterwards refers to it by UUID. The response is the only discovery step there is: it lists every slot the file holds, with the handles you send back at render time.
The file is fetched server side, so the URL has to answer without a session cookie. A signed URL that expires works.

​
Register the template

1

Host the PSD at a URL the API can fetch.

Object storage, a CDN or a signed link all work. The fetch timeout is in the table below.
2

Send that URL to the upload endpoint.

One POST with psd_file_url and an optional psd_name. Create a mockup from a PSD carries that request in eight languages, with the whole response body. Every call carries your API key. See Authentication.
3

Read the template UUID back.

4

Read the slot arrays beside it.

smart_objects, text_layers and group_layers each list what the designer built, one entry and one UUID per addressable layer.
5

Store those UUIDs against the names your own product uses.

A render addresses a slot by UUID, not by layer name, so the mapping is yours to keep.

​
What comes back

One response carries every UUID a render needs. Author artwork at a design area’s size. The render scales it into position for you, so neither number belongs in a render body. quad, the area’s four corner points as placed in the file, rotation and perspective included, arrives on Scale and Enterprise plans and is null on other plans. position and quad are measured on the canvas for a top-level area, and inside the parent smart object’s document for a nested one, as Smart objects explains.

​
Uploading in the background

A large PSD takes a while to read. Send "is_async": true and the call answers at once with a job rather than a template: a job_id, the job kind, its status and a status_url. Retrieve a single job returns that job once it finishes, carrying the new mockup_uuid. A call without is_async waits up to 100 seconds. When the upload needs longer, the call answers 503 with the error code UPLOAD_PROCESSING and the upload carries on. Its details hold the job_id, the status_url and retry_after_seconds: follow that job the same way until it finishes. The same request sent again while the job runs picks up that job instead of uploading the file a second time. Register a webhook endpoint and the upload.succeeded event arrives instead, with no polling. Send an Idempotency-Key header either way, so a retried upload does not register the same template twice.

​
Practical notes

Upload once per template, not once per render. Re-uploading the same file produces a second template with its own UUIDs and spends the time again. Uploads that contain hidden smart objects come back flagged, because a hidden smart object is not exposed as a slot. Make it visible in Photoshop and upload again. See Hidden layers. Upload failures return error_code, message and detail. A file that cannot be fetched, a file that is not a PSD, and a file with no addressable layer each have their own code, listed in Errors.

​
Learn more

Smart objects

Read what each field on a design area describes.

Text layers

Change wording, font, size and colour on every render.

​
Next steps

Render a PSD

Take those UUIDs and produce a finished image.

Create a mockup from a PSD

See the request and the whole response body.