Get Task Status

curl https://api.vibepeak.ai/v1/tasks/task_abc123xyz \
  -H "Authorization: Bearer vpk_live_xxxxx"

const response = await fetch('https://api.vibepeak.ai/v1/tasks/task_abc123xyz', {
  headers: {
    'Authorization': 'Bearer vpk_live_xxxxx'
  }
});

const task = await response.json();
console.log(`Status: ${task.status}`);

if (task.status === 'completed') {
  console.log(`Video URL: ${task.result.video_url}`);
  console.log(`Cover Image: ${task.result.cover_image_url}`);
}

import requests

response = requests.get(
    'https://api.vibepeak.ai/v1/tasks/task_abc123xyz',
    headers={
        'Authorization': 'Bearer vpk_live_xxxxx'
    }
)

task = response.json()
print(f"Status: {task['status']}")

if task['status'] == 'completed':
    print(f"Video URL: {task['result']['video_url']}")
    print(f"Cover Image: {task['result']['cover_image_url']}")

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

{
  "task_id": "task_abc123xyz",
  "status": "processing",
  "created_at": "2026-01-04T12:00:00Z",
  "started_at": "2026-01-04T12:05:00Z"
}

{
  "task_id": "task_abc123xyz",
  "status": "completed",
  "created_at": "2026-01-04T12:00:00Z",
  "started_at": "2026-01-04T12:05:00Z",
  "completed_at": "2026-01-04T12:15:00Z",
  "livemode": true,
  "result": {
    "video_url": "https://storage.vibepeak.ai/videos/task_abc123xyz.mp4",
    "cover_image_url": "https://storage.googleapis.com/vibepeak-audio/covers/task_abc123xyz.jpg",
    "duration_seconds": 45,
    "resolution": "1080p",
    "expires_at": "2026-01-11T12:15:00Z"
  }
}

{
  "task_id": "task_abc123xyz",
  "status": "completed",
  "created_at": "2026-01-04T12:00:00Z",
  "started_at": "2026-01-04T12:05:00Z",
  "completed_at": "2026-01-04T12:15:00Z",
  "livemode": true,
  "result": {
    "video_url": "https://storage.vibepeak.ai/videos/task_abc123xyz.mp4",
    "cover_image_url": "https://storage.googleapis.com/vibepeak-audio/covers/task_abc123xyz.jpg",
    "duration_seconds": 45,
    "intro_outro_warning": "Intro/outro overlay failed: Scene boundaries first_scene_ms and last_scene_ms were not reported by the video engine, so the overlay cannot be timed. Video delivered without the overlay."
  }
}

{
  "task_id": "task_story789xyz",
  "status": "completed",
  "created_at": "2026-07-15T09:00:00Z",
  "started_at": "2026-07-15T09:00:10Z",
  "completed_at": "2026-07-15T09:12:40Z",
  "livemode": true,
  "result": {
    "video_url": "https://storage.vibepeak.ai/videos/task_story789xyz.mp4",
    "cover_image_url": "https://storage.googleapis.com/vibepeak-audio/covers/task_story789xyz.jpg",
    "duration_seconds": 32,
    "resolution": "1080p",
    "expires_at": "2026-07-22T09:12:40Z",
    "story": {
      "arc": "morning_to_night",
      "locale": "en",
      "scenes": [
        {
          "order": 0,
          "room": "bedroom",
          "time_of_day": "morning",
          "members_present": [0, 2],
          "activity": "The mother wakes the youngest child as soft sunlight fills the room",
          "transition_to_next": "follow"
        },
        {
          "order": 1,
          "room": "kitchen",
          "time_of_day": "morning",
          "members_present": [0, 1, 2],
          "activity": "The family shares breakfast together at the counter",
          "transition_to_next": "cut"
        },
        {
          "order": 2,
          "room": "exterior",
          "time_of_day": "afternoon",
          "members_present": [],
          "activity": "The facade glows in the warm afternoon light",
          "transition_to_next": "fade"
        },
        {
          "order": 3,
          "room": "garden",
          "time_of_day": "afternoon",
          "members_present": [1, 2],
          "activity": "The father and child play outside in the warm afternoon light",
          "transition_to_next": "match"
        },
        {
          "order": 4,
          "room": "living_room",
          "time_of_day": "night",
          "members_present": [0, 1, 2],
          "activity": "The family winds down together on the sofa under warm evening lamps",
          "transition_to_next": "close"
        }
      ]
    }
  }
}

{
  "task_id": "task_venue123xyz",
  "status": "completed",
  "created_at": "2026-09-24T09:00:00Z",
  "started_at": "2026-09-24T09:00:10Z",
  "completed_at": "2026-09-24T09:10:40Z",
  "livemode": true,
  "result": {
    "video_url": "https://storage.vibepeak.ai/videos/task_venue123xyz.mp4",
    "cover_image_url": "https://storage.googleapis.com/vibepeak-audio/covers/task_venue123xyz.jpg",
    "duration_seconds": 30,
    "resolution": "1080p",
    "expires_at": "2026-10-01T09:10:40Z",
    "space_uses": [
      { "image_index": 0, "space_use": "cocktail-bar", "space_tag": "customer_area" },
      { "image_index": 1, "space_use": "cocktail-bar", "space_tag": "customer_area" },
      { "image_index": 2, "space_use": "cocktail-bar", "space_tag": "facade_exterior" },
      { "image_index": 3, "space_use": "cocktail-bar", "space_tag": "bathroom" },
      { "image_index": 4, "space_use": "cocktail-bar", "space_tag": "customer_area" },
      { "image_index": 5, "space_use": "clothing-store", "space_tag": "customer_area" }
    ]
  }
}

{
  "task_id": "task_fam456xyz",
  "status": "completed",
  "created_at": "2026-07-09T10:00:00Z",
  "started_at": "2026-07-09T10:00:05Z",
  "completed_at": "2026-07-09T10:02:30Z",
  "livemode": true,
  "result": {
    "family_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "reference_image_urls": [
      "https://media.vibepeak.ai/families/garcia-family-mother.jpg",
      "https://media.vibepeak.ai/families/garcia-family-father.jpg",
      "https://media.vibepeak.ai/families/garcia-family-daughter.jpg"
    ],
    "card_image_url": "https://media.vibepeak.ai/families/garcia-family-card.jpg"
  }
}

{
  "task_id": "task_abc123xyz",
  "status": "completed",
  "created_at": "2026-01-04T12:00:00Z",
  "started_at": "2026-01-04T12:00:05Z",
  "completed_at": "2026-01-04T12:00:05Z",
  "livemode": false,
  "result": {
    "video_url": "https://storage.vibepeak.ai/samples/sample-landscape.mp4",
    "cover_image_url": "https://storage.vibepeak.ai/samples/sample-cover.jpg",
    "duration_seconds": 12,
    "total_scenes": 3
  }
}

{
  "task_id": "task_abc123xyz",
  "status": "failed",
  "created_at": "2026-01-04T12:00:00Z",
  "started_at": "2026-01-04T12:05:00Z",
  "completed_at": "2026-01-04T12:06:00Z",
  "error": {
    "code": "IMAGE_PROCESSING_FAILED",
    "message": "Failed to process image at index 2: Invalid image format"
  }
}

{
  "error": {
    "code": "TASK_NOT_FOUND",
    "message": "Task not found.",
    "request_id": "req_xyz123"
  }
}

GET

tasks

{taskId}

curl https://api.vibepeak.ai/v1/tasks/task_abc123xyz \
  -H "Authorization: Bearer vpk_live_xxxxx"

const response = await fetch('https://api.vibepeak.ai/v1/tasks/task_abc123xyz', {
  headers: {
    'Authorization': 'Bearer vpk_live_xxxxx'
  }
});

const task = await response.json();
console.log(`Status: ${task.status}`);

if (task.status === 'completed') {
  console.log(`Video URL: ${task.result.video_url}`);
  console.log(`Cover Image: ${task.result.cover_image_url}`);
}

import requests

response = requests.get(
    'https://api.vibepeak.ai/v1/tasks/task_abc123xyz',
    headers={
        'Authorization': 'Bearer vpk_live_xxxxx'
    }
)

task = response.json()
print(f"Status: {task['status']}")

if task['status'] == 'completed':
    print(f"Video URL: {task['result']['video_url']}")
    print(f"Cover Image: {task['result']['cover_image_url']}")

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

{
  "task_id": "task_abc123xyz",
  "status": "processing",
  "created_at": "2026-01-04T12:00:00Z",
  "started_at": "2026-01-04T12:05:00Z"
}

{
  "task_id": "task_abc123xyz",
  "status": "completed",
  "created_at": "2026-01-04T12:00:00Z",
  "started_at": "2026-01-04T12:05:00Z",
  "completed_at": "2026-01-04T12:15:00Z",
  "livemode": true,
  "result": {
    "video_url": "https://storage.vibepeak.ai/videos/task_abc123xyz.mp4",
    "cover_image_url": "https://storage.googleapis.com/vibepeak-audio/covers/task_abc123xyz.jpg",
    "duration_seconds": 45,
    "resolution": "1080p",
    "expires_at": "2026-01-11T12:15:00Z"
  }
}

{
  "task_id": "task_abc123xyz",
  "status": "completed",
  "created_at": "2026-01-04T12:00:00Z",
  "started_at": "2026-01-04T12:05:00Z",
  "completed_at": "2026-01-04T12:15:00Z",
  "livemode": true,
  "result": {
    "video_url": "https://storage.vibepeak.ai/videos/task_abc123xyz.mp4",
    "cover_image_url": "https://storage.googleapis.com/vibepeak-audio/covers/task_abc123xyz.jpg",
    "duration_seconds": 45,
    "intro_outro_warning": "Intro/outro overlay failed: Scene boundaries first_scene_ms and last_scene_ms were not reported by the video engine, so the overlay cannot be timed. Video delivered without the overlay."
  }
}

{
  "task_id": "task_story789xyz",
  "status": "completed",
  "created_at": "2026-07-15T09:00:00Z",
  "started_at": "2026-07-15T09:00:10Z",
  "completed_at": "2026-07-15T09:12:40Z",
  "livemode": true,
  "result": {
    "video_url": "https://storage.vibepeak.ai/videos/task_story789xyz.mp4",
    "cover_image_url": "https://storage.googleapis.com/vibepeak-audio/covers/task_story789xyz.jpg",
    "duration_seconds": 32,
    "resolution": "1080p",
    "expires_at": "2026-07-22T09:12:40Z",
    "story": {
      "arc": "morning_to_night",
      "locale": "en",
      "scenes": [
        {
          "order": 0,
          "room": "bedroom",
          "time_of_day": "morning",
          "members_present": [0, 2],
          "activity": "The mother wakes the youngest child as soft sunlight fills the room",
          "transition_to_next": "follow"
        },
        {
          "order": 1,
          "room": "kitchen",
          "time_of_day": "morning",
          "members_present": [0, 1, 2],
          "activity": "The family shares breakfast together at the counter",
          "transition_to_next": "cut"
        },
        {
          "order": 2,
          "room": "exterior",
          "time_of_day": "afternoon",
          "members_present": [],
          "activity": "The facade glows in the warm afternoon light",
          "transition_to_next": "fade"
        },
        {
          "order": 3,
          "room": "garden",
          "time_of_day": "afternoon",
          "members_present": [1, 2],
          "activity": "The father and child play outside in the warm afternoon light",
          "transition_to_next": "match"
        },
        {
          "order": 4,
          "room": "living_room",
          "time_of_day": "night",
          "members_present": [0, 1, 2],
          "activity": "The family winds down together on the sofa under warm evening lamps",
          "transition_to_next": "close"
        }
      ]
    }
  }
}

{
  "task_id": "task_venue123xyz",
  "status": "completed",
  "created_at": "2026-09-24T09:00:00Z",
  "started_at": "2026-09-24T09:00:10Z",
  "completed_at": "2026-09-24T09:10:40Z",
  "livemode": true,
  "result": {
    "video_url": "https://storage.vibepeak.ai/videos/task_venue123xyz.mp4",
    "cover_image_url": "https://storage.googleapis.com/vibepeak-audio/covers/task_venue123xyz.jpg",
    "duration_seconds": 30,
    "resolution": "1080p",
    "expires_at": "2026-10-01T09:10:40Z",
    "space_uses": [
      { "image_index": 0, "space_use": "cocktail-bar", "space_tag": "customer_area" },
      { "image_index": 1, "space_use": "cocktail-bar", "space_tag": "customer_area" },
      { "image_index": 2, "space_use": "cocktail-bar", "space_tag": "facade_exterior" },
      { "image_index": 3, "space_use": "cocktail-bar", "space_tag": "bathroom" },
      { "image_index": 4, "space_use": "cocktail-bar", "space_tag": "customer_area" },
      { "image_index": 5, "space_use": "clothing-store", "space_tag": "customer_area" }
    ]
  }
}

{
  "task_id": "task_fam456xyz",
  "status": "completed",
  "created_at": "2026-07-09T10:00:00Z",
  "started_at": "2026-07-09T10:00:05Z",
  "completed_at": "2026-07-09T10:02:30Z",
  "livemode": true,
  "result": {
    "family_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "reference_image_urls": [
      "https://media.vibepeak.ai/families/garcia-family-mother.jpg",
      "https://media.vibepeak.ai/families/garcia-family-father.jpg",
      "https://media.vibepeak.ai/families/garcia-family-daughter.jpg"
    ],
    "card_image_url": "https://media.vibepeak.ai/families/garcia-family-card.jpg"
  }
}

{
  "task_id": "task_abc123xyz",
  "status": "completed",
  "created_at": "2026-01-04T12:00:00Z",
  "started_at": "2026-01-04T12:00:05Z",
  "completed_at": "2026-01-04T12:00:05Z",
  "livemode": false,
  "result": {
    "video_url": "https://storage.vibepeak.ai/samples/sample-landscape.mp4",
    "cover_image_url": "https://storage.vibepeak.ai/samples/sample-cover.jpg",
    "duration_seconds": 12,
    "total_scenes": 3
  }
}

{
  "task_id": "task_abc123xyz",
  "status": "failed",
  "created_at": "2026-01-04T12:00:00Z",
  "started_at": "2026-01-04T12:05:00Z",
  "completed_at": "2026-01-04T12:06:00Z",
  "error": {
    "code": "IMAGE_PROCESSING_FAILED",
    "message": "Failed to process image at index 2: Invalid image format"
  }
}

{
  "error": {
    "code": "TASK_NOT_FOUND",
    "message": "Task not found.",
    "request_id": "req_xyz123"
  }
}

Retrieves the current status of an asynchronous task. This includes video generation tasks as well as family avatar generation tasks created by Create Family. Poll this endpoint to check when a task is ready.

Path Parameters

string

required

The unique identifier of the task, returned when creating a slideshow.Example: task_abc123xyz

Response

The response varies based on the task status:

Common Fields

string

required

Unique identifier for the task.

string

required

Current task status: queued, processing, completed, or failed.Land tasks start one step earlier, in preparing, while the server resolves the request’s inputs.Tasks that requested post-processing can also report a transitional status while the finished video is being refined, in this order: watermarking (watermark or text overlay), intro_outro (intro/outro overlays), subtitling (subtitles). Treat all of these like processing and keep polling; the task always ends in completed or failed.

string

required

Task creation timestamp (ISO 8601 format).

boolean

required

true for tasks created with a live (vpk_live_) key; false for test-mode (vpk_test_) sandbox tasks.

Test and live tasks are isolated: a vpk_test_ key can only read test tasks and a vpk_live_ key can only read live tasks. Reading a task created with the other key type returns the same 404 TASK_NOT_FOUND as a missing task. See Test Mode.

Queued Status

integer

Position in the processing queue.

string

Estimated completion time (ISO 8601 format).

Processing Status

string

When processing began (ISO 8601 format).

Completed Status

string

When processing finished (ISO 8601 format).

object

The task result. Its shape depends on what created the task.

Show Result properties (video generation task)

string

URL to download the generated video.

string

URL to the cover image (first frame of the video). Use this as a thumbnail or preview for the video.

integer

Video duration in seconds.

string

Video resolution (e.g., “1080p”).

string

When the video URL expires (ISO 8601 format). URLs expire after 7 days.

string

Present when the watermark or text overlay could not be applied. The video was delivered without it; the task still counts as completed.

string

Present when the requested intro/outro overlays could not be applied, for example when the video engine did not report the scene boundaries needed to time them. The video was delivered without the overlays; the task still counts as completed.

string

Present when subtitles could not be applied. The video was delivered without them; the task still counts as completed.

object

Present only on completed videos created with story_mode (see Create Living Property Video). The day-in-the-life plan the AI chose at creation time, including the final scene order. Since Story Mode reorders your images into a morning-to-night arc, use this block to see which image ended up where.

Show Story properties

string

Narrative arc of the video. Always morning_to_night.

string

Language of the scene activities (the request’s story_locale, en by default).

object[]

One entry per scene, in the order they appear in the video:

order (integer): Position of the scene in the video, starting at 0
room (string): Room type of the scene’s image
time_of_day (string or null): morning, midday, afternoon, sunset, or night. May be null for a scene that carries no lighting
members_present (integer[]): Who appears in the scene, as indices into the family’s members array. Empty for people-free scenes
activity (string): What the family is doing in the scene, written in the story locale
transition_to_next (string): Intent label for how the scene hands over to the next one: cut, fade, follow, match, or close

object[]

Present only on a completed living-property video whose request had at least one commercial image (an image with an effective space_use — see Commercial Space Use). One entry per commercial image, ordered by image_index. Absent for a residential-only video. Built at read time from the request, like result.story; never included in webhook payloads.

image_index (integer): 0-based position of the image in the request’s images array
space_use (string): the effective commercial use applied to that image
space_tag (string): the effective space tag applied to that image

Show Result properties (family-avatars task)

Tasks of type family-avatars return this shape instead. They are created by Create Family and by every member operation (Add, Update, Regenerate, Remove), which regenerate a portrait and the group card:

string

Unique identifier of the family whose avatars finished generating.

string[]

Reference image URLs generated for each family member.

string

Preview image showing the full family together.

Failed Status

object

Error details when the task failed.

Show Error properties

string

Machine-readable error code.

string

Human-readable error description.

curl https://api.vibepeak.ai/v1/tasks/task_abc123xyz \
  -H "Authorization: Bearer vpk_live_xxxxx"

const response = await fetch('https://api.vibepeak.ai/v1/tasks/task_abc123xyz', {
  headers: {
    'Authorization': 'Bearer vpk_live_xxxxx'
  }
});

const task = await response.json();
console.log(`Status: ${task.status}`);

if (task.status === 'completed') {
  console.log(`Video URL: ${task.result.video_url}`);
  console.log(`Cover Image: ${task.result.cover_image_url}`);
}

import requests

response = requests.get(
    'https://api.vibepeak.ai/v1/tasks/task_abc123xyz',
    headers={
        'Authorization': 'Bearer vpk_live_xxxxx'
    }
)

task = response.json()
print(f"Status: {task['status']}")

if task['status'] == 'completed':
    print(f"Video URL: {task['result']['video_url']}")
    print(f"Cover Image: {task['result']['cover_image_url']}")

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

{
  "task_id": "task_abc123xyz",
  "status": "processing",
  "created_at": "2026-01-04T12:00:00Z",
  "started_at": "2026-01-04T12:05:00Z"
}

{
  "task_id": "task_abc123xyz",
  "status": "completed",
  "created_at": "2026-01-04T12:00:00Z",
  "started_at": "2026-01-04T12:05:00Z",
  "completed_at": "2026-01-04T12:15:00Z",
  "livemode": true,
  "result": {
    "video_url": "https://storage.vibepeak.ai/videos/task_abc123xyz.mp4",
    "cover_image_url": "https://storage.googleapis.com/vibepeak-audio/covers/task_abc123xyz.jpg",
    "duration_seconds": 45,
    "resolution": "1080p",
    "expires_at": "2026-01-11T12:15:00Z"
  }
}

{
  "task_id": "task_abc123xyz",
  "status": "completed",
  "created_at": "2026-01-04T12:00:00Z",
  "started_at": "2026-01-04T12:05:00Z",
  "completed_at": "2026-01-04T12:15:00Z",
  "livemode": true,
  "result": {
    "video_url": "https://storage.vibepeak.ai/videos/task_abc123xyz.mp4",
    "cover_image_url": "https://storage.googleapis.com/vibepeak-audio/covers/task_abc123xyz.jpg",
    "duration_seconds": 45,
    "intro_outro_warning": "Intro/outro overlay failed: Scene boundaries first_scene_ms and last_scene_ms were not reported by the video engine, so the overlay cannot be timed. Video delivered without the overlay."
  }
}

{
  "task_id": "task_story789xyz",
  "status": "completed",
  "created_at": "2026-07-15T09:00:00Z",
  "started_at": "2026-07-15T09:00:10Z",
  "completed_at": "2026-07-15T09:12:40Z",
  "livemode": true,
  "result": {
    "video_url": "https://storage.vibepeak.ai/videos/task_story789xyz.mp4",
    "cover_image_url": "https://storage.googleapis.com/vibepeak-audio/covers/task_story789xyz.jpg",
    "duration_seconds": 32,
    "resolution": "1080p",
    "expires_at": "2026-07-22T09:12:40Z",
    "story": {
      "arc": "morning_to_night",
      "locale": "en",
      "scenes": [
        {
          "order": 0,
          "room": "bedroom",
          "time_of_day": "morning",
          "members_present": [0, 2],
          "activity": "The mother wakes the youngest child as soft sunlight fills the room",
          "transition_to_next": "follow"
        },
        {
          "order": 1,
          "room": "kitchen",
          "time_of_day": "morning",
          "members_present": [0, 1, 2],
          "activity": "The family shares breakfast together at the counter",
          "transition_to_next": "cut"
        },
        {
          "order": 2,
          "room": "exterior",
          "time_of_day": "afternoon",
          "members_present": [],
          "activity": "The facade glows in the warm afternoon light",
          "transition_to_next": "fade"
        },
        {
          "order": 3,
          "room": "garden",
          "time_of_day": "afternoon",
          "members_present": [1, 2],
          "activity": "The father and child play outside in the warm afternoon light",
          "transition_to_next": "match"
        },
        {
          "order": 4,
          "room": "living_room",
          "time_of_day": "night",
          "members_present": [0, 1, 2],
          "activity": "The family winds down together on the sofa under warm evening lamps",
          "transition_to_next": "close"
        }
      ]
    }
  }
}

{
  "task_id": "task_venue123xyz",
  "status": "completed",
  "created_at": "2026-09-24T09:00:00Z",
  "started_at": "2026-09-24T09:00:10Z",
  "completed_at": "2026-09-24T09:10:40Z",
  "livemode": true,
  "result": {
    "video_url": "https://storage.vibepeak.ai/videos/task_venue123xyz.mp4",
    "cover_image_url": "https://storage.googleapis.com/vibepeak-audio/covers/task_venue123xyz.jpg",
    "duration_seconds": 30,
    "resolution": "1080p",
    "expires_at": "2026-10-01T09:10:40Z",
    "space_uses": [
      { "image_index": 0, "space_use": "cocktail-bar", "space_tag": "customer_area" },
      { "image_index": 1, "space_use": "cocktail-bar", "space_tag": "customer_area" },
      { "image_index": 2, "space_use": "cocktail-bar", "space_tag": "facade_exterior" },
      { "image_index": 3, "space_use": "cocktail-bar", "space_tag": "bathroom" },
      { "image_index": 4, "space_use": "cocktail-bar", "space_tag": "customer_area" },
      { "image_index": 5, "space_use": "clothing-store", "space_tag": "customer_area" }
    ]
  }
}

{
  "task_id": "task_fam456xyz",
  "status": "completed",
  "created_at": "2026-07-09T10:00:00Z",
  "started_at": "2026-07-09T10:00:05Z",
  "completed_at": "2026-07-09T10:02:30Z",
  "livemode": true,
  "result": {
    "family_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "reference_image_urls": [
      "https://media.vibepeak.ai/families/garcia-family-mother.jpg",
      "https://media.vibepeak.ai/families/garcia-family-father.jpg",
      "https://media.vibepeak.ai/families/garcia-family-daughter.jpg"
    ],
    "card_image_url": "https://media.vibepeak.ai/families/garcia-family-card.jpg"
  }
}

{
  "task_id": "task_abc123xyz",
  "status": "completed",
  "created_at": "2026-01-04T12:00:00Z",
  "started_at": "2026-01-04T12:00:05Z",
  "completed_at": "2026-01-04T12:00:05Z",
  "livemode": false,
  "result": {
    "video_url": "https://storage.vibepeak.ai/samples/sample-landscape.mp4",
    "cover_image_url": "https://storage.vibepeak.ai/samples/sample-cover.jpg",
    "duration_seconds": 12,
    "total_scenes": 3
  }
}

{
  "task_id": "task_abc123xyz",
  "status": "failed",
  "created_at": "2026-01-04T12:00:00Z",
  "started_at": "2026-01-04T12:05:00Z",
  "completed_at": "2026-01-04T12:06:00Z",
  "error": {
    "code": "IMAGE_PROCESSING_FAILED",
    "message": "Failed to process image at index 2: Invalid image format"
  }
}

{
  "error": {
    "code": "TASK_NOT_FOUND",
    "message": "Task not found.",
    "request_id": "req_xyz123"
  }
}

Polling Best Practices

Don’t poll too frequently. We recommend polling every 5-15 seconds.

Here’s a recommended polling implementation:

async function waitForCompletion(taskId, apiKey) {
  const maxAttempts = 60;
  const pollInterval = 5000; // 5 seconds

  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const response = await fetch(
      `https://api.vibepeak.ai/v1/tasks/${taskId}`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    );

    const task = await response.json();

    switch (task.status) {
      case 'completed':
        return task.result;
      case 'failed':
        throw new Error(`Task failed: ${task.error.message}`);
      default:
        // queued, processing, or a transitional post-processing status
        // (watermarking, intro_outro, subtitling)
        await new Promise(r => setTimeout(r, pollInterval));
        break;
    }
  }

  throw new Error('Task timed out');
}

// Usage
const result = await waitForCompletion('task_abc123xyz', apiKey);
console.log(`Video ready: ${result.video_url}`);

Error Codes

Code	Status	Description
`TASK_NOT_FOUND`	404	Task doesn’t exist or belongs to another user
`INVALID_API_KEY`	401	Invalid or missing API key

See Error Handling for more details.

Video URL Expiration

Video URLs expire after 7 days. Download or store the video before the expires_at timestamp.

If you need the video after expiration:

Re-request the task status (if the video is still available in storage)
Create a new slideshow with the same images

Overview

Avatars

Voices

Videos

Families

Images

Path Parameters

Response

Common Fields

Queued Status

Processing Status

Completed Status

Failed Status

Polling Best Practices

Error Codes

Video URL Expiration

​Path Parameters

​Response

​Common Fields

​Queued Status

​Processing Status

​Completed Status

​Failed Status

​Polling Best Practices

​Error Codes

​Video URL Expiration

Path Parameters

Response

Common Fields

Queued Status

Processing Status

Completed Status

Failed Status

Polling Best Practices

Error Codes

Video URL Expiration