> ## Documentation Index
> Fetch the complete documentation index at: https://sudomock.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> The base URL is https://api.sudomock.com.
> Authenticate every request with the x-api-key header. Keys begin with sm_.
> A render returns the finished image at data.print_files[0].export_path. A request sent with is_async true returns a job_id to poll at GET /api/v1/jobs/{job_id}.
> Prefer the official SDKs over hand-written HTTP calls: npm install sudomock for Node, pip install sudomock for Python.

# Photo mockups

> How a product photo becomes a mockup you render onto.

A photo mockup turns one product photograph into a template you render onto.
You prepare it once, then send any artwork at it for as long as you keep it, the
same way a PSD template works, without owning a layered file.

<Info>
  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.
</Info>

## From a photograph to a finished image

<Steps>
  <Step title="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](/docs/api-reference/photo-mockups/create-a-mockup-from-a-product-photo).
  </Step>

  <Step title="(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.
  </Step>

  <Step title="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](/docs/photo-mockups/print-areas).
  </Step>

  <Step title="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](/docs/photo-mockups/render-artwork).
  </Step>

  <Step title="Swap the artwork and send the render call again." />
</Steps>

## Run it in the background

Both calls accept `is_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.

| Job kind              | A finished job carries              |
| --------------------- | ----------------------------------- |
| `photo_mockup_create` | The new mockup in `mockup_uuid`.    |
| `photo_mockup_render` | The finished image in `result_url`. |

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](/docs/api-reference/jobs/retrieve-a-single-job).

## Which events fire

Asynchronous work reports through five events. Subscribe on
[Webhooks](/docs/webhooks/overview), and treat `job_id` plus the event name as the
idempotency key so a repeat delivery is a safe no operation.

| Event                           | Meaning                                                                                         |
| ------------------------------- | ----------------------------------------------------------------------------------------------- |
| `photo_mockup.ready`            | The mockup was created and its targets are ready to render.                                     |
| `photo_mockup.rejected`         | The photograph could not be used. The payload carries a `reason`, and the credits are returned. |
| `photo_mockup.failed`           | The create job failed unexpectedly. The credits are returned.                                   |
| `photo_mockup_render.succeeded` | An asynchronous render finished and `result_url` is ready.                                      |
| `photo_mockup_render.failed`    | An asynchronous render failed.                                                                  |

## 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](https://sudomock.com/pricing).

On a funded account renders come back unwatermarked at the width you asked for.
While the account is on trial credits, renders carry a watermark and a reduced
output width.

## Learn more

<CardGroup cols={2}>
  <Card title="Print areas and surfaces" icon="crop" href="/docs/photo-mockups/print-areas">
    Where artwork can land, and how to move it.
  </Card>

  <Card title="Render artwork" icon="image" href="/docs/photo-mockups/render-artwork">
    Placement, adjustments and export options, field by field.
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Create endpoint" icon="code" href="/docs/api-reference/photo-mockups/create-a-mockup-from-a-product-photo">
    Send a photograph and read the mockup that comes back.
  </Card>

  <Card title="Render endpoint" icon="play" href="/docs/api-reference/photo-mockups/render-a-photo-mockup">
    Run a render from the page and read every field it accepts.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/docs/webhooks/overview">
    Subscribe once and stop polling for finished jobs.
  </Card>

  <Card title="Legacy paths" icon="history" href="/docs/changes/legacy-paths">
    Map the older 2D paths onto the ones above.
  </Card>
</CardGroup>