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:
| Field | Required | What it is |
|---|---|---|
upload | Yes | The id from POST /v1/uploads |
op | Yes | wheels, color, spoiler, or exhaust, switched on in Storefront → Pick what you sell |
ref | Yes | Public https address of the product image. Any host; your allowed image domains don't apply to the API |
label | No | Product name, up to 120 characters. Shown in your dashboard; never sent to the AI |
finish | No | Only with op: "color": gloss, matte, satin, pearl, metallic, carbon, or chameleon |
webhook_url | No | Public 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, codeidempotency_key_reused. - Same key while the first request is still running:
409, codeidempotency_key_in_use. Retry after a second. - A request that was refused (for example
422or429) 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
}
| Field | What it is |
|---|---|
id | Starts with rnd_ |
status | queued, processing, succeeded, or failed |
phase | While queued or processing: preparing, rendering, checking, or rerendering. null once finished |
estimated_seconds_remaining | A best guess for a progress indicator. It can go up when a render is redone. null once finished |
upload, op, ref, label, finish | What you sent |
output | When succeeded: { "url": "..." }, a permanent public address of the finished image |
failure | When failed: { "code", "message" }, see below |
refunded | true once the render was given back to your balance |
created_at, completed_at | ISO 8601 timestamps in UTC |
Statuses and phases#
| Status | Phase | What's happening |
|---|---|---|
queued | preparing | Accepted, about to start |
processing | preparing | Reading the car photo and the product |
processing | rendering | The image is being made |
processing | checking | Wheel renders only: the result is checked against your wheel |
processing | rerendering | The check failed, so the render is being redone at no extra cost |
succeeded | output.url is ready | |
failed | See 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.code | What happened | What to do |
|---|---|---|
wheels_not_visible | A wheel render on a photo with no wheel face visible, for example straight from the front or back | Ask the customer for a side or three-quarter photo |
render_failed | Anything else, for example a product image that couldn't be loaded | Check 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.