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

Parameter	Type	Required	Description
videoContext	string	No	Context about the video content
companyContext	string	No	Company or brand context
language	string	No	Language code (e.g. en, de)
tone	string	No	Desired tone or style

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

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