Process Video

POST /v1/videos/process

Upload a video and run multiple operations in a single request. The endpoint creates the video, analyzes it, and chains any additional steps you request — voiceover, help article, export, and translation.

Business plan required

The /process endpoint is available on Business plans and above.

Request body

Parameter	Type	Required	Description
url	string	Yes	Public URL of the video file
name	string	No	Display name for the video
context	string	No	Context about the video content
companyContext	string	No	Company or brand context
language	string	No	Primary language code (e.g. en, de)
tone	string	No	Desired tone for analysis
voiceId	string	No	Voice ID for voiceover (required if voiceover is enabled)
generate	object	No	Which operations to run (see below)
exportSettings	object	No	Export configuration

generate object

Field	Type	Default	Description
analysis	boolean	true	Always runs first — generates subtitles and metadata
voiceover	boolean	false	Generate AI voiceover from subtitles
helpArticle	boolean	false	Generate a step-by-step help article
export	boolean	false	Export the final video with subtitles
translation	object	—	Translation configuration
translation.enabled	boolean	false	Enable translation
translation.languages	string[]	[]	Target language codes (e.g. ["es", "fr"])

Pipeline order

Steps execute sequentially in this order (only requested steps run):

1. Analysis — always first
2. Voiceover — requires subtitles from analysis
3. Help article — generated from transcript (synchronous)
4. Export — produces final video
5. Translation — runs last, languages process in parallel

Example

curl -X POST https://api.vidocu.ai/v1/videos/process \
  -H "Authorization: Bearer vdo_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/demo.mp4",
    "name": "Product Demo",
    "context": "SaaS onboarding walkthrough",
    "language": "en",
    "generate": {
      "analysis": true,
      "voiceover": true,
      "export": true,
      "helpArticle": true,
      "translation": {
        "enabled": true,
        "languages": ["es", "fr"]
      }
    },
    "voiceId": "EXAVITQu4vr4xnSDxMaL"
  }'

Response 202 Accepted

{
  "jobId": "process_1708300000000_abc1234",
  "videoId": "vid_1708300000000_xyz5678",
  "status": "processing",
  "steps": ["analysis", "voiceover", "helpArticle", "export", "translation"]
}

Polling for completion

Use the Jobs endpoint to poll the process job:

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

In-progress response

{
  "jobId": "process_1708300000000_abc1234",
  "type": "process",
  "status": "processing",
  "result": {
    "completedSteps": ["analysis", "voiceover"],
    "currentStep": "helpArticle"
  }
}

Completed response

{
  "jobId": "process_1708300000000_abc1234",
  "type": "process",
  "status": "completed",
  "result": {
    "completedSteps": ["analysis", "voiceover", "helpArticle", "export", "translation"],
    "videoId": "vid_1708300000000_xyz5678",
    "exportedVideoUrl": "https://storage.vidocu.ai/...",
    "exportedSrtUrl": "https://storage.vidocu.ai/...",
    "exportedVoiceoverUrl": "https://storage.vidocu.ai/..."
  }
}

Or set up webhooks to receive a process.completed event when the full pipeline finishes.

Webhook events

Event	Fires when
process.completed	All requested steps finished successfully
process.failed	Any step in the pipeline failed

Individual step webhooks (video.analyzed, export.completed, etc.) also fire as each step completes.

Errors

Status	Code	Cause
400	validation_error	Invalid request body, missing voiceId when voiceover enabled, etc.
401	authentication_error	Invalid or missing API key
403	limit_exceeded	Plan does not include /process, or a requested feature requires a higher plan

Quota consumption

Each step consumes video minutes independently:

Step	Cost
Analysis	1 min per video min
Voiceover	1 min per video min
Export	1 min per video min
Help article	2 min flat
Translation	1 min per video min, per language

For a 5-minute video with all features and 2 translation languages: 5 + 5 + 5 + 2 + (5 × 2) = 27 minutes.