Create Narrated Slideshow

curl -X POST https://api.vibepeak.ai/v1/real-estate/narrated-slideshow \
  -H "Authorization: Bearer vpk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "images": [
      "https://example.com/property/living-room.jpg",
      "https://example.com/property/kitchen.jpg",
      "https://example.com/property/bedroom.jpg",
      "https://example.com/property/bathroom.jpg",
      "https://example.com/property/backyard.jpg",
      "https://example.com/property/exterior.jpg"
    ],
    "voice": {
      "voice_id": "EXAVITQu4vr4xnSDxMaL",
      "language": "en"
    },
    "orientation": "portrait",
    "script": "Welcome to this stunning 3-bedroom home in the heart of the city. The open-concept living area floods with natural light...",
    "orchestration_mode": "standard",
    "webhook_url": "https://yourserver.com/webhooks/vibepeak",
    "background_music": true,
    "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"
      }
    }
  }'

const response = await fetch('https://api.vibepeak.ai/v1/real-estate/narrated-slideshow', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vpk_live_xxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    images: [
      'https://example.com/property/living-room.jpg',
      'https://example.com/property/kitchen.jpg',
      'https://example.com/property/bedroom.jpg',
      'https://example.com/property/bathroom.jpg',
      'https://example.com/property/backyard.jpg',
      'https://example.com/property/exterior.jpg'
    ],
    voice: {
      voice_id: 'EXAVITQu4vr4xnSDxMaL',
      language: 'en'
    },
    orientation: 'portrait',
    script: 'Welcome to this stunning 3-bedroom home...',
    orchestration_mode: 'standard',
    webhook_url: 'https://yourserver.com/webhooks/vibepeak',
    background_music: true,
    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'
      }
    }
  })
});

const task = await response.json();
console.log(`Task created: ${task.task_id}`);

import requests

response = requests.post(
    'https://api.vibepeak.ai/v1/real-estate/narrated-slideshow',
    headers={
        'Authorization': 'Bearer vpk_live_xxxxx',
        'Content-Type': 'application/json'
    },
    json={
        'images': [
            'https://example.com/property/living-room.jpg',
            'https://example.com/property/kitchen.jpg',
            'https://example.com/property/bedroom.jpg',
            'https://example.com/property/bathroom.jpg',
            'https://example.com/property/backyard.jpg',
            'https://example.com/property/exterior.jpg'
        ],
        'voice': {
            'voice_id': 'EXAVITQu4vr4xnSDxMaL',
            'language': 'en'
        },
        'orientation': 'portrait',
        'script': 'Welcome to this stunning 3-bedroom home...',
        'orchestration_mode': 'standard',
        'webhook_url': 'https://yourserver.com/webhooks/vibepeak',
        'background_music': True,
        '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 = response.json()
print(f"Task created: {task['task_id']}")

{
  "task_id": "task_abc123xyz",
  "status": "queued",
  "queue_position": 3,
  "estimated_completion": "2026-01-04T12:30:00Z",
  "created_at": "2026-01-04T12:00:00Z",
  "livemode": true
}

{
  "task_id": "task_abc123xyz",
  "status": "queued",
  "message": "Video generation request accepted",
  "created_at": "2026-01-04T12:00:00Z",
  "livemode": false,
  "request_id": "req_xyz123",
  "_links": {
    "self": "/v1/tasks/task_abc123xyz",
    "poll_interval_seconds": 30
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "images must contain between 6 and 15 URLs",
    "request_id": "req_xyz123"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Provide either 'subtitle_style_preset' or 'styles', but not both.",
    "request_id": "req_xyz123"
  }
}

{
  "error": {
    "code": "SCRIPT_TOO_SHORT",
    "message": "Script is too short for 6 images. Minimum 240 characters required (40 per image), but got 100.",
    "request_id": "req_xyz123",
    "details": {
      "script_length": 100,
      "min_length": 240,
      "max_length": 300,
      "image_count": 6
    }
  }
}

{
  "error": {
    "code": "SCRIPT_TOO_LONG",
    "message": "Script is too long for 6 images. Maximum 300 characters allowed (50 per image), but got 500.",
    "request_id": "req_xyz123",
    "details": {
      "script_length": 500,
      "min_length": 240,
      "max_length": 300,
      "image_count": 6
    }
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "If elements_config is enabled, you must provide at least a 'watermark' or 'text' configuration.",
    "request_id": "req_xyz123",
    "details": {
      "path": ["elements_config", "enabled"]
    }
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid hex color",
    "request_id": "req_xyz123",
    "details": {
      "path": ["elements_config", "text", "color"]
    }
  }
}

{
  "error": {
    "code": "SCRIPT_INVALID_CHARACTERS",
    "message": "Script contains characters not supported by text-to-speech: \"🏠\". Emojis and other non-speech symbols are not allowed.",
    "request_id": "req_xyz123",
    "details": {
      "invalid_characters": ["3", "2"]
    }
  }
}

{
  "error": {
    "code": "CONCURRENCY_LIMIT_EXCEEDED",
    "message": "You have reached your concurrent task limit of 1. Please wait for existing tasks to complete.",
    "request_id": "req_xyz123",
    "details": {
      "limit": 1,
      "in_flight": 1,
      "plan": "Plus"
    }
  }
}

POST

real-estate

narrated-slideshow

curl -X POST https://api.vibepeak.ai/v1/real-estate/narrated-slideshow \
  -H "Authorization: Bearer vpk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "images": [
      "https://example.com/property/living-room.jpg",
      "https://example.com/property/kitchen.jpg",
      "https://example.com/property/bedroom.jpg",
      "https://example.com/property/bathroom.jpg",
      "https://example.com/property/backyard.jpg",
      "https://example.com/property/exterior.jpg"
    ],
    "voice": {
      "voice_id": "EXAVITQu4vr4xnSDxMaL",
      "language": "en"
    },
    "orientation": "portrait",
    "script": "Welcome to this stunning 3-bedroom home in the heart of the city. The open-concept living area floods with natural light...",
    "orchestration_mode": "standard",
    "webhook_url": "https://yourserver.com/webhooks/vibepeak",
    "background_music": true,
    "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"
      }
    }
  }'

const response = await fetch('https://api.vibepeak.ai/v1/real-estate/narrated-slideshow', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vpk_live_xxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    images: [
      'https://example.com/property/living-room.jpg',
      'https://example.com/property/kitchen.jpg',
      'https://example.com/property/bedroom.jpg',
      'https://example.com/property/bathroom.jpg',
      'https://example.com/property/backyard.jpg',
      'https://example.com/property/exterior.jpg'
    ],
    voice: {
      voice_id: 'EXAVITQu4vr4xnSDxMaL',
      language: 'en'
    },
    orientation: 'portrait',
    script: 'Welcome to this stunning 3-bedroom home...',
    orchestration_mode: 'standard',
    webhook_url: 'https://yourserver.com/webhooks/vibepeak',
    background_music: true,
    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'
      }
    }
  })
});

const task = await response.json();
console.log(`Task created: ${task.task_id}`);

import requests

response = requests.post(
    'https://api.vibepeak.ai/v1/real-estate/narrated-slideshow',
    headers={
        'Authorization': 'Bearer vpk_live_xxxxx',
        'Content-Type': 'application/json'
    },
    json={
        'images': [
            'https://example.com/property/living-room.jpg',
            'https://example.com/property/kitchen.jpg',
            'https://example.com/property/bedroom.jpg',
            'https://example.com/property/bathroom.jpg',
            'https://example.com/property/backyard.jpg',
            'https://example.com/property/exterior.jpg'
        ],
        'voice': {
            'voice_id': 'EXAVITQu4vr4xnSDxMaL',
            'language': 'en'
        },
        'orientation': 'portrait',
        'script': 'Welcome to this stunning 3-bedroom home...',
        'orchestration_mode': 'standard',
        'webhook_url': 'https://yourserver.com/webhooks/vibepeak',
        'background_music': True,
        '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 = response.json()
print(f"Task created: {task['task_id']}")

{
  "task_id": "task_abc123xyz",
  "status": "queued",
  "queue_position": 3,
  "estimated_completion": "2026-01-04T12:30:00Z",
  "created_at": "2026-01-04T12:00:00Z",
  "livemode": true
}

{
  "task_id": "task_abc123xyz",
  "status": "queued",
  "message": "Video generation request accepted",
  "created_at": "2026-01-04T12:00:00Z",
  "livemode": false,
  "request_id": "req_xyz123",
  "_links": {
    "self": "/v1/tasks/task_abc123xyz",
    "poll_interval_seconds": 30
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "images must contain between 6 and 15 URLs",
    "request_id": "req_xyz123"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Provide either 'subtitle_style_preset' or 'styles', but not both.",
    "request_id": "req_xyz123"
  }
}

{
  "error": {
    "code": "SCRIPT_TOO_SHORT",
    "message": "Script is too short for 6 images. Minimum 240 characters required (40 per image), but got 100.",
    "request_id": "req_xyz123",
    "details": {
      "script_length": 100,
      "min_length": 240,
      "max_length": 300,
      "image_count": 6
    }
  }
}

{
  "error": {
    "code": "SCRIPT_TOO_LONG",
    "message": "Script is too long for 6 images. Maximum 300 characters allowed (50 per image), but got 500.",
    "request_id": "req_xyz123",
    "details": {
      "script_length": 500,
      "min_length": 240,
      "max_length": 300,
      "image_count": 6
    }
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "If elements_config is enabled, you must provide at least a 'watermark' or 'text' configuration.",
    "request_id": "req_xyz123",
    "details": {
      "path": ["elements_config", "enabled"]
    }
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid hex color",
    "request_id": "req_xyz123",
    "details": {
      "path": ["elements_config", "text", "color"]
    }
  }
}

{
  "error": {
    "code": "SCRIPT_INVALID_CHARACTERS",
    "message": "Script contains characters not supported by text-to-speech: \"🏠\". Emojis and other non-speech symbols are not allowed.",
    "request_id": "req_xyz123",
    "details": {
      "invalid_characters": ["3", "2"]
    }
  }
}

{
  "error": {
    "code": "CONCURRENCY_LIMIT_EXCEEDED",
    "message": "You have reached your concurrent task limit of 1. Please wait for existing tasks to complete.",
    "request_id": "req_xyz123",
    "details": {
      "limit": 1,
      "in_flight": 1,
      "plan": "Plus"
    }
  }
}

Creates a new video generation task from property images. The video is generated asynchronously - you’ll receive a task ID to poll for status or configure a webhook to be notified when complete.

Request Body

string[] | object[]

required

Images for the slideshow. Must contain 6 to 15 images, and all entries must be unique (no duplicates allowed).Each array entry can take one of two shapes. Pick a single shape for the whole array — you cannot mix strings and objects.1. Simple (URL strings): an array of image URLs. Every image renders as a static still. This is the default behavior.2. Rich (objects): an array of objects, where each image can opt into a subtle camera move (the “reanimate” option).Images should be:

Publicly accessible HTTP(S) URLs (not a private/internal address)
JPEG, PNG, or WebP format
Minimum resolution: 720p recommended

Show Rich image object properties

string

required

The image URL. Same rules as the string shape: a public HTTP(S) URL that cannot point to a private/internal address.

boolean

default:"false"

When true, VibePeak’s animation pipeline applies a subtle camera move to this image. When false or omitted, the image renders as a static still.

string

Which camera move to apply. One of:

traveling_left
traveling_right
traveling_up
traveling_down
dolly_in
dolly_out

Use null (together with reanimate: true) to let VibePeak pick a move automatically.

string

Optional scene label (max 64 characters) used to tune the camera move to the kind of room, e.g. "living room", "bedroom", "kitchen", "bathroom", "garden". Omit to use a neutral default.

reanimate and movement go together. When reanimate is true, movement is required — supply one of the six values above or null (which lets VibePeak pick a move automatically). When reanimate is false or omitted, movement must not be set.

For the best visual result, upload images that already match your target format. When orientation is set to portrait, the pipeline can expand landscape photos to fit a 9:16 output when needed.

string

Optional output orientation for the final video.

Value	Description
`landscape`	Generate a horizontal 16:9 video
`portrait`	Generate a vertical 9:16 video

If omitted, VibePeak auto-detects the orientation from the first image and defaults to landscape if detection is not possible.

Choosing portrait is useful when you want social-first vertical output from a mixed or landscape-heavy photo set.

boolean

default:"true"

Whether the video has a voiceover (narration). Defaults to true.Set to false to create a music-only slideshow: omit voice and script, and the video is produced with background music only (or silent if background_music is false). Without a voiceover, subtitle and avatar_id are not available and will be rejected.

object

Voice configuration for the AI-generated narration. Required when voiceover_enabled is true (the default); omit it together with script when voiceover_enabled is false.

Show Voice properties

string

required

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

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.

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 script length must be proportional to the number of images to ensure proper narration pacing (~3 seconds per image):

Images	Min Characters	Max Characters
6	240	300
10	400	500
15	600	750

Formula: min = images × 40, max = images × 50

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.

Scripts that are too short or too long for the number of images will be rejected with SCRIPT_TOO_SHORT or SCRIPT_TOO_LONG error codes.

string

default:"artistic"

Video orchestration mode that controls scene pacing and transitions.

Value	Description
`standard`	Standard mode with scenes of 3-7 seconds
`artistic`	Cinematic mode with 2-3 second scenes and visual weight hierarchy (default)
`sequential`	Images appear in order without AI reordering. Scene duration is auto-calculated.

string

URL to receive webhook notification when the task completes.Must be a valid HTTPS URL. See Webhooks for details.

Webhook URLs must use HTTPS and cannot point to private/internal networks (SSRF protection).

string

Optional UUID of an avatar to include in the video.Must be a valid UUID v4 format (e.g., 123e4567-e89b-12d3-a456-426614174000).

Requires voiceover. A speaking avatar needs narration, so omit avatar_id when voiceover_enabled is false (music-only or silent video) — the request is rejected otherwise.

boolean

default:"false"

Enable AI-generated background music for the video.When true, generates calm ambient music that matches the video duration. The music is automatically generated with a real estate style (soft piano, elegant, minimal) and mixed at 20% volume to complement the narration.

Background music generation adds a few seconds to the processing time. If music generation fails, the video will still be created without background music.

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

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.

object

Granular styling properties for subtitle rendering.

Show Styles properties

integer

default:"2"

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

string

default:"#000000"

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

integer

default:"100"

Transparency of background box: 0-255.

string

default:"phrase_blocks"

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

integer

default:"1"

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

string

default:"Arial"

System font name.

integer

default:"28"

Font size in pixels (14-96).

integer

default:"40"

Left margin in pixels (0-500).

integer

default:"40"

Right margin in pixels (0-500).

integer

default:"200"

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

number

default:"0.3"

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

integer

default:"6"

Automatic line wrapping constraint (1-12).

integer

default:"2"

Thickness of text stroke (0-10).

string

default:"#000000"

Color of text stroke in hex format.

string

default:"#FFFFFF"

Default text color in hex format.

string

default:"#FFFFFF"

Alt color for highlights/karaoke in hex format.

integer

default:"0"

Thickness of text drop shadow (0-10).

object

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

Show Elements Config properties

boolean

default:"false"

Global toggle for the elements overlay feature.

object

Watermark (logo) branding configuration.

Show Watermark properties

string

required

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

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.

number

default:"20"

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

number

default:"100"

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

object

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

Show Text properties

string

required

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

string

default:"#FFFFFF"

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

string

default:"Inter"

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

number

default:"100"

Transparency level of the text (0-100).

number

default:"20"

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

string

default:"center"

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

Scene Duration Overrides

For fine-tuned control over video pacing, you can override the default scene durations.

number

Minimum duration for each scene in seconds. Range: 1-30.

number

Maximum duration for each scene in seconds. Range: 1-30.

Artistic Mode Duration Overrides

When using orchestration_mode: "artistic", you can separately control hero and secondary scene durations.

number

Minimum duration for hero (primary) scenes in seconds. Range: 1-30.

number

Maximum duration for hero (primary) scenes in seconds. Range: 1-30.

number

Minimum duration for secondary scenes in seconds. Range: 1-30.

number

Maximum duration for secondary scenes in seconds. Range: 1-30.

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.

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

string

required

Unique identifier for the task. Use this to check status.

string

required

Initial task status. Always queued for new tasks.

integer

Position in the processing queue.

string

Estimated completion time (ISO 8601 format).

string

required

Task creation timestamp (ISO 8601 format).

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.

curl -X POST https://api.vibepeak.ai/v1/real-estate/narrated-slideshow \
  -H "Authorization: Bearer vpk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "images": [
      "https://example.com/property/living-room.jpg",
      "https://example.com/property/kitchen.jpg",
      "https://example.com/property/bedroom.jpg",
      "https://example.com/property/bathroom.jpg",
      "https://example.com/property/backyard.jpg",
      "https://example.com/property/exterior.jpg"
    ],
    "voice": {
      "voice_id": "EXAVITQu4vr4xnSDxMaL",
      "language": "en"
    },
    "orientation": "portrait",
    "script": "Welcome to this stunning 3-bedroom home in the heart of the city. The open-concept living area floods with natural light...",
    "orchestration_mode": "standard",
    "webhook_url": "https://yourserver.com/webhooks/vibepeak",
    "background_music": true,
    "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"
      }
    }
  }'

const response = await fetch('https://api.vibepeak.ai/v1/real-estate/narrated-slideshow', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vpk_live_xxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    images: [
      'https://example.com/property/living-room.jpg',
      'https://example.com/property/kitchen.jpg',
      'https://example.com/property/bedroom.jpg',
      'https://example.com/property/bathroom.jpg',
      'https://example.com/property/backyard.jpg',
      'https://example.com/property/exterior.jpg'
    ],
    voice: {
      voice_id: 'EXAVITQu4vr4xnSDxMaL',
      language: 'en'
    },
    orientation: 'portrait',
    script: 'Welcome to this stunning 3-bedroom home...',
    orchestration_mode: 'standard',
    webhook_url: 'https://yourserver.com/webhooks/vibepeak',
    background_music: true,
    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'
      }
    }
  })
});

const task = await response.json();
console.log(`Task created: ${task.task_id}`);

import requests

response = requests.post(
    'https://api.vibepeak.ai/v1/real-estate/narrated-slideshow',
    headers={
        'Authorization': 'Bearer vpk_live_xxxxx',
        'Content-Type': 'application/json'
    },
    json={
        'images': [
            'https://example.com/property/living-room.jpg',
            'https://example.com/property/kitchen.jpg',
            'https://example.com/property/bedroom.jpg',
            'https://example.com/property/bathroom.jpg',
            'https://example.com/property/backyard.jpg',
            'https://example.com/property/exterior.jpg'
        ],
        'voice': {
            'voice_id': 'EXAVITQu4vr4xnSDxMaL',
            'language': 'en'
        },
        'orientation': 'portrait',
        'script': 'Welcome to this stunning 3-bedroom home...',
        'orchestration_mode': 'standard',
        'webhook_url': 'https://yourserver.com/webhooks/vibepeak',
        'background_music': True,
        '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 = response.json()
print(f"Task created: {task['task_id']}")

Example: images with camera motion

To apply subtle per-image camera moves, pass images as an array of objects with reanimate: true and a movement value (or null to let VibePeak pick one). Remember you cannot mix strings and objects in the same array.

curl -X POST https://api.vibepeak.ai/v1/real-estate/narrated-slideshow \
  -H "Authorization: Bearer vpk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "images": [
      { "image_url": "https://example.com/property/living-room.jpg", "reanimate": true, "movement": "dolly_in", "room_type": "living room" },
      { "image_url": "https://example.com/property/kitchen.jpg", "reanimate": true, "movement": "traveling_left" },
      { "image_url": "https://example.com/property/bedroom.jpg", "reanimate": true, "movement": null },
      { "image_url": "https://example.com/property/bathroom.jpg", "reanimate": false },
      { "image_url": "https://example.com/property/backyard.jpg", "reanimate": true, "movement": "traveling_up" },
      { "image_url": "https://example.com/property/exterior.jpg", "reanimate": true, "movement": "dolly_out" }
    ],
    "voice": {
      "voice_id": "EXAVITQu4vr4xnSDxMaL",
      "language": "en"
    },
    "script": "Welcome to this stunning 3-bedroom home in the heart of the city. The open-concept living area floods with natural light..."
  }'

const response = await fetch('https://api.vibepeak.ai/v1/real-estate/narrated-slideshow', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vpk_live_xxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    images: [
      { image_url: 'https://example.com/property/living-room.jpg', reanimate: true, movement: 'dolly_in', room_type: 'living room' },
      { image_url: 'https://example.com/property/kitchen.jpg', reanimate: true, movement: 'traveling_left' },
      { image_url: 'https://example.com/property/bedroom.jpg', reanimate: true, movement: null },
      { image_url: 'https://example.com/property/bathroom.jpg', reanimate: false },
      { image_url: 'https://example.com/property/backyard.jpg', reanimate: true, movement: 'traveling_up' },
      { image_url: 'https://example.com/property/exterior.jpg', reanimate: true, movement: 'dolly_out' }
    ],
    voice: {
      voice_id: 'EXAVITQu4vr4xnSDxMaL',
      language: 'en'
    },
    script: 'Welcome to this stunning 3-bedroom home...'
  })
});

const task = await response.json();
console.log(`Task created: ${task.task_id}`);

import requests

response = requests.post(
    'https://api.vibepeak.ai/v1/real-estate/narrated-slideshow',
    headers={
        'Authorization': 'Bearer vpk_live_xxxxx',
        'Content-Type': 'application/json'
    },
    json={
        'images': [
            {'image_url': 'https://example.com/property/living-room.jpg', 'reanimate': True, 'movement': 'dolly_in', 'room_type': 'living room'},
            {'image_url': 'https://example.com/property/kitchen.jpg', 'reanimate': True, 'movement': 'traveling_left'},
            {'image_url': 'https://example.com/property/bedroom.jpg', 'reanimate': True, 'movement': None},
            {'image_url': 'https://example.com/property/bathroom.jpg', 'reanimate': False},
            {'image_url': 'https://example.com/property/backyard.jpg', 'reanimate': True, 'movement': 'traveling_up'},
            {'image_url': 'https://example.com/property/exterior.jpg', 'reanimate': True, 'movement': 'dolly_out'}
        ],
        'voice': {
            'voice_id': 'EXAVITQu4vr4xnSDxMaL',
            'language': 'en'
        },
        'script': 'Welcome to this stunning 3-bedroom home...'
    }
)

task = response.json()
print(f"Task created: {task['task_id']}")

{
  "task_id": "task_abc123xyz",
  "status": "queued",
  "queue_position": 3,
  "estimated_completion": "2026-01-04T12:30:00Z",
  "created_at": "2026-01-04T12:00:00Z",
  "livemode": true
}

{
  "task_id": "task_abc123xyz",
  "status": "queued",
  "message": "Video generation request accepted",
  "created_at": "2026-01-04T12:00:00Z",
  "livemode": false,
  "request_id": "req_xyz123",
  "_links": {
    "self": "/v1/tasks/task_abc123xyz",
    "poll_interval_seconds": 30
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "images must contain between 6 and 15 URLs",
    "request_id": "req_xyz123"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Provide either 'subtitle_style_preset' or 'styles', but not both.",
    "request_id": "req_xyz123"
  }
}

{
  "error": {
    "code": "SCRIPT_TOO_SHORT",
    "message": "Script is too short for 6 images. Minimum 240 characters required (40 per image), but got 100.",
    "request_id": "req_xyz123",
    "details": {
      "script_length": 100,
      "min_length": 240,
      "max_length": 300,
      "image_count": 6
    }
  }
}

{
  "error": {
    "code": "SCRIPT_TOO_LONG",
    "message": "Script is too long for 6 images. Maximum 300 characters allowed (50 per image), but got 500.",
    "request_id": "req_xyz123",
    "details": {
      "script_length": 500,
      "min_length": 240,
      "max_length": 300,
      "image_count": 6
    }
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "If elements_config is enabled, you must provide at least a 'watermark' or 'text' configuration.",
    "request_id": "req_xyz123",
    "details": {
      "path": ["elements_config", "enabled"]
    }
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid hex color",
    "request_id": "req_xyz123",
    "details": {
      "path": ["elements_config", "text", "color"]
    }
  }
}

{
  "error": {
    "code": "SCRIPT_INVALID_CHARACTERS",
    "message": "Script contains characters not supported by text-to-speech: \"🏠\". Emojis and other non-speech symbols are not allowed.",
    "request_id": "req_xyz123",
    "details": {
      "invalid_characters": ["3", "2"]
    }
  }
}

{
  "error": {
    "code": "CONCURRENCY_LIMIT_EXCEEDED",
    "message": "You have reached your concurrent task limit of 1. Please wait for existing tasks to complete.",
    "request_id": "req_xyz123",
    "details": {
      "limit": 1,
      "in_flight": 1,
      "plan": "Plus"
    }
  }
}

Error Codes

Code	Status	Description
`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
`SCRIPT_TOO_SHORT`	400	Script is too short for the number of images (min 40 chars/image)
`SCRIPT_TOO_LONG`	400	Script is too long for the number of images (max 50 chars/image)
`SCRIPT_INVALID_CHARACTERS`	400	Script contains emojis or other non-speech characters not supported by TTS
`INVALID_API_KEY`	401	Invalid or missing API key
`PLAN_REQUIRED`	403	Plan doesn’t include API access
`CONCURRENCY_LIMIT_EXCEEDED`	429	Concurrent task limit reached
`SERVICE_UNAVAILABLE`	503	Video generation service temporarily unavailable
`SERVICE_TIMEOUT`	504	Service request timed out

See Error Handling for more details.

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

Overview

Avatars

Voices

Videos

Create Narrated Slideshow

Request Body

Scene Duration Overrides

Artistic Mode Duration Overrides

Test Mode

Response

Example: images with camera motion

Error Codes

Next Steps

​Request Body

​Scene Duration Overrides

​Artistic Mode Duration Overrides

​Test Mode

​Response

​Example: images with camera motion

​Error Codes

​Next Steps

Request Body

Scene Duration Overrides

Artistic Mode Duration Overrides

Test Mode

Response

Example: images with camera motion

Error Codes

Next Steps