API quickstart

Render a customer's car with one of your products from your own site or configurator. Three calls: upload the car photo, start the render, fetch the result.

The API does what a try-on link does, without your VizTunr storefront: you send the customer's car photo and the same op, ref, label, and finish a link would carry, and you get back the finished image to show in your own design.

Before you start#

  • Your shop is on the Growth or Pro plan.
  • You have a secret key from Settings → Developer API. See API keys and rate limits.
  • The try-on type you want is switched on in Storefront → Pick what you sell.

Every API render is a real render from your balance. There is no test mode.

Base URL:

https://app.viztunr.com/api/v1

1. Upload the car photo#

curl https://app.viztunr.com/api/v1/uploads \
  -H "Authorization: Bearer $VIZTUNR_KEY" \
  -F file=@customer-car.jpg
{
  "id": "upl_269c9fcbc7154983b2124958d8e4c58e",
  "url": "https://api.viztunr.com/storage/v1/object/public/shop-uploads/.../269c9fcb.jpg",
  "content_type": "image/jpeg",
  "size_bytes": 719808,
  "created_at": "2026-11-14T07:35:36Z"
}

2. Start the render#

Pass the upload's id and the product, exactly as a try-on link would:

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": "wheels",
    "ref": "https://yourshop.com/images/forged-r1.jpg",
    "label": "Forged R1 20\""
  }'

The API answers at once with 202 Accepted and the render in queued state. The render is charged now; if it fails later, it is given back.

{
  "id": "rnd_b13cf6c43e5a49aabc5b2be8ddbffd60",
  "status": "queued",
  "phase": "preparing",
  "estimated_seconds_remaining": 60,
  "upload": "upl_269c9fcbc7154983b2124958d8e4c58e",
  "op": "wheels",
  "ref": "https://yourshop.com/images/forged-r1.jpg",
  "label": "Forged R1 20\"",
  "finish": null,
  "output": null,
  "failure": null,
  "refunded": false,
  "created_at": "2026-11-14T07:36:01Z",
  "completed_at": null
}

3. Get the result#

A render takes about a minute, sometimes up to two. Ask for it every few seconds until status is succeeded or failed:

curl https://app.viztunr.com/api/v1/renders/rnd_b13cf6c43e5a49aabc5b2be8ddbffd60 \
  -H "Authorization: Bearer $VIZTUNR_KEY"
{
  "id": "rnd_b13cf6c43e5a49aabc5b2be8ddbffd60",
  "status": "succeeded",
  "phase": null,
  "estimated_seconds_remaining": null,
  "output": { "url": "https://api.viztunr.com/storage/v1/object/public/renders/.../result.png" },
  "failure": null,
  "refunded": false,
  "completed_at": "2026-11-14T07:36:50Z"
}

Show output.url to your customer. While you wait, phase and estimated_seconds_remaining are there for a progress indicator.

Rather not poll? Add a webhook_url when you start the render and VizTunr tells your server when it's done. See Webhooks.

Reference#

EndpointWhat it does
POST /v1/uploadsUpload a car photo
DELETE /v1/uploads/:idDelete a car photo
POST /v1/rendersStart a render
GET /v1/renders/:idGet a render
DELETE /v1/renders/:idDelete a render
GET /v1/balanceRenders left

Errors always come with a code and a fix: see Errors. Renders made through the API show up in your shop's Leads, under All visitors, as one row per key tagged API.