Skip to main content

​
POST /api/generate-ad-video

Takes the video_id and analysis output from POST /api/analyze-video, generates a static ad frame using Gemini and a voiceover using ElevenLabs, then splices the result into the cached clip with ffmpeg.
ELEVENLABS_API_KEY must be configured unless the environment variable ALLOW_SILENT_VOICEOVER=1 is set. Without a valid ElevenLabs key and that override unset, this endpoint will fail.
ffmpeg must be installed and available on PATH. The server will return 500 if ffmpeg is missing or exits with an error.

​
Request

Send the request as multipart/form-data.
​
video_id
string
required
The UUID returned by /api/analyze-video. Must refer to a video still in the server cache (within 30 minutes of the analyze call).
​
analysis
string
required
The full response object from /api/analyze-video, serialized as a JSON string.
​
product_name
string
required
The product to display in the ad segment.

​
Response

​
status
string
required
Always "success" on a successful response.
​
video_url
string
required
Server-relative path to the merged output video, e.g. "/api/output/abc123_edited.mp4". Serve this path with GET /api/output/.
​
voiceover_line
string
required
The voiceover line that was generated and included in the ad segment, e.g. "Oh wow, a 2025 Toyota RAV4 XLE Hybrid AWD."

​
Example

curl -X POST http://127.0.0.1:8000/api/generate-ad-video \
  -F "video_id=550e8400-e29b-41d4-a716-446655440000" \
  -F 'analysis={"scene_breakdown":"...","ad_placement":{...},"product":"...","video_id":"..."}' \
  -F "product_name=2025 Toyota RAV4 XLE Hybrid AWD"
Response 
{
  "status": "success",
  "video_url": "/api/output/550e8400_edited.mp4",
  "voiceover_line": "Oh wow, a 2025 Toyota RAV4 XLE Hybrid AWD."
}

​
Errors

StatusCause
400Any required field (video_id, analysis, product_name) is missing.
400analysis is not valid JSON.
400Ad timestamp from analysis falls too close to the end of the video.
404video_id not found — cache expired or invalid UUID.
500ffmpeg processing failed.
503GEMINI_API_KEY is not configured.

Build docs developers (and LLMs) love

Get started for freeTalk to us