Skip to main content
POST

​
Example Output

Creates a new living property video from real estate images. This endpoint uses AI to transform static property photos into dynamic videos with optional virtual staging, AI-generated narration, and background music. The video generation is asynchronous - you’ll receive a task ID to poll for status or configure a webhook to be notified when complete.

​
Key Features

  • Virtual Staging: Add people, furniture, or redecorate rooms using AI
  • AI Narration: Provide your own script for professional text-to-speech narration — or set voiceover_enabled: false for a music-only video
  • Background Music: Optional ambient music that complements your property video
  • Story Mode: Turn the video into one continuous day-in-the-life story told through a family cast, with AI-planned scene order and evolving lighting from morning to night

​
Request Body

​
object[]
required
Array of image objects for the video. Must contain 5 to 9 images.You can also pass a plain URL string instead of an object — it behaves the same as { "url": "..." }.Each image object contains:
  • url (required): Publicly accessible HTTP(S) URL of the property image
  • room_type (optional): Type of room for better AI processing
  • modification_mode (optional): per-image override of the request-level modification_mode — omit to inherit
  • include_humans_and_pets (optional): per-image override of the request-level include_humans_and_pets — omit to inherit
  • space_use (optional): per-image override of the request-level space_use — omit to inherit. See Commercial Space Use below.
  • space_tag (optional): which part of the commercial premises this image shows — omit to derive it. See Commercial Space Use below.
Per-image exceptions. The top-level modification_mode / include_humans_and_pets apply to every image. To make an exception for one image — say, keep a facade original while the rest of the gallery is restyled — set those fields on that image object only:
decoration_style stays request-level — it is a global aesthetic, not a per-image toggle.
All image URLs must be unique. Duplicate URLs are not allowed.
Minimum resolution (HD floor): every image’s long side must be at least 1280 px and short side at least 720 px. Images below this threshold are rejected with IMAGE_RESOLUTION_TOO_LOW. CRMs that expose thumbnail URLs by default usually have a higher-resolution variant — use that one.
​
boolean
default:"true"
Whether the video has a voiceover (narration). Defaults to true.Set to false to create a music-only video: omit voice and script, and the video is produced with background music only (or silent if background_music is false). Subtitles are not available without a voiceover.
​
object
Voice configuration for text-to-speech narration. Required when voiceover_enabled is true (the default); omit it together with script when voiceover_enabled is false.
​
string
required
How to process the property images using AI.
The change_decoration mode uses AI virtual staging to transform your images. Processing may take longer for this mode.
Whether people are added is controlled by include_humans_and_pets. Together with modification_mode, it also selects the per-scene script budget — see script.
furnish was previously accepted but is no longer supported. Requests using it are rejected with a VALIDATION_ERROR. Use change_decoration to restyle or furnish the room, or no_modify to keep it unchanged.
​
string
Interior decoration style applied when modification_mode is change_decoration. Ignored for the other modes. Defaults to a modern aesthetic when omitted.On a commercial image (any image with an effective space_use — see Commercial Space Use), decoration_style has exactly one effect: industrial and mountain-rustic keep the photographed shell’s raw finishes (exposed brick, concrete, visible installations); any other value, or omitting the field, renders a fully renovated space — walls plastered and painted, the ceiling finished with installations hidden, and a new floor suited to the business — the same as for a residential room. The business look itself (furniture, fixtures, people) still comes from space_use, not decoration_style. A facade_exterior image is never renovated by this: the building’s exterior finishes are kept whatever decoration_style is. bathroom and storage_back_room images are renovated too, even though they never get people.
​
string
Request-level default business use for commercial staging. Only takes effect on an image whose effective modification_mode is change_decoration — it has no effect on a no_modify image, and an explicit per-image space_use/space_tag on a no_modify image is rejected (see Commercial Space Use).A per-image images[].space_use overrides this default for that image only. Omit this field entirely to keep every image residential (today’s behavior).
space_use cannot be combined with story_mode. Story scenes are planned server-side and are never commercial; sending both is rejected with VALIDATION_ERROR.
​
boolean
default:"true"
Whether to add realistic people (and occasionally a pet) to the staged scenes.When enabled together with change_decoration, the video uses longer two-step scenes (the room is restyled, then animated), which widens the per-scene script budget — see script. Set to false to keep scenes free of people and use the single-step budget.On a commercial image, people are use-aware instead of generic (a bartender and guests for cocktail-bar, a stylist and a client for hair-beauty-salon, and so on) — see Commercial Space Use below. A commercial image renders like a residential one: with change_decoration and people on, it gets the same before → after reveal. bathroom and storage_back_room images never get people (see below), so they stay single-step regardless of this setting.
​
string
Narration script for text-to-speech. Required when voiceover_enabled is true (the default); omit it together with voice when voiceover_enabled is false. The length must scale with the number of images, and the per-scene budget depends on the render mode:Single-step — no_modify, any mode with include_humans_and_pets set to false, or a request where no image — residential or commercial — qualifies as a two-step candidate (see below). Scenes are ~5 seconds. The recommended length is per narration language (our client app targets it directly); this API enforces the outer envelope across every supported language, 58–87 characters per image:Two-step — a request with at least one two-step candidate: a residential image with change_decoration, people on and no effective space_use, or a commercial image with change_decoration, people on and a space_tag other than bathroom / storage_back_room. Scenes are ~7 seconds (restyle + animation), requiring 110–140 characters per image:
A commercial image renders like a residential one. With change_decoration and people on, it gets the same before → after reveal: the scene opens on the original photo, is renovated as the staged business, then people suited to that business appear — and it counts toward the two-step budget by the same rule as a residential image. bathroom and storage_back_room images never get people (see Commercial Space Use), so they never get the reveal and don’t widen the budget on their own. Example: 6 cocktail-bar images, all with people on and change_decoration, require the two-step budget (660–840 characters). The same 6 images all tagged bathroom stay on the single-step budget (348–522 characters), since a bathroom never gets a reveal.
Scripts outside the applicable range are rejected with SCRIPT_TOO_SHORT or SCRIPT_TOO_LONG.
Numbers and symbols are allowed. Write the script naturally — numbers (e.g. 3 bedrooms, 580.000 €) and symbols are read correctly by text-to-speech. Only emojis and other non-speech characters (pictographs, control characters) are rejected.
Write compelling property descriptions that highlight key features. The script should flow naturally when spoken aloud, and its length must fit the per-scene budget above.
​
boolean
default:"true"
Enable AI-generated background music.When true, adds ambient music that complements the property video. The music is automatically mixed at an appropriate volume to not overpower the narration.
​
string
Optional identifier of a family to cast consistently across every scene, instead of the AI casting different people scene to scene.
  • For a family you own or one shared by your organization, pass its UUID.
  • For a preset family, pass its slug, e.g. family-with-kids.
The family must be in ready status, and using it (whether a preset or one of your own) requires a Pro, Max, or Enterprise plan. Members can appear in different combinations and counts from scene to scene, always drawn from the same cast.Omit this field to leave casting behavior unchanged. Using a family does not change the credit cost of the video.
Browse available families with List Families, or create your own with Create Family.
​
boolean
default:"false"
Turn the video into one continuous day-in-the-life story told through the selected family. Instead of independent per-room scenes, the AI plans the whole video at creation time: it orders the scenes from morning to night, picks a time of day for each room, chooses which family members appear in each scene and what they are doing, and evolves the lighting across the day.Requirements when story_mode is true:
  • selected_family_id must be set (the story is told through the family cast). Missing it is rejected with STORY_FAMILY_REQUIRED.
  • Every image must carry a room_type so the scenes can be planned. Requests with untyped images are rejected with STORY_ROOM_TYPE_REQUIRED; the error details list the offending image indices.
  • The endpoint’s usual 5 to 9 images bound applies; Story Mode adds no extra count rules.
Write the script as one continuous narration. With story_mode, the AI chooses the scene order, so your images may not appear in the order you uploaded them. Avoid per-photo captions tied to upload order; write a single flowing script instead. The final scene order is visible in the story block of the completed task result (see Get Task).
Using Story Mode does not change the credit cost of the video.
​
string
default:"en"
Language of the generated scene activities in the story plan (2 to 10 characters, e.g. en, es, pt-BR). Only honored when story_mode is true.
​
object
Subtitle configuration for word-level animated overlays. Use subtitle_style_preset for quick setup or styles for granular control. Providing both will result in a validation error.
Requires voiceover. Subtitles are derived from the narration’s word timing, so omit subtitle (or set it to false) when voiceover_enabled is false — the request is rejected otherwise.
​
string
HTTPS URL to receive webhook notification when the task completes.See Webhooks for payload format and verification details.
Webhook URLs must use HTTPS and cannot point to private/internal networks (SSRF protection).
​
object
Configuration for visual elements and branding overlays. If not provided, elements are disabled by default.

​
Commercial Space Use

Stage an empty commercial premises — a restaurant, a shop, an office — instead of a home. Set a business use with space_use (request-level default) and, per image, images[].space_use / images[].space_tag. An image with an effective use is staged from the commercial catalog with people who fit the business, instead of the residential restyle prompt.
This is additive. A request that never sets space_use/space_tag behaves exactly as before — same validation, same charge, residential staging.
Fields Resolution: which image gets staged, and how For each image, the effective mode is images[i].modification_mode ?? modification_mode. The effective use is images[i].space_use ?? space_use, and it only applies when the effective mode is change_decoration — a no_modify image is never commercial, even if it would otherwise inherit a request-level space_use. An image with an effective use is a commercial image. Its space_tag (the effective tag) is resolved in this order:
  1. images[i].space_tag, if set;
  2. derived from room_type: bathroom → bathroom, exterior → facade_exterior, hallway → hallway_common_areas, kitchen → kitchen_workshop;
  3. customer_area otherwise.
room_type is still accepted and stored on a commercial image, but beyond that 4-value derivation it no longer drives staging — the catalog prompt is chosen from space_use + the resolved space_tag. decoration_style still applies to a commercial image, but only for its one renovation effect (see decoration_style above) — the business look itself comes from space_use, not decoration_style.
A request-level space_use inherited by a no_modify image is not an error — that mirrors the existing per-image exception pattern (e.g. a facade you keep original). It only becomes an error when you set space_use/space_tag explicitly on that image — see Validation below.
People With include_humans_and_pets on, a commercial image gets people who fit the business, not generic residential figures — always capped at 4 people total, no pets: How many people appear also depends on the image’s space_tag — a Customer Area gets 2-4 people, a Waiting / Reception gets 1-2, a Counter / Service gets 1-3, a Facade / Exterior gets 0-2 passers-by, a Kitchen / Workshop gets 1-2 staff with no customers, an Internal Office gets 1, and a Hallway / Common Areas gets at most 1 person passing through.
storage_back_room and bathroom never get people, regardless of include_humans_and_pets. A storage room stays storage and a bathroom stays a restroom — they are staged empty, matching how they’d actually look.
Validation Every rule below is a 400 VALIDATION_ERROR, with details.field pointing at the offending field, except the last one, a 503. All checks run before any charge — an invalid request never creates a task or spends credits. Price Commercial space staging does not change the price: this endpoint still charges a flat 15 credits per request, regardless of how many images are commercial, which uses they use, or how many tags you set. Result A completed task whose request had at least one commercial image returns an additive result.space_uses block from Get Task — one entry per commercial image, with the use and tag that were applied. See that page for the shape. It is GET-only: it is never added to webhook payloads. Example: mixed request A cocktail bar with one image tagged as its bathroom, plus one image overridden to a completely different business (a clothing store):
In this example: image 0 (bar area), 1 (seating) and 4 (back wall) resolve to cocktail-bar / customer_area (the default tag). Image 2 resolves to cocktail-bar / facade_exterior (derived from room_type: "exterior"). Image 3 resolves to cocktail-bar / bathroom (explicit tag) and gets no people, even though include_humans_and_pets is true. Image 5 resolves to clothing-store / customer_area — a completely different business than the request-level default. Since five of the six images are two-step candidates, this request renders the before → after reveal for each of them; the bathroom image stays single-step and empty.

​
Test Mode

​
string
default:"success"
Sandbox-only scenario selector. Honored only for test-mode (vpk_test_) keys and silently ignored for live keys, so it is safe to leave in shared request-building code.
Test mode never spends credits or runs the real pipeline. See Test Mode for the full sandbox model.

​
Response

Returns a 202 Accepted response with task details.
​
string
required
Unique identifier for the task. Use this to poll for status via Get Task.
​
string
required
Initial task status. Always queued for new tasks.
​
string
required
Human-readable confirmation message.
​
string
required
Task creation timestamp (ISO 8601 format).
​
integer
required
Number of credits charged for this request (15 credits). Always 0 for test-mode requests.
​
boolean
required
true for live (vpk_live_) requests; false for test-mode (vpk_test_) requests. Use this to tell a real task from a sandbox one. See Test Mode.
​
string
required
Unique request ID for support reference.
​
object
required
HATEOAS links for navigation.
  • self: URL to poll for task status
  • poll_interval_seconds: Recommended polling interval (30 seconds)

​
Response Headers

​
Example: mosaic watermark

Set elements_config.watermark.mode to mosaic to tile the logo across the whole frame instead of placing it once at position. position and size are ignored in mosaic mode; rotation controls the tile angle (-45 to 45, default -20).

​
Example: custom image outro

To close on a flyer, a floor plan or any image of your own instead of a contact card, pick the custom_image outro. It takes one asset and no text, so values stays empty, and it rides the same closing window as every other outro: it adds no duration to the video. If the image’s aspect ratio does not match the video’s, the server extends its background out to the video’s shape before rendering, so the image is never cropped. That runs while this request is being accepted, which is why the POST below can take a few seconds, and up to about 25 seconds when the ratios differ. The image must be a JPG, PNG or WEBP of at most 8 MB whose shortest edge is at least 400 px, and it costs no extra credits.

​
Error Codes

See Error Handling for more details.

​
Credits

This endpoint charges 15 credits per request upon successful task creation. If the task fails during processing, credits are not refunded.

​
Processing Time

Video generation typically takes 3-5 minutes depending on:
  • Number of images
  • Selected modification mode (change_decoration takes longer)
  • Current system load
Use the Retry-After header (30 seconds) as a guide for polling frequency.

​
Next Steps

After creating a task:
  1. Poll for status: Use Get Task to check progress
  2. Wait for webhook: If configured, receive notification when complete
  3. Download video: Access the video URL from the completed task result