API Best Practices

Best Practices

Video Preparation

For optimal results, follow these guidelines when preparing your videos:

  1. Video Quality:

    • Resolution: 720p (1280×720) or 1080p (1920×1080) recommended.
    • Frame rate: 24-30fps recommended.
    • Duration: Keep under 10 minutes for optimal processing time. Longer videos may take significantly more time.

  2. Recording Environment:

    • Good lighting: Ensure the subject is well-lit, with even lighting. Avoid strong backlighting or shadows on the face.
    • Clear audio: Use a quality microphone to minimize background noise. Clear audio is crucial for accurate speech processing and lip-sync.
    • Plain background: A simple, non-distracting background works best, especially if background blur is not used.

  3. Performance Tips:

    • Look directly at the camera as much as possible for better eye contact enhancement.
    • Speak clearly and at a consistent, natural pace.
    • Maintain a relatively steady head position to improve lip-sync results. Avoid excessive or rapid head movements.
    • Ensure the primary speaker is clearly visible and in focus.

API Usage

  1. Polling Strategy:

    • Implement exponential backoff when polling the status endpoint (/status/{video_id}).
    • Start with reasonable intervals (e.g., 10-15 seconds), gradually increasing the delay for subsequent polls to avoid overwhelming the API.
    • Include a maximum number of attempts or a total timeout for polling very long jobs to prevent indefinite polling.

  2. Error Handling:

    • As detailed in the Error Handling section, validate input parameters before submission.
    • Implement proper retry logic for transient errors (e.g., 429, 500, 503).
    • Store video_id values persistently in your application in case it needs to restart and resume polling.

  3. Security:

    • Never embed API keys directly in client-side code (e.g., JavaScript running in a browser, mobile apps). API calls should be made from a secure backend server where the key can be protected.
    • Store your API key securely, for example, as an environment variable or using a secrets management service.
    • Rotate API keys periodically if your security policy requires it.
    • Consider restricting API key usage to specific IP addresses if your infrastructure allows and our platform supports it (check your developer dashboard for options).
    • Monitor your API usage for any unusual activity that might indicate a compromised key.

  4. Efficiency:

    • Only request the features you need. For example, if you do not require background blur, set blur_background=false.
    • Avoid submitting duplicate video processing requests for the same source video unless necessary.