Create Living Property Video

curl -X POST https://api.vibepeak.ai/v1/real-estate/living-property \
  -H "Authorization: Bearer vpk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "images": [
      { "url": "https://example.com/property/living-room.jpg", "room_type": "living_room" },
      { "url": "https://example.com/property/kitchen.jpg", "room_type": "kitchen" },
      { "url": "https://example.com/property/bedroom.jpg", "room_type": "bedroom" },
      { "url": "https://example.com/property/bathroom.jpg", "room_type": "bathroom" },
      { "url": "https://example.com/property/exterior.jpg", "room_type": "exterior" }
    ],
    "voice": {
      "voice_id": "EXAVITQu4vr4xnSDxMaL",
      "language": "en"
    },
    "modification_mode": "no_modify",
    "script": "Welcome to this stunning modern home where comfort meets contemporary design. The spacious living room is filled with natural light and elegant finishes. The kitchen offers sleek cabinetry and generous counter space. Each bedroom feels calm and inviting, while the bright bathroom adds a touch of luxury. Step outside to enjoy a beautiful private garden.",
    "webhook_url": "https://yourserver.com/webhooks/vibepeak",
    "subtitle": {
      "subtitle_style_preset": "classic"
    },
    "elements_config": {
      "enabled": true,
      "watermark": {
        "url": "https://example.com/logo.png",
        "position": "bottom-right",
        "size": 20,
        "opacity": 100
      },
      "text": {
        "content": "Powered by Vibepeak",
        "color": "#FFFFFF",
        "font": "Inter",
        "size": 20,
        "position": "center"
      }
    }
  }'

{
  "task_id": "task_abc123xyz",
  "status": "queued",
  "message": "Real estate video generation request accepted",
  "created_at": "2026-01-19T12:00:00Z",
  "credits_charged": 15,
  "livemode": true,
  "request_id": "req_xyz123",
  "_links": {
    "self": "/v1/tasks/task_abc123xyz",
    "poll_interval_seconds": 30
  }
}

POST

real-estate

living-property

curl -X POST https://api.vibepeak.ai/v1/real-estate/living-property \
  -H "Authorization: Bearer vpk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "images": [
      { "url": "https://example.com/property/living-room.jpg", "room_type": "living_room" },
      { "url": "https://example.com/property/kitchen.jpg", "room_type": "kitchen" },
      { "url": "https://example.com/property/bedroom.jpg", "room_type": "bedroom" },
      { "url": "https://example.com/property/bathroom.jpg", "room_type": "bathroom" },
      { "url": "https://example.com/property/exterior.jpg", "room_type": "exterior" }
    ],
    "voice": {
      "voice_id": "EXAVITQu4vr4xnSDxMaL",
      "language": "en"
    },
    "modification_mode": "no_modify",
    "script": "Welcome to this stunning modern home where comfort meets contemporary design. The spacious living room is filled with natural light and elegant finishes. The kitchen offers sleek cabinetry and generous counter space. Each bedroom feels calm and inviting, while the bright bathroom adds a touch of luxury. Step outside to enjoy a beautiful private garden.",
    "webhook_url": "https://yourserver.com/webhooks/vibepeak",
    "subtitle": {
      "subtitle_style_preset": "classic"
    },
    "elements_config": {
      "enabled": true,
      "watermark": {
        "url": "https://example.com/logo.png",
        "position": "bottom-right",
        "size": 20,
        "opacity": 100
      },
      "text": {
        "content": "Powered by Vibepeak",
        "color": "#FFFFFF",
        "font": "Inter",
        "size": 20,
        "position": "center"
      }
    }
  }'

{
  "task_id": "task_abc123xyz",
  "status": "queued",
  "message": "Real estate video generation request accepted",
  "created_at": "2026-01-19T12:00:00Z",
  "credits_charged": 15,
  "livemode": true,
  "request_id": "req_xyz123",
  "_links": {
    "self": "/v1/tasks/task_abc123xyz",
    "poll_interval_seconds": 30
  }
}

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

Request Body

images

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

Show Available room types

bedroom, kitchen, living_room, bathroom, dining_room, office, garage, basement, attic, patio, balcony, garden, pool, exterior, entrance, hallway, laundry, other

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:

{
  "modification_mode": "change_decoration",
  "include_humans_and_pets": true,
  "images": [
    "https://example.com/property/living-room.jpg",
    {
      "url": "https://example.com/property/facade.jpg",
      "room_type": "exterior",
      "modification_mode": "no_modify",
      "include_humans_and_pets": false
    }
  ]
}

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.

voiceover_enabled

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.

voice

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.

Show Voice properties

voice_id

string

required

Voice ID to use for narration. You can find available voices using the List Voices endpoint.

language

string

required

ISO 639-1 language code for TTS pronunciation (e.g., en, es, de, fr, pt).This helps produce more accurate pronunciation for the target language.

Use the same language code as the script content for best results.

modification_mode

string

required

How to process the property images using AI.

Value	Description
`no_modify`	Keep rooms as-is, add realistic people for a lived-in feel
`change_decoration`	Modernize old or outdated furniture and decor

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.

decoration_style

string

Interior decoration style applied when modification_mode is change_decoration. Ignored for the other modes. Defaults to a modern aesthetic when omitted.

Show Available styles

scandinavian, minimalist, traditional, mid-century-modern, industrial, mediterranean, modern, bohemian, mountain-rustic, luxury, japandi, wabi-sabi, organic-modern, quiet-luxury

include_humans_and_pets

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.

script

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, or any mode with include_humans_and_pets set to false. Scenes are ~5 seconds, requiring 65–85 characters per image:

Images	Min characters	Max characters
5	325	425
9	585	765

Two-step — change_decoration with include_humans_and_pets set to true (the default). Scenes are ~7 seconds (restyle + animation), requiring 110–140 characters per image:

Images	Min characters	Max characters
5	550	700
9	990	1260

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.

background_music

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.

subtitle

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.

Show Subtitle Config properties

subtitle_style_preset

string

Name of a predefined style to apply. Options: classic, cinematic, gradient, handwritten, hustle, karaoke_highlight_no_box, karaoke_red_box_phrase, karaoke_word_box_clip, minimal, neon, one_word_red_box, phrase_yellow, retro, tiktok_default, youtube_caption.

styles

object

Granular styling properties for subtitle rendering.

Show Styles properties

alignment

integer

default:"2"

SSA alignment: 1-9 (e.g., 2 for bottom-center).

backColor

string

default:"#000000"

Background color in hex format (e.g., #000000).

backOpacity

integer

default:"100"

Transparency of background box: 0-255.

behavior

string

default:"phrase_blocks"

Subtitle reveal behavior. Options: phrase_blocks, one_word, karaoke_highlight, karaoke_box_word.

borderStyle

integer

default:"1"

Border style: 1 (Outline) or 3 (Box).

fontFamily

string

default:"Arial"

System font name.

fontSize

integer

default:"28"

Font size in pixels (14-96).

marginL

integer

default:"40"

Left margin in pixels (0-500).

marginR

integer

default:"40"

Right margin in pixels (0-500).

marginV

integer

default:"200"

Vertical/Bottom margin in pixels (0-500).

maxGapSeconds

number

default:"0.3"

Max silence (sec) between words before phrase break (0.01-2).

maxWordsPerLine

integer

default:"6"

Automatic line wrapping constraint (1-12).

outline

integer

default:"2"

Thickness of text stroke (0-10).

outlineColor

string

default:"#000000"

Color of text stroke in hex format.

primaryColor

string

default:"#FFFFFF"

Default text color in hex format.

secondaryColor

string

default:"#FFFFFF"

Alt color for highlights/karaoke in hex format.

shadow

integer

default:"0"

Thickness of text drop shadow (0-10).

webhook_url

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).

elements_config

object

Configuration for visual elements and branding overlays. If not provided, elements are disabled by default.

Show Elements Config properties

enabled

boolean

default:"false"

Global toggle for the elements overlay feature.

watermark

object

Watermark (logo) branding configuration.

Show Watermark properties

url

string

required

URL of the uploaded watermark image. Must be a valid public URL.

position

string

default:"bottom-right"

Anchor point for the watermark placement. Options: top-left, top-center, top-right, center-left, center, center-right, bottom-left, bottom-center, bottom-right.

size

number

default:"20"

Relative scale percentage of the watermark (0-100).

opacity

number

default:"100"

Transparency level (0 for transparent, 100 for opaque).

text

object

Text overlay configuration for static labels or call-to-actions.

Show Text properties

content

string

required

Text content to be rendered on the video (max 20 characters).

color

string

default:"#FFFFFF"

Hex color code for the text (e.g., #FFFFFF).

font

string

default:"Inter"

Font family for the text overlay. Options: Alegreya, DM Mono, Inter, Libre Bodoni, Quicksand, Roboto, Raleway, Noto Sans, Zilla Slab.

opacity

number

default:"100"

Transparency level of the text (0-100).

size

number

default:"20"

Font size scale relative to video height (1-100).

position

string

default:"center"

Anchor point for the text placement. Same options as watermark position.

Test Mode

test_scenario

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.

Value	Outcome
`success`	Synthetic task completes with a watermarked sample video
`fail`	Synthetic task fails with a sanitized, public-safe error
`slow`	Like `success`, but completes after a noticeably longer delay

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.

task_id

string

required

Unique identifier for the task. Use this to poll for status via Get Task.

status

string

required

Initial task status. Always queued for new tasks.

message

string

required

Human-readable confirmation message.

created_at

string

required

Task creation timestamp (ISO 8601 format).

credits_charged

integer

required

Number of credits charged for this request (15 credits). Always 0 for test-mode requests.

livemode

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.

request_id

string

required

Unique request ID for support reference.

_links

object

required

HATEOAS links for navigation.

self: URL to poll for task status
poll_interval_seconds: Recommended polling interval (30 seconds)

Response Headers

Header	Description
`Location`	URL to poll for task status (`/v1/tasks/{taskId}`)
`Retry-After`	Recommended polling interval in seconds (30)

curl -X POST https://api.vibepeak.ai/v1/real-estate/living-property \
  -H "Authorization: Bearer vpk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "images": [
      { "url": "https://example.com/property/living-room.jpg", "room_type": "living_room" },
      { "url": "https://example.com/property/kitchen.jpg", "room_type": "kitchen" },
      { "url": "https://example.com/property/bedroom.jpg", "room_type": "bedroom" },
      { "url": "https://example.com/property/bathroom.jpg", "room_type": "bathroom" },
      { "url": "https://example.com/property/exterior.jpg", "room_type": "exterior" }
    ],
    "voice": {
      "voice_id": "EXAVITQu4vr4xnSDxMaL",
      "language": "en"
    },
    "modification_mode": "no_modify",
    "script": "Welcome to this stunning modern home where comfort meets contemporary design. The spacious living room is filled with natural light and elegant finishes. The kitchen offers sleek cabinetry and generous counter space. Each bedroom feels calm and inviting, while the bright bathroom adds a touch of luxury. Step outside to enjoy a beautiful private garden.",
    "webhook_url": "https://yourserver.com/webhooks/vibepeak",
    "subtitle": {
      "subtitle_style_preset": "classic"
    },
    "elements_config": {
      "enabled": true,
      "watermark": {
        "url": "https://example.com/logo.png",
        "position": "bottom-right",
        "size": 20,
        "opacity": 100
      },
      "text": {
        "content": "Powered by Vibepeak",
        "color": "#FFFFFF",
        "font": "Inter",
        "size": 20,
        "position": "center"
      }
    }
  }'

{
  "task_id": "task_abc123xyz",
  "status": "queued",
  "message": "Real estate video generation request accepted",
  "created_at": "2026-01-19T12:00:00Z",
  "credits_charged": 15,
  "livemode": true,
  "request_id": "req_xyz123",
  "_links": {
    "self": "/v1/tasks/task_abc123xyz",
    "poll_interval_seconds": 30
  }
}

Error Codes

Code	Status	Description
`INVALID_JSON`	400	Request body is not valid JSON (malformed/truncated payload)
`VALIDATION_ERROR`	400	Invalid request parameters
`INVALID_IMAGE_URL`	400	One or more image URLs are inaccessible or invalid
`INVALID_WATERMARK_URL`	400	The `elements_config` watermark URL is inaccessible or does not return an image
`IMAGE_RESOLUTION_TOO_LOW`	400	One or more images are below the HD floor (long ≥ 1280 px, short ≥ 720 px)
`SCRIPT_TOO_SHORT`	400	Script is shorter than the per-scene minimum (`image_count × 65` single-step, `× 120` two-step)
`SCRIPT_TOO_LONG`	400	Script is longer than the per-scene maximum (`image_count × 85` single-step, `× 150` two-step)
`SCRIPT_INVALID_CHARACTERS`	400	Script contains emojis or other non-speech characters not supported by TTS
`VOICE_NOT_FOUND`	404	The specified voice ID does not exist
`VOICE_ACCESS_DENIED`	403	The specified voice is not accessible to your account
`INVALID_API_KEY`	401	Invalid or missing API key
`PLAN_REQUIRED`	403	Plan doesn’t include API access
`INSUFFICIENT_CREDITS`	402	Not enough credits to process the request
`CONCURRENCY_LIMIT_EXCEEDED`	429	Concurrent task limit reached
`SERVICE_UNAVAILABLE`	503	Video generation service temporarily unavailable

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:

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

List Voices Create Narrated Slideshow

​Example Output

​Key Features

​Request Body

​Test Mode

​Response

​Response Headers

​Error Codes

​Credits

​Processing Time

​Next Steps

Example Output

Key Features

Request Body

Test Mode

Response

Response Headers

Error Codes

Credits

Processing Time

Next Steps