Script

The script is the timed set of lines that get burned in as subtitles and spoken as narration. It's produced by Analyze, and this is how you read and change it.

Get the script

GET /v1/videos/:id/script

curl https://api.vidocu.ai/v1/videos/vid_abc123/script \
  -H "Authorization: Bearer vdo_live_your_key_here"

Response 200 OK

{
  "videoId": "vid_abc123",
  "language": "en",
  "lines": [
    { "start": 0, "end": 3.2, "text": "Open the settings panel.", "hasVoice": true, "voiceDuration": 3.1 },
    { "start": 3.2, "end": 7.0, "text": "Choose your workspace.", "hasVoice": true, "voiceDuration": 3.6 }
  ],
  "locked": false
}

hasVoice tells you whether narration audio has been generated for that line.

Replace the script

PUT /v1/videos/:id/script

This is a full replacement, not a patch. Fetch the script, apply your changes, and send back every line. Sending a subset deletes the rest.

curl -X PUT https://api.vidocu.ai/v1/videos/vid_abc123/script \
  -H "Authorization: Bearer vdo_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "lines": [
      { "start": 0, "end": 3.2, "text": "Open the Settings panel." },
      { "start": 3.2, "end": 7.0, "text": "Choose your workspace." }
    ]
  }'

Response 200 OK

{
  "videoId": "vid_abc123",
  "lines": [ "..." ],
  "voiceoverInvalidatedLines": 1
}

Editing text invalidates narration

A line's generated audio belongs to the words it was generated from. When you change a line's text, its existing narration is dropped - carrying it forward would export a video saying something the subtitles no longer show.

voiceoverInvalidatedLines counts how many lines lost their audio, so you know whether to regenerate the voiceover before exporting. Lines whose text you left alone keep their audio, so fixing one typo doesn't cost you a full re-narration.

Timing changes alone don't invalidate anything.

Errors

Status	Code	Cause
400	validation_error	No lines, or a line ends before it starts
401	authentication_error	Invalid or missing API key
403	insufficient_role	The workspace role behind the token can't edit videos
404	not_found	Video not found, or it has no script yet
423	locked	The video is locked - unlock it in the Vidocu app