Get started

Quickstart

Make your first paint preview with three requests.

Create an API key

Open API keys in your settings and create a key. The API is part of the Business plan. The key is shown once, so copy it somewhere safe.

Send a photo and a color

Post a photo with the surfaces to repaint. This example paints the walls in Agreeable Gray by Sherwin-Williams.

Request

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

The response comes back right away with an id and the status queued.

Get the finished preview

Ask for the preview by its id every few seconds until the status is succeeded.

Request

curl https://api.paintvisualizer.ai/v1/previews/PREVIEW_ID \
  -H "Authorization: Bearer pv_your_key"

Response

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

Download the image from image_url. To skip the waiting loop, use webhooks.

PreviousIntroduction NextAuthentication