Analyze video

POST /api/analyze-video

Accepts a video clip and a product name. Sends the clip to Gemini for scene analysis, then returns a full scene breakdown, an ad placement recommendation with timestamp and visual instructions, and a video_id to use in POST /api/generate-ad-video.

The video_id returned by this endpoint expires after 30 minutes. Calls to /api/generate-ad-video with an expired or unknown video_id will return 404.

Request

Send the request as multipart/form-data.

video

file

required

The video clip to analyze. Accepted formats: MP4, MOV, MPEG, WEBM, MKV, AVI. Maximum size is MAX_VIDEO_UPLOAD_MB (default 200 MB).

product_name

string

required

The product to advertise. Typically the product_name returned by POST /api/identify-product.

Response

scene_breakdown

string

required

Detailed scene-by-scene analysis with timestamps and transcript.

ad_placement

object

required

Placement recommendation produced by Gemini.

Show properties

ad_timestamp

string

Suggested insertion point in MM:SS format.

ad_timestamp_seconds

number

Same timestamp as a decimal number of seconds.

placement_rationale

string

Why this moment was chosen for the ad insertion.

scene_context

string

Description of what is happening at the insertion point.

ad_description

object

Visual and audio instructions for the ad segment.

Show properties

visual

string

Exact description of how the product should appear on the character or in the frame.

text_or_voiceover

string

Draft voiceover line for the ad segment.

transition_in

string

Recommended transition into the ad segment.

transition_out

string

Recommended transition out of the ad segment.

style_notes

string

Color grade and lighting guidance to match the surrounding footage.

edit_instruction

object

Low-level instruction for the image editor.

Show properties

timestamp

string

The target timestamp for the edit.

whats_happening

string

Brief description of the scene at that moment.

adjustment

string

Specific instruction for the image editor, e.g. how to composite the product into the frame.

product

string

required

The product_name value echoed back from the request.

video_id

string

required

UUID identifying the cached video on the server. Pass this to /api/generate-ad-video. Valid for 30 minutes.

Example

curl -X POST http://127.0.0.1:8000/api/analyze-video \
  -F "video=@/path/to/clip.mp4" \
  -F "product_name=2025 Toyota RAV4 XLE Hybrid AWD"

Errors

Status	Cause
`400`	`product_name` is missing.
`400`	Uploaded file is empty.
`413`	File exceeds `MAX_VIDEO_UPLOAD_MB`.
`503`	`GEMINI_API_KEY` is not configured.
`502`	Gemini video analysis request failed.

Endpoints

POST /api/analyze-video

Request

Response

Example

Errors

Build docs developers (and LLMs) love

Endpoints

​POST /api/analyze-video

​Request

​Response

​Example

​Errors

Build docs developers (and LLMs) love

POST /api/analyze-video

Request

Response

Example

Errors