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 four corner points of an area with a perspective transform, arrives on Scale plans and is null on lower ones. 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.