Analyze Video

POST /v1/videos/:id/analyze

Start an asynchronous analysis job that generates subtitles, detects key events, and extracts metadata from the video.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	Video ID

Request body

All optional.

Parameter	Type	Description
videoContext	string	What the video shows
companyContext	string	Company or product background
language	string	Language code (see codes)
tone	string	Desired tone, e.g. professional, casual
contentStyle	string	how-to (default), sop, promotional, training, announcement
productName	string	Referenced by name when contentStyle is promotional
scriptSource	string	video (default), transcript, original, custom
customScript	string	Your own script. Required when scriptSource is custom.
scriptSkillId	string	Brand Kit script skill, applied as a style guide
forceRefresh	boolean	Re-run even if a cached analysis exists
keyEvents	array	Pre-identified moments to build the script around, instead of detecting them
analysisModel	string	Model used to analyze the footage (gemini)
subtitleModel	string	Model used to generate subtitles (openai or gemini)
autoZoom	boolean	Generate zoom moments from detected interactions

keyEvents accepts either plain strings or { text, timestamp } objects. It's the hook for callers that already know the steps - a recorder that logged every click, for instance - and want the script built around them rather than rediscovered.

Content style

contentStyle shapes the structure and register of the generated script. An SOP reads as numbered procedure; a training video builds up concepts; a promotional video leads with outcomes. Getting this right matters more than editing the result afterwards.

Script source

Value	What happens
video	Analyzes the footage and writes a script from what it sees. The default.
transcript	Reuses what the speaker actually said, cleaned up
original	Keeps the speaker's own audio rather than generating narration
custom	Uses the script you pass in customScript, timed to the footage

curl -X POST https://api.vidocu.ai/v1/videos/vid_abc123/analyze \
  -H "Authorization: Bearer vdo_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "contentStyle": "sop",
    "language": "de",
    "companyContext": "Industrial label printers for pharmaceutical packaging"
  }'

Example

curl -X POST https://api.vidocu.ai/v1/videos/vid_.../analyze \
  -H "Authorization: Bearer vdo_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "videoContext": "Product demo for new dashboard",
    "language": "en",
    "tone": "professional"
  }'

Response 202 Accepted

{
  "jobId": "analysis_1708300000000_abc1234",
  "status": "pending"
}

If an analysis is already running for this video, the existing job is returned instead:

Response 200 OK (existing job)

{
  "jobId": "analysis_1708300000000_abc1234",
  "status": "processing",
  "message": "Analysis already in progress"
}

Polling for completion

Use the Jobs endpoint to poll for progress:

curl https://api.vidocu.ai/v1/jobs/analysis_1708300000000_abc1234 \
  -H "Authorization: Bearer vdo_live_your_key_here"

Or set up webhooks to receive a video.analyzed event when the job completes.

Errors

Status	Code	Cause
400	validation_error	Invalid request body
401	authentication_error	Invalid or missing API key
404	not_found	Video not found
423	locked	The video is locked - unlock it in the Vidocu app before you re-analyze it

Locked videos

A locked video's content is frozen through its approval cycle, so this endpoint returns 423 Locked. Check locked on GET /v1/videos/:id first. Exporting a locked video still works.

Next steps

Once analysis completes:

• Get subtitles — Retrieve the generated subtitles
• Export the video — Export with subtitles burned in
• Generate an article — Create a help article from the transcript