Skip to main content

​
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

1

Submit Request

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

Task Queued

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

Processing

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

Completion

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

​
Task Lifecycle

Tasks progress through the following statuses:
StatusDescription
queuedTask is waiting in the processing queue
processingVideo generation is in progress
completedVideo is ready for download
failedAn error occurred during processing

​
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"
    ]
  }'

​
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"

​
Response Headers

When creating a task, the API returns helpful headers for async workflows:
HeaderDescription
LocationURL to poll for task status (e.g., /v1/tasks/task_abc123)
Retry-AfterRecommended 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:
  1. Download the video to your own storage, or
  2. 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.