The API

Getting a key

Sign in, open Settings, and press Create a key. Give it a name you will recognise later — till system, website — because that name and the first few characters are the only way to tell two keys apart afterwards.

A key spends the credits of the account that made it. Treat it like a password: keep it on your server, never in a web page, an app, or anything a customer can read. Revoking is instant — the next request carrying a revoked key is refused.

Authenticating

Every request carries the key in the Authorization header.

Authorization: Bearer ws_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

There is no way to pass a key in the URL, on purpose. A credential in a query string is written into every access log it passes through and sent onward in the Referer header.

Anything that is not a live key belonging to a usable account gets the same 401 — missing, malformed, unknown, revoked, or an account that has been closed. The answer does not say which, because a reply that distinguished them would let somebody with a wrong key learn that a right one exists.

Asking for a render

Send the photographs as base64. A data: URL is accepted as well as raw base64, because that is what a browser's FileReader produces and an integration written from a browser example will send one.

curl https://wheel-swap.com/api/v1/renders \
  -H "Authorization: Bearer $WHEELSWAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "kind": "WheelSwap",
        "car":  "<base64 of the car photograph>",
        "wheel":"<base64 of the wheel you want fitted>"
      }'

A successful request answers 202 Accepted. Nothing is rendered yet.

{
  "id": "01a0c3c6-97a2-743a-8157-09ae37157e09",
  "status": "queued",
  "kind": "WheelSwap",
  "credits": 1,
  "createdAt": "2026-09-21T11:42:07.113Z"
}

The Location header carries the same address as the id, so a client that follows it needs no string building of its own.

Checking whether it is finished

{
  "id": "01a0c3c6-97a2-743a-8157-09ae37157e09",
  "status": "delivered",
  "kind": "WheelSwap",
  "credits": 1,
  "createdAt": "2026-09-21T11:42:07.113Z",
  "photoExpiresAt": "2026-09-22T11:42:07.113Z",
  "photoFirstUploadedAt": "2026-09-21T11:42:07.113Z",
  "result": "/api/v1/renders/01a0c3c6-97a2-743a-8157-09ae37157e09/image",
  "error": null,
  "errorCode": null
}

Poll until result is not null, rather than until status says a particular word. A render takes around half a minute; once every second or two is polite and well inside the limit.

photoExpiresAt is when the photographs you sent for this render are deleted, in UTC: 24 hours after they were last used, and 7 days after upload at the latest. Sending the same photograph again uses the stored one and moves this time. It is null once they are gone; the result is kept.

Fetching the render

Returns the JPEG. Carry the same Authorization header — this is not a public URL, and it is not a redirect, so an HTTP client that does not follow redirects works exactly as one that does.

Until the account has bought credits at least once, every render carries a small mark in the corner, here and in the studio alike. More credits lift it on renders made afterwards.

Credits and usage

{
  "credits":  { "plan": 8, "permanent": 120, "total": 128 },
  "lastThirtyDays": { "delivered": 46, "failed": 1, "inFlight": 0 },
  "limits":   { "rendersPerHour": 120, "readsPerHour": 3600 }
}

Two pots, because they behave differently. Plan credits come with a monthly subscription and are cleared at the end of each cycle, used or not. Permanent credits were bought outright or given as compensation, and never expire. Spending takes from the plan pot first, so the ones with a deadline go before the ones without.

When something is wrong

Every failure is the same shape: a code to branch on and a sentence to show.

{ "error": "insufficient_credits",
  "message": "This render costs 1 credit(s) and the balance is 0." }

A whole integration

Submit, poll, save. This is the entire client — there is nothing else to it.

const KEY = process.env.WHEELSWAP_KEY;
const auth = { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" };

async function render(carBase64, wheelBase64) {
  const started = await fetch("https://wheel-swap.com/api/v1/renders", {
    method: "POST",
    headers: auth,
    body: JSON.stringify({ kind: "WheelSwap", car: carBase64, wheel: wheelBase64 })
  });

  if (!started.ok) throw new Error((await started.json()).message);
  const { id } = await started.json();

  // Half a minute is typical. Give up long after that rather than just after it.
  for (let waited = 0; waited < 180; waited++) {
    await new Promise(r => setTimeout(r, 1000));

    const look = await fetch(`https://wheel-swap.com/api/v1/renders/${id}`, { headers: auth });
    const job = await look.json();

    if (job.result) {
      const image = await fetch(`https://wheel-swap.com${job.result}`, { headers: auth });
      return Buffer.from(await image.arrayBuffer());
    }

    if (job.status === "failed") throw new Error(job.error);
  }

  throw new Error("Still not finished after three minutes.");
}

What this API does not do yet

Listed because you will find out anyway, and it is cheaper for both of us if you find out now.

• No shop accounts. A key belongs to one person's account and spends that account's credits. A shop with three people sharing the work needs one shared login, not three.
• No webhooks. You poll. A render takes around half a minute, so this is workable, but it is polling and we know it.
• No background photograph. The studio lets you attach a scene to put the car in; this endpoint does not accept one.
• No batches. One render per request. Send several requests.
• This is a visual preview, not a fitment check. Diameter, offset, bolt pattern and brake clearance cannot be read from a photograph, and your customer still needs to hear those from you.