Translate Video
POST /v1/videos/:id/translate
Start an asynchronous translation job for the video's subtitles.
Translation draws 1 video minute per video minute, per target language from your monthly allowance. See Plans & Limits.
Prerequisites
The video must be analyzed and have subtitles before translating.
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Video ID |
Request body
| Parameter | Type | Required | Description |
|---|---|---|---|
language | string | Yes | Target language code (minimum 2 characters, e.g. es, de, fr) |
Example
curl -X POST https://api.vidocu.ai/v1/videos/vid_.../translate \
-H "Authorization: Bearer vdo_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"language": "es"
}'
Response 202 Accepted
{
"jobId": "translation_1708300000000_abc1234",
"status": "pending"
}
If a translation is already running for this video:
Response 200 OK (existing job)
{
"jobId": "translation_1708300000000_abc1234",
"status": "processing",
"message": "Translation already in progress"
}
What a translation creates
A new package, not a new language on the old one: its own video id, its own approval, its own lock, and its own Knowledge Base article. Both packages carry the same languageGroup, which is how you find every language of one instruction — see Language families.
The training is shared rather than copied. The translated package points at the same module as its source, and the module gains a translation in the target language. That keeps one requirement to one training: the Training Planner has one row per person per training however many languages exist, and a pass is a pass whichever language it was taken in.
The article is translated, not regenerated. The existing help article is translated as it stands, so a wording somebody corrected by hand survives into every language. It is not rewritten from the translated video.
Polling for completion
Use the Jobs endpoint to check progress, or listen for the video.translated webhook event.
Errors
| Status | Code | Cause |
|---|---|---|
| 400 | validation_error | Video must be analyzed before translating, or missing language code |
| 401 | authentication_error | Invalid or missing API key |
| 403 | limit_exceeded | No API access (Business+ required), or video minutes exhausted |
| 404 | not_found | Video not found |
| 423 | locked | The video is locked - unlock it in the Vidocu app before you translate it |
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.