Generate Voiceover

POST /v1/videos/:id/voiceover

Start an asynchronous voiceover generation job using AI text-to-speech.

Growth plan required

Voiceover is available on Growth plans and above. Starter plans receive a 403 error.

Prerequisites

The video must have subtitles (run analysis first).

Path parameters

Parameter	Type	Required	Description
id	string	Yes	Video ID

Request body

Parameter	Type	Required	Description
voiceId	string	Yes	Voice ID for text-to-speech (non-empty)
language	string	No	Language code for the voiceover

Example

curl -X POST https://api.vidocu.ai/v1/videos/vid_.../voiceover \
  -H "Authorization: Bearer vdo_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "voiceId": "EXAVITQu4vr4xnSDxMaL",
    "language": "en"
  }'

Response 202 Accepted

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

Polling for completion

Use the Jobs endpoint to check progress, or listen for the voiceover.generated webhook event.

Errors

Status	Code	Cause
400	validation_error	Video must have subtitles, or missing voiceId
401	authentication_error	Invalid or missing API key
403	limit_exceeded	Voiceover requires Growth plan or higher
404	not_found	Video not found