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#
| Endpoint | What it does |
|---|---|
POST /v1/uploads | Upload a car photo |
DELETE /v1/uploads/:id | Delete a car photo |
POST /v1/renders | Start a render |
GET /v1/renders/:id | Get a render |
DELETE /v1/renders/:id | Delete a render |
GET /v1/balance | Renders 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.