Asynchronous Processing

Video generation is a computationally intensive process that can take several minutes to complete. The VibePeak API uses an asynchronous task-based architecture to handle this efficiently.

How It Works

Submit Request

Send a POST request to create a slideshow. The API validates your request and returns immediately with a task ID.

Task Queued

Your video generation task is added to the processing queue. You receive a 202 Accepted response with the task details.

Processing

The system processes your images, applies AI enhancements, generates narration, and creates the final video.

Completion

Once complete, you can retrieve the video URL via polling or webhook notification.

This same task model is also used for family avatar generation, started by Create Family. Poll it the same way via Get Task: only the result shape differs.

Task Lifecycle

Tasks progress through the following statuses:

Status	Description
`queued`	Task is waiting in the processing queue
`processing`	Video generation is in progress
`watermarking`	Video complete, watermark or text overlay being applied (only when requested)
`intro_outro`	Video complete, intro/outro overlays being applied (only when requested)
`subtitling`	Video complete, subtitles being applied (only when requested)
`completed`	Video is ready for download
`failed`	An error occurred during processing

The three post-processing statuses appear only for tasks that requested the corresponding feature, in the order watermarking, intro_outro, subtitling. Treat them like processing and keep polling. If a post-processing step cannot finish, the task still completes with the video it already has and the result carries a matching warning field (watermark_warning, intro_outro_warning, or subtitle_warning).

Some endpoints apply these refinements inside the main render instead of as separate steps. On those tasks the corresponding status never appears even when the feature was requested.

* Optional: watermarking, intro_outro, and/or subtitling, skipped entirely when no post-processing was requested.

Submitting a Task

When you create a slideshow, you’ll receive an immediate response:

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/living-room.jpg",
      "https://example.com/kitchen.jpg",
      "https://example.com/bedroom.jpg",
      "https://example.com/bathroom.jpg",
      "https://example.com/backyard.jpg"
    ]
  }'

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

Polling for Status

Check the task status by polling the tasks endpoint:

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

{
  "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",
  "result": {
    "video_url": "https://storage.vibepeak.ai/videos/task_abc123xyz.mp4",
    "duration_seconds": 45,
    "resolution": "1080p",
    "expires_at": "2026-01-11T12:15:00Z"
  }
}

Response Headers

When creating a task, the API returns helpful headers for async workflows:

Header	Description
`Location`	URL to poll for task status (e.g., `/v1/tasks/task_abc123`)
`Retry-After`	Recommended polling interval in seconds (default: 30)

HTTP/1.1 202 Accepted
Location: /v1/tasks/task_abc123xyz
Retry-After: 30
Content-Type: application/json

Polling Best Practices

Video generation typically takes 4-10 minutes. Polling too frequently wastes resources and may trigger rate limiting.

The API returns a Retry-After: 30 header - we recommend polling every 30 seconds for video generation tasks.

We recommend the following polling strategy:

async function waitForCompletion(taskId, apiKey) {
  const maxAttempts = 40; // 40 attempts × 30 seconds = 20 minutes max
  const pollInterval = 30000; // 30 seconds (matches Retry-After header)

  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();

    if (task.status === 'completed') {
      return task.result;
    }

    if (task.status === 'failed') {
      throw new Error(task.error.message);
    }

    // Wait before next poll (use Retry-After header if available)
    const retryAfter = response.headers.get('Retry-After');
    const waitTime = retryAfter ? parseInt(retryAfter) * 1000 : pollInterval;
    await new Promise(resolve => setTimeout(resolve, waitTime));
  }

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

Recommended intervals:

Default: Poll every 30 seconds (matches Retry-After header)
Video generation typically completes in 4-10 minutes
Maximum wait: 20 minutes before timing out

Using Webhooks Instead

For production applications, we recommend using webhooks instead of polling. Webhooks provide:

Real-time notifications - No delay between completion and notification
Reduced API calls - No need for repeated polling requests
Better scalability - Handle more concurrent tasks efficiently

{
  "images": ["..."],
  "webhook_url": "https://yourserver.com/webhooks/vibepeak"
}

Video URL Expiration

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

The expires_at field in the task result indicates when the video URL will become invalid. Make sure to:

Download the video to your own storage, or
Re-request the task status to get a fresh URL (if the video is still available)

Handling Failures

If a task fails, the response will include error details:

{
  "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"
  }
}

Common failure reasons:

Invalid or inaccessible image URLs
Unsupported image formats
Images too small or corrupted
Internal processing errors

For failed tasks, review the error message, fix the issue, and submit a new request.

Getting Started

Core Concepts

Async Processing

Asynchronous Processing

How It Works

Task Lifecycle

Submitting a Task

Polling for Status

Response Headers

Polling Best Practices

Using Webhooks Instead

Video URL Expiration

Handling Failures

​Asynchronous Processing

​How It Works

​Task Lifecycle

​Submitting a Task

​Polling for Status

​Response Headers

​Polling Best Practices

​Using Webhooks Instead

​Video URL Expiration

​Handling Failures

Asynchronous Processing

How It Works

Task Lifecycle

Submitting a Task

Polling for Status

Response Headers

Polling Best Practices

Using Webhooks Instead

Video URL Expiration

Handling Failures