API Flow Guide

This guide explains the complete flow of integrating with the LipDub API. The process involves uploading videos, processing them, and generating dubbed content.

API Flow Overview

Link to API Flow Diagram

Step-by-Step Explanation

1. Video Upload Process

1. Initiate Upload

   • Make a POST request to /v1/video

     NB: Here's the recommended video specifications to get fast results - 1080p HD, 23.976 fps, low bit-rate, H.264 Codec. The generated video will maintain the same quality and video specs as the uploaded video

   • Receive upload_url and video_id

   • The API automatically creates project, scene, and actor

2. Upload Video

   • Make a PUT request to upload your video file to the provided upload_url
   • Call the success_url when complete or call the failure_url if failed
   • Receive a shot_id for tracking
   • To display actor pickers or previews, make a GET request to /v1/shots/{shot_id}/actors to retrieve actors for the shot. Each actor includes thumbnail_url — a short-lived, pre-signed HTTPS URL for that actor’s scene thumbnail.

3. Monitor Processing (optional)

   • Make a GET request to check status using /v1/shots/{shot_id}/status
   • Track both video processing and AI training status

2) Audio Upload Process

1. Initiate Audio Upload

   • Make a POST request to /v1/audio
   • Receive upload_url and audio_id

2. Upload Audio

   • Make a PUT request to upload your audio file to the provided upload_url
   • Call the success_url when complete or call the failure_url if failed

3) Generate LipDub

1. Start Generation

   • Make a POST request to /v1/shots/{shot_id}/generate

     NB: The generated video maintains the same video specs (resolution, frame rate, codec, colorspace, etc.) as the uploaded video. If you upload a 4K video, the output is always 4K. Outputs above HD resolution (1080p) may be more expensive than HD. If you want HD outputs via the API, you’ll need to upload and train your AI model with HD footage.

   • Include the audio_id and output_filename

   • Optionally specify language and maintain_expression

2. Monitor Generation

   • Make a GET request to check status using /v1/shots/{shot_id}/generate/{generate_id}
   • Track the generation progress

3. Download Result

   • Once complete, download the result using /v1/shots/{shot_id}/generate/{generate_id}/download
   • Receive a download_url for the dubbed video