Async Rendering

Sync vs Async

By default, POST /api/v1/renders and POST /api/v1/psd/upload are synchronous: the request blocks until the work is done and returns the result inline with a 200OK. That is the simplest path and works well for a single render in a request/response cycle.

For long-running work, large batches, or any flow where you do not want to hold a connection open, run the same endpoints asynchronously. Add "is_async": true to the request body and you get an immediate 202Accepted with a render_uuid you can track to completion.

The is_async flag

1{
2  "is_async": true,
3  "mockup_uuid": "c315f78f-d2c7-4541-b240-a9372842de94",
4  "smart_objects": [
5    {
6      "uuid": "128394ee-6758-4f2f-aa36-e2b19b152bd9",
7      "asset": {
8        "url": "https://your-domain.com/design.png",
9        "fit": "cover"
10      }
11    }
12  ],
13  "export_options": {
14    "image_format": "webp",
15    "image_size": 1920,
16    "quality": 90
17  }
18}

The 202 lifecycle

An async submission returns 202Accepted right away. The body echoes back enough to start tracking the job:

1{
2  "render_uuid": "9d4e2b51-0c7a-4f8e-bb1c-2a6f9e3d8c10",
3  "kind": "render",
4  "status": "queued",
5  "status_url": "/api/v1/jobs/9d4e2b51-0c7a-4f8e-bb1c-2a6f9e3d8c10"
6}

202 Response Fields

A PSD upload submitted with is_async returns the same shape, with kind set to upload:

1{
2  "render_uuid": "1f0a8c23-7b44-4e90-9c2d-55ab1e7f0d33",
3  "kind": "upload",
4  "status": "queued",
5  "status_url": "/api/v1/jobs/1f0a8c23-7b44-4e90-9c2d-55ab1e7f0d33"
6}

Submit, then poll

The async pattern is two steps: submit to get a render_uuid, then poll GET /api/v1/jobs/{render_uuid} until the status is succeeded, failed, or cancelled. Use a gentle backoff so you are not hammering the endpoint.

A job moves through a fixed set of states. The full state machine is documented in the Jobs reference; the states you will observe are:

• queued: accepted and waiting to start. This is the initial state returned with the 202Accepted.
• processing: the job is actively running.
• succeeded: terminal. The result is ready; render and video jobs expose a result_url, and upload jobs expose a mockup_uuid.
• failed: terminal. The job did not complete; error describes why.
• cancelled: terminal. The job was cancelled before it finished.

queued and processing are non-terminal: keep polling. succeeded, failed, and cancelled are terminal: stop polling.

1const BASE_URL = "https://api.sudomock.com/api/v1";
2const headers = {
3  "Content-Type": "application/json",
4  "x-api-key": "sm_your_api_key",
5};
6
7// 1) Submit asynchronously -> 202 Accepted
8const submit = await fetch(`${BASE_URL}/renders`, {
9  method: "POST",
10  headers,
11  body: JSON.stringify({
12    is_async: true,
13    mockup_uuid: "c315f78f-d2c7-4541-b240-a9372842de94",
14    smart_objects: [{
15      uuid: "128394ee-6758-4f2f-aa36-e2b19b152bd9",
16      asset: { url: "https://your-domain.com/design.png", fit: "cover" },
17    }],
18  }),
19});
20
21const { render_uuid } = await submit.json();
22
23// 2) Poll the job until it is finished
24async function poll(uuid, { intervalMs = 1500, maxMs = 120000 } = {}) {
25  const deadline = Date.now() + maxMs;
26  let delay = intervalMs;
27  while (Date.now() < deadline) {
28    const res = await fetch(`${BASE_URL}/jobs/${uuid}`, { headers });
29    const job = await res.json();
30    if (job.status === "succeeded") return job.result_url;
31    if (job.status === "failed" || job.status === "cancelled") {
32      throw new Error(`Job ${job.status}: ${job.error ?? "unknown"}`);
33    }
34    await new Promise(r => setTimeout(r, delay));
35    delay = Math.min(delay * 1.5, 8000); // gentle backoff, cap at 8s
36  }
37  throw new Error("Timed out waiting for the job to finish");
38}
39
40const resultUrl = await poll(render_uuid);
41console.log("Done:", resultUrl);

SDKs cover async