Creating a mockup and rendering onto it are separate calls. Setup happens once
per photograph and rendering happens once per design, so the cost of a
catalogue follows the number of designs rather than the number of photographs.
From a photograph to a finished image
1
Send the photograph to the create endpoint.
POST /api/v1/photo-mockups takes exactly one image source, source_url or
source_base64, and an optional name. The call is synchronous by default
and answers with the finished mockup, so there is nothing to poll before you
render. The whole request is on
Create a mockup from a product photo.2
(Optional) Send your own print areas with the same call.
The create body also accepts a
print_areas list of four point areas in
source photo pixels, and they are used as given.3
Keep the mockup id and one target id.
The response carries
data.mockup_id for the render path and two lists of
render targets. data.quads holds bounded zones addressed by
print_area_id, and data.surfaces holds whole products addressed by
surface_uuid. A product keeps its surface entry after zones are drawn on
it, so a chest logo and an all over print are two targets on one
photograph. Both lists are read field by field in
Print areas and surfaces.4
Render the artwork onto the target.
POST /api/v1/photo-mockups/{mockup_id}/render takes one entry per target,
each naming a target id and its artwork, plus export_options for the file
you want back. The finished image arrives at
data.print_files[0].export_path. Placement, adjustments and export
options are covered in Render artwork.5
Swap the artwork and send the render call again.
Run it in the background
Both calls acceptis_async: true. You get a 202 carrying a job_id and a
status_url instead of a result, which is what you want when you create or
render in batches and do not want to hold connections open.
Poll
status_url until the job reports succeeded, or subscribe to a webhook
and skip polling. The full poll contract is in the
job status reference.
Which events fire
Asynchronous work reports through five events. Subscribe on Webhooks, and treatjob_id plus the event name as the
idempotency key so a repeat delivery is a safe no operation.
What a mockup costs you
Creating a mockup is charged once and each render is charged per image. A rejected or failed create returns its credits automatically. The current credit weights are on pricing. On a funded account renders come back unwatermarked at the size you asked for. While the account is on trial credits, API renders carry a watermark, and animage_size above the trial cap answers with
OUTPUT_RESOLUTION_LIMIT rather than a quietly smaller image.
Learn more
Print areas and surfaces
Where artwork can land, and how to move it.
Render artwork
Placement, adjustments and export options, field by field.
Next steps
Create endpoint
Send a photograph and read the mockup that comes back.
Render endpoint
Run a render from the page and read every field it accepts.
Webhooks
Subscribe once and stop polling for finished jobs.
Legacy paths
Map the older 2D paths onto the ones above.