Skip to main content
POST
/
v1
/
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"
    },
    "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
  }'

{
  "task_id": "task_abc123xyz",
  "status": "queued",
  "queue_position": 3,
  "estimated_completion": "2026-01-04T12:30:00Z",
  "created_at": "2026-01-04T12:00:00Z"
}
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

​
images
string[]
required
Array of image URLs for the slideshow. Must contain 6 to 15 images.Images should be:
  • Publicly accessible URLs
  • JPEG, PNG, or WebP format
  • Minimum resolution: 720p recommended
  • All URLs must be unique (no duplicates allowed)
​
voice
object
required
Voice configuration for the AI-generated narration.
​
script
string
required
Narration script for text-to-speech.The script length must be proportional to the number of images to ensure proper narration pacing (~3 seconds per image):
ImagesMin CharactersMax Characters
6240300
10400500
15600750
Formula: min = images × 40, max = images × 50
No numbers or special symbols allowed. The script must contain only letters, spaces, and basic punctuation (. , ! ? ; : ' " -). Numbers must be written as words (e.g., “three” instead of “3”) and symbols like @, #, $, %, &, (, ) are not permitted. This ensures optimal text-to-speech audio quality.
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.
​
orchestration_mode
string
default:"artistic"
Video orchestration mode that controls scene pacing and transitions.
ValueDescription
standardStandard mode with scenes of 3-7 seconds
artisticCinematic mode with 2-3 second scenes and visual weight hierarchy (default)
sequentialImages appear in order without AI reordering. Scene duration is auto-calculated.
​
webhook_url
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).
​
avatar_id
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).
​
background_music
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.

​
Scene Duration Overrides

For fine-tuned control over video pacing, you can override the default scene durations.
​
min_scene_duration_seconds
number
Minimum duration for each scene in seconds. Range: 1-30.
​
max_scene_duration_seconds
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.
​
hero_min_duration_seconds
number
Minimum duration for hero (primary) scenes in seconds. Range: 1-30.
​
hero_max_duration_seconds
number
Maximum duration for hero (primary) scenes in seconds. Range: 1-30.
​
secondary_min_duration_seconds
number
Minimum duration for secondary scenes in seconds. Range: 1-30.
​
secondary_max_duration_seconds
number
Maximum duration for secondary scenes in seconds. Range: 1-30.

​
Response

​
task_id
string
required
Unique identifier for the task. Use this to check status.
​
status
string
required
Initial task status. Always queued for new tasks.
​
queue_position
integer
Position in the processing queue.
​
estimated_completion
string
Estimated completion time (ISO 8601 format).
​
created_at
string
required
Task creation timestamp (ISO 8601 format).
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"
    },
    "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
  }'

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

​
Error Codes

CodeStatusDescription
VALIDATION_ERROR400Invalid request parameters
INVALID_IMAGE_URL400One or more image URLs are inaccessible or invalid
SCRIPT_TOO_SHORT400Script is too short for the number of images (min 40 chars/image)
SCRIPT_TOO_LONG400Script is too long for the number of images (max 50 chars/image)
SCRIPT_INVALID_CHARACTERS400Script contains numbers or special symbols not supported by TTS
INVALID_API_KEY401Invalid or missing API key
PLAN_REQUIRED403Plan doesn’t include API access
CONCURRENCY_LIMIT_EXCEEDED429Concurrent task limit reached
SERVICE_UNAVAILABLE503Video generation service temporarily unavailable
SERVICE_TIMEOUT504Service request timed out
See Error Handling for more details.

​
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