Create a preview

Send the photo as a file with multipart form data, or send JSON with a link to the photo.

curl https://api.paintvisualizer.ai/v1/previews \
  -H "Authorization: Bearer pv_your_key" \
  -H "Idempotency-Key: order-1042" \
  -F image=@living-room.jpg \
  -F space=interior \
  -F 'surfaces=[{"surface":"Walls","brand":"sherwin-williams","code":"SW 7029"}]' \
  -F webhook_url=https://example.com/hooks/paint

curl https://api.paintvisualizer.ai/v1/previews \
  -H "Authorization: Bearer pv_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/photos/living-room.jpg",
    "space": "interior",
    "surfaces": [
      { "surface": "Walls", "hex": "#2F4F4F", "name": "Deep slate" },
      { "surface": "Trim", "brand": "benjamin-moore", "code": "OC-17" }
    ]
  }'

imagefile

The photo, in a multipart request. JPEG, PNG, or WebP up to 12 MB. One of image, image_url, or image_base64 is required.

image_urlstring

An https link to the photo, in a JSON request.

image_base64string

The photo as base64 text, in a JSON request. A data URL works too.

spacestringrequired

Either interior or exterior.

surfacesarrayrequired

One to eight surfaces to repaint. In a multipart request, send this as a JSON string.

webhook_urlstring

An https address we call when the preview finishes. See webhooks.

Idempotency-Keyheader

Any text that identifies this request. A repeated request with the same key returns the first preview and uses no extra credit.

Each surface names what to paint and the color to use. Give the color as a brand and code from the catalog, or as a hex value.

surfacestringrequired

What to paint, in plain words. Walls, Trim, Ceiling, Cabinets, Siding, Front door, and Shutters all work.

brandstring

A brand slug such as sherwin-williams. Use together with code.

codestring

The color code as the brand prints it, such as SW 7029. Spacing and capital letters do not matter.

hexstring

A custom color such as #2F4F4F. Use instead of brand and code.

namestring

An optional name for a custom hex color.

Returns the new preview with the status queued and the status code 201. Each surface comes back with the full paint brand, color name, color code, and hex value.

{
  "id": "jd7e8r1qxqnm3gz7e3awx1ypn18fv15j",
  "object": "preview",
  "status": "queued",
  "space": "interior",
  "surfaces": [
    {
      "surface": "Walls",
      "brand": "Sherwin-Williams",
      "color_name": "Agreeable Gray",
      "color_code": "SW 7029",
      "hex": "#D1CBC1"
    }
  ],
  "image_url": null,
  "image_url_expires_at": null,
  "error": null,
  "upscale": null,
  "created_at": "2026-10-07T22:28:21.028Z"
}