Visualizer renders

Quick answer

POST /visualizer/render with a product image and a swatch starts a render and returns a runId. Poll GET /visualizer/render/{runId} until status is completed. Surface com. Renders spend your workspace’s credits.

The COM/COL flow: the shopper picks a piece and a material (including a photo of their own fabric or leather) and sees the piece rendered in it.

POST /visualizer/render

Field	Type	Notes
productImageUrl	string	Required. The piece to render
swatchUrl	string	Required. The material: a swatch image, or the shopper’s own photo
aspectRatio	string	Default 1:1
email	string	Required up front only when the key is capture-first
instruction	string	Optional plain-language note for the render
swatch2Url	string	Optional second material for two-fabric pieces (one render, one charge)
swatchPlacement · swatch2Placement	string	Where each material goes, in plain words (for example “body”, “seat cushions and back pillows”)
patternDirection · pattern2Direction	string	up_the_roll or railroaded
repeatH · repeatV · repeat2H · repeat2V	number	Pattern repeat in inches, horizontal and vertical, per material

cURL

Terminal

curl -X POST https://share.plunk.io/visualizer/render \
  -H "x-visualizer-key: sk_••••" -H "Content-Type: application/json" \
  -d '{
    "productImageUrl": "https://your.cdn/pieces/harbor-sofa.jpg",
    "swatchUrl": "https://your.cdn/swatches/customer-linen.jpg"
  }'

JavaScript

Browser

const headers = { 'x-visualizer-key': 'sk_••••', 'x-surface': 'com', 'Content-Type': 'application/json' };

const start = await fetch('https://share.plunk.io/visualizer/render', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    productImageUrl: 'https://your.cdn/pieces/harbor-sofa.jpg',
    swatchUrl: 'https://your.cdn/swatches/customer-linen.jpg',
  }),
});
const { runId } = await start.json();

let result;
do {
  await new Promise((r) => setTimeout(r, 3000));
  result = await (await fetch(`https://share.plunk.io/visualizer/render/${runId}`, { headers })).json();
} while (result.status === 'processing');

Python

render.py

import time, requests

headers = {"x-visualizer-key": "kk_••••", "x-surface": "com"}
run = requests.post(
    "https://share.plunk.io/visualizer/render",
    headers=headers,
    json={
        "productImageUrl": "https://your.cdn/pieces/harbor-sofa.jpg",
        "swatchUrl": "https://your.cdn/swatches/customer-linen.jpg",
    },
).json()

while True:
    time.sleep(3)
    r = requests.get(f"https://share.plunk.io/visualizer/render/{run['runId']}", headers=headers).json()
    if r["status"] != "processing":
        break
print(r["outputUrl"])

Response

{
  "runId": "9f4c1e07b2…"
}

Status	Code	When
422	capture_required	Capture-first key, no valid email in the body
429	rate_limited	Per-IP burst limit on site keys
429	daily_cap_reached	The key’s daily render cap is spent
402		Your account is out of credits

GET /visualizer/render/{runId}

Poll until the render lands.

While rendering

{
  "status": "processing",
  "outputUrl": null
}

When it's done

{
  "status": "completed",
  "outputUrl": "https://…/render.png"
}

Related

• Lead capture
• COM/COL requests
• Fabric scale looks wrong