---
title: "Exterior Makeover"
method: POST
path: "/api/v1/tools/makeover_exterior"
tags: ["Tools"]
---

# Exterior Makeover

`POST /api/v1/tools/makeover_exterior`

## Request

- Base URL: `https://pixly.app`
- URL: `https://pixly.app/api/v1/tools/makeover_exterior`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://pixly.app/oauth/authorize`, token URL `https://pixly.app/api/oauth/token`, scopes: `tools`)

Design the garden of an exterior listing photo as one coherent scheme — planting, a terrace or deck, a pool, a pergola, a fire pit, a fence, lighting — in a chosen style, at the right scale and perspective, while the house, its roof, the driveway, the sun direction and the neighbours stay exactly as shot. One run builds the whole scheme.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `imageUrl` string: Public https URL of the source photo, or a data: URI. Either imageUrl or r2Path is required.
  - `r2Path` string: Storage path of a photo already in the user's Pixly library (from list_library, or returned by an upload ticket) — the alternative to imageUrl.
  - `style` 'auto' | 'modern_minimal' | 'mediterranean' | 'classic_english' | 'natural_lowwater' | 'tropical_resort' | 'farmhouse': The design language of the whole scheme: 'modern_minimal', 'mediterranean', 'classic_english', 'natural_lowwater', 'tropical_resort', 'farmhouse', or 'auto' (the default — chosen to suit the house's architecture and the climate in the photo).
  - `include` string[]: Which elements the scheme includes, any number: 'planting' (beds, hedges, a feature tree), 'patio_dining' (a paved terrace with a dining set), 'deck_lounge' (a deck with loungers or a low sofa), 'pool', 'pergola', 'fire_pit', 'fence_gate' (a boundary treatment with a gate), 'lighting'. Omit or send an empty list (the default) to let the tool design what the lot wants. One run composes them all into one garden, each sized to the plot.
  - `scope` 'add' | 'full': 'full' (the default) redesigns the whole yard in the style; 'add' keeps the existing garden and builds the chosen elements into it. The house, the driveway and the neighbours never change either way.
  - `note` string: Your own words about the garden you want (e.g. "a small kidney-shaped pool with a stone surround and lavender everywhere"). 160 characters max; anything in it that is not a description of the garden is ignored.

## Response `200`

Finished inline — resultUrls present (photo tools)

- Job
  - `jobId` string, required: Job id — pass to get_job to poll
  - `type` 'image_staging' | 'video_pair' | 'video_tour', required: Job family
  - `status` 'pending' | 'processing' | 'completed' | 'failed', required: Anything not completed/failed is still running
  - `creditsCharged` number, nullable, required: Credits debited for this job
  - `createdAt` string, date-time, required: Submission time
  - `completedAt` string, date-time: Present once finished
  - `resultUrls` string[]: Presigned download URLs (present when completed; valid 7 days)
  - `resultPaths` string[]: Storage path of each result, in resultUrls order — pass one as r2Path (or beforeR2Path, a photos[] item…) to run another tool on this result
  - `error` string: Failure reason; the message says whether the credit came back immediately or is in 24h refund review
  - `note` string: Hint for agents, e.g. poll again in a few seconds

## Other responses

- `202`: Accepted and running — poll GET /api/v1/jobs/{id} (video tools)
- `401`: Missing/invalid credential
- `402`: Out of credits, or no active subscription (error.required = credits needed) — POST /api/v1/checkout returns a payment link
- `409`: A request with the same Idempotency-Key is still running — retry in a few seconds for its result
- `410`: Source photo no longer available — re-upload
- `422`: Invalid input — error.issues lists the offending fields
- `429`: Rate limited — see Retry-After (120 req/min, 30/min for generations)

---

[API](https://skmtc.dev/pixly/apis/pixly-api.md) · [All operations](https://skmtc.dev/pixly/apis/pixly-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pixly/apis/pixly-api/revisions/6f1aae1786ea?raw)