Best Practices

Tips for getting optimal results from the VAD API.

Video Quality

For best results, ensure your videos have:

Clear faces - Faces should be visible and not obscured
Good lighting - Avoid dark or overexposed footage
Stable camera - Excessive motion can affect detection
Adequate resolution - At least 480p recommended

Efficient Polling

When polling for results, use exponential backoff to avoid overwhelming the API:

JavaScript

async function pollForResult(taskId, maxAttempts = 60) {
  let delay = 2000; // Start with 2 seconds

  for (let i = 0; i < maxAttempts; i++) {
    const result = await fetch(`/api/vad/result/${taskId}`, {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }).then(r => r.json());

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

    await new Promise(r => setTimeout(r, delay));
    delay = Math.min(delay * 1.5, 10000); // Max 10 seconds
  }

  throw new Error('Polling timeout');
}

Video Hosting

The video_url must be publicly accessible. Good options include:

Cloud storage (S3, GCS, Azure Blob) with public URLs or signed URLs
CDN-hosted videos
Direct video file URLs (not streaming platforms)

Note: YouTube, Vimeo, and similar streaming URLs are not supported. Use direct file URLs instead.

Error Handling

Always handle potential errors gracefully:

JavaScript

try {
  const submitRes = await fetch('/api/vad/analyze', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ video_url })
  });

  if (!submitRes.ok) {
    const error = await submitRes.json();
    throw new Error(error.error || 'Submit failed');
  }

  const { task_id } = await submitRes.json();
  // Continue with polling...

} catch (error) {
  console.error('VAD analysis failed:', error.message);
  // Handle error appropriately
}

Cost Optimization

Trim videos - Only submit the relevant portions
Cache results - Store results to avoid re-processing
Monitor usage - Check your dashboard for credit consumption