Renders

A render is one customer's car with one of your products on it. You start it, it runs for about a minute, and you get a finished image or a refund.

Start a render#

POST /v1/renders, with a JSON body.

curl https://app.viztunr.com/api/v1/renders \
  -H "Authorization: Bearer $VIZTUNR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a90-3d7e-4f0b-9a51-2c8e4b7d1f03" \
  -d '{
    "upload": "upl_269c9fcbc7154983b2124958d8e4c58e",
    "op": "color",
    "ref": "https://yourshop.com/films/ruby-red.jpg",
    "label": "Ruby Red",
    "finish": "gloss",
    "webhook_url": "https://yourshop.com/viztunr/webhook"
  }'

The parameters are the ones a try-on link carries, plus the photo and an optional webhook:

FieldRequiredWhat it is
uploadYesThe id from POST /v1/uploads
opYeswheels, color, spoiler, or exhaust, switched on in Storefront → Pick what you sell
refYesPublic https address of the product image. Any host; your allowed image domains don't apply to the API
labelNoProduct name, up to 120 characters. Shown in your dashboard; never sent to the AI
finishNoOnly with op: "color": gloss, matte, satin, pearl, metallic, carbon, or chameleon
webhook_urlNoPublic https address VizTunr calls once when the render ends. See Webhooks

The API answers at once with 202 Accepted, the render object, and a Location header pointing at the render. The render is charged from your balance at this moment, exactly like a storefront try-on.

ref is only checked to be an https address. If the image can't be loaded or read, the render fails and is given back.

Idempotency#

Networks drop responses. If you retry a POST /v1/renders without knowing whether the first one arrived, you can start, and pay for, the same render twice. Send an Idempotency-Key header (any unique string up to 255 characters; a UUID is ideal) and retry with the same key:

  • Same key, same body, within 24 hours: you get the first response back with the header Idempotent-Replayed: true, and nothing is charged again.
  • Same key, different body: 409, code idempotency_key_reused.
  • Same key while the first request is still running: 409, code idempotency_key_in_use. Retry after a second.
  • A request that was refused (for example 422 or 429) doesn't use up its key; fix it and retry with the same key.

The header is optional, but every render request you send from production code should have one.

Get a render#

GET /v1/renders/:id

curl https://app.viztunr.com/api/v1/renders/rnd_b13cf6c43e5a49aabc5b2be8ddbffd60 \
  -H "Authorization: Bearer $VIZTUNR_KEY"

Without a webhook, call this every 3 seconds or so until the render is finished. Only renders created through the API, by any of your shop's keys, can be read here.

The render object#

{
  "id": "rnd_b13cf6c43e5a49aabc5b2be8ddbffd60",
  "status": "processing",
  "phase": "rendering",
  "estimated_seconds_remaining": 46,
  "upload": "upl_269c9fcbc7154983b2124958d8e4c58e",
  "op": "color",
  "ref": "https://yourshop.com/films/ruby-red.jpg",
  "label": "Ruby Red",
  "finish": "gloss",
  "output": null,
  "failure": null,
  "refunded": false,
  "created_at": "2026-11-14T07:36:01Z",
  "completed_at": null
}
FieldWhat it is
idStarts with rnd_
statusqueued, processing, succeeded, or failed
phaseWhile queued or processing: preparing, rendering, checking, or rerendering. null once finished
estimated_seconds_remainingA best guess for a progress indicator. It can go up when a render is redone. null once finished
upload, op, ref, label, finishWhat you sent
outputWhen succeeded: { "url": "..." }, a permanent public address of the finished image
failureWhen failed: { "code", "message" }, see below
refundedtrue once the render was given back to your balance
created_at, completed_atISO 8601 timestamps in UTC

Statuses and phases#

StatusPhaseWhat's happening
queuedpreparingAccepted, about to start
processingpreparingReading the car photo and the product
processingrenderingThe image is being made
processingcheckingWheel renders only: the result is checked against your wheel
processingrerenderingThe check failed, so the render is being redone at no extra cost
succeededoutput.url is ready
failedSee failure; the render was given back

Most renders finish in 50 to 60 seconds. A redone wheel render takes about 100 to 110 seconds.

Failures#

A failed render is always given back to your balance, so refunded is true.

failure.codeWhat happenedWhat to do
wheels_not_visibleA wheel render on a photo with no wheel face visible, for example straight from the front or backAsk the customer for a side or three-quarter photo
render_failedAnything else, for example a product image that couldn't be loadedCheck that ref opens in a browser, then try again

Delete a render#

DELETE /v1/renders/:id removes the render and its result image. It never gives the render back. The car photo is a separate upload.

curl -X DELETE https://app.viztunr.com/api/v1/renders/rnd_b13cf6c43e5a49aabc5b2be8ddbffd60 \
  -H "Authorization: Bearer $VIZTUNR_KEY"

Answers 204 No Content, or 404 with code not_found. Images can stay reachable from caches for a short while after they're deleted.