Tools

Restyle

Give one or more surfaces of a room a new finish — repaint the walls, change the floor, reface the kitchen cabinets and worktop, retile the bathroom or refinish the furniture — while the room's layout, fittings, windows and camera angle stay exactly as shot.

post/api/v1/tools/restyle_room

Request

  • Base URL: https://pixly.app
  • URL: https://pixly.app/api/v1/tools/restyle_room
  • 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)

Headers

Idempotency-Keystring

Recommended. A retry with the same key and body returns the first run's result (header Idempotency-Replayed: true) instead of running and charging again. Kept 24 hours; failed runs release the key.

Request body

imageUrlstring

Public https URL of the source photo, or a data: URI. Either imageUrl or r2Path is required.

r2Pathstring

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.

surfacesstring[]

Which surfaces get a new finish: 'walls', 'floor', 'cabinets' (fitted joinery plus its worktop and splashback), 'bathroom_tiles' (the tiled walls; a bathroom floor is 'floor') or 'furniture' (upholstery and wood finishes). Omit for walls. The room's layout, fittings and camera never change.

looksobject

The finish per surface: 'auto', one of the presets below, 'custom' with your own words in notes, 'own_colour' (walls, cabinets, furniture) with a hex colour in colours, or 'material_photo' with a photo of the material in references. A finish that does not belong to its surface falls back to 'auto' (the tool picks one that suits the room; several on auto are made to agree). walls: warm_white, soft_grey, greige, sage, deep_navy. floor: light_oak, walnut, grey_plank, polished_concrete, stone_tile. cabinets: white_shaker, charcoal, natural_oak, forest_green, navy_cabinets. bathroom_tiles (wall tiles only; a bathroom floor is 'floor'): white_metro, zellige_white, marble_large, travertine, green_gloss. floor also takes terrazzo, encaustic_pattern, matt_black_hex. furniture: light_neutral, warm_wood, dark_wood, black_leather.

notesobject

Your own description of the finish for a surface, used when that surface's look is "custom" (e.g. "terracotta hex tiles with dark grout"). Set look "custom" and the note together; "custom" with no note falls back to "auto". 120 characters max, and anything in it that is not a description of a finish is ignored.

coloursobject

Any colour as a hex code for walls, cabinets or furniture (e.g. {"walls": "#7A8B6F"}), used when that surface's look is "own_colour". The result matches it closely as it would look in the room's light.

referencesobject

A photo of the material itself — a floor plank, a tile, a fabric swatch, a wallpaper sample — for ONE surface, as the r2Path from create_upload_ticket or list_library (e.g. {"floor": "users/…/oak.jpg"}). Set that surface's look to "material_photo". One photo per run; a close, straight-on photo of the sample works best.

Response

Finished inline — resultUrls present (photo tools)

jobIdstring 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

creditsChargednumber nullable required

Credits debited for this job

createdAtstring date-time required

Submission time

completedAtstring date-time

Present once finished

resultUrlsstring[]

Presigned download URLs (present when completed; valid 7 days)

resultPathsstring[]

Storage path of each result, in resultUrls order — pass one as r2Path (or beforeR2Path, a photos[] item…) to run another tool on this result

errorstring

Failure reason; the message says whether the credit came back immediately or is in 24h refund review

notestring

Hint for agents, e.g. poll again in a few seconds

Changes

No recorded changes to this operation across all 1 revision of this API.