Vsub
Get started
Templates

AI video V3

Send a script and an art style, and Vsub splits the script into scenes, records the voice over, draws every scene in that style and optionally renders the final mp4. Creation returns immediately, so poll the video or listen with webhooks.

How it differs from AI video V2

V2 draws in one of sixteen fixed looks named by imageStyle. V3 draws in an art style learned from footage you uploaded, so the scenes look like your channel rather than like a preset. That style is required, and its id comes from Art styles. V3 also accepts a recorded voice over instead of a script, and leaves captions off unless you ask for them.

POST/v1/ai-videos-v3

Create an AI video

Starts a new video, credits are charged the same way as videos created in the app.
Body
artStyleIdrequired
string
How every scene is drawn. List the styles your workspace can use with Art styles.
script
string
The narration to turn into a video. Up to 30,000 characters, and short enough to fit your plan's maximum video length. Required unless you send voiceoverUrl.
voiceoverUrl
string
HTTPS url of a recording to narrate with instead of generating a voice. Vsub transcribes it and the script comes from what it hears, so voiceId and voiceStyle are ignored. One of .aac, .flac, .m4a, .mp3, .oga, .ogg or .wav, up to 200MB.
size
"portrait" | "landscape"
Aspect ratio of the video.
default: landscape
voiceId
string
ElevenLabs voice to narrate with. Defaults to the same voice the create form starts with. Ignored when you send voiceoverUrl. List the ids with Voices.
voiceStyle
object
Fine tunes the narration. Every field is a percentage, matching the voice sliders in the editor. Pass only the ones you want to change, see voiceStyle fields.
captions
boolean
Burns the narration in as captions. V3 videos carry no captions by default, the artwork is what tells the story.
default: false
captionTemplateId
number
Caption style the words on screen use. Built in styles have a negative id, styles you saved in the app have a positive one, list them with Caption templates. Left out, the video uses the style your workspace used last.
render
object
Export the mp4 as soon as generation finishes, taking the same fields as the render endpoint, see render fields. Pass an empty object to accept the defaults. Left out, the video stays an editable project you can render later. Rendering charges export credits and requires a paid plan.
webhookUrl
string
HTTPS callback fired once the video reaches a terminal status. See Webhooks for details.
voiceStyle fields
voiceStyle.stability
number, 0 to 100
Lower values let the voice vary more between takes, higher values keep it flat and predictable.
default: 50
voiceStyle.similarityBoost
number, 0 to 100
How closely the output sticks to the original voice.
default: 75
voiceStyle.style
number, 0 to 100
Style exaggeration. Higher values push the delivery harder, at some cost to stability.
default: 0
voiceStyle.speed
number, 70 to 120
Speaking rate as a percentage of the voice’s natural pace.
default: 100
render fields
render.format
"standard" | "greenscreen"
Standard renders the finished video. Green screen drops the background and renders the captions and overlays on a solid green fill, ready to key out in your own editor.
default: standard
render.frameRate
30 | 60
Frames per second. Rendering costs 30 credits per minute of video at 30fps and 60 credits per minute at 60fps.
default: 30
Request
curl -X POST "https://api.vsub.io/v1/ai-videos-v3" \
  -H "Authorization: Bearer vp_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90" \
  -H "Content-Type: application/json" \
  -d '{
    "artStyleId": "6f1d0b74-9a2e-4f3c-8b51-2d7c9e40a1b8",
    "script": "Every map you have ever seen is wrong, and here is why.",
    "size": "landscape",
    "webhookUrl": "https://your-app.example.com/hooks/vsub-video"
  }'
Response 200
{
  "id": "9f0c1d5e-3a1b-4c2f-9d7e-8b1a2c3d4e5f",
  "status": "processing",
  "step": "create-vocal",
  "render": false,
  "createdAt": "2026-08-14T09:20:11.000Z",
  "editorUrl": "https://vsub.io/workspace/editor/9f0c1d5e-3a1b-4c2f-9d7e-8b1a2c3d4e5f"
}

Generation runs in the background and a V3 video has a lot of scenes to draw, so it takes longer than V2. Follow the video with Video status or let a webhook tell you when it's done.

Narrate with your own recording

Sending voiceoverUrl instead of a script has Vsub transcribe the recording, cut it into parts and draw the scenes against the words it heard.

Request
curl -X POST "https://api.vsub.io/v1/ai-videos-v3" \
  -H "Authorization: Bearer vp_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90" \
  -H "Content-Type: application/json" \
  -d '{
    "artStyleId": "6f1d0b74-9a2e-4f3c-8b51-2d7c9e40a1b8",
    "voiceoverUrl": "https://your-app.example.com/audio/episode-14.mp3",
    "captions": true,
    "render": {}
  }'

Send either script or voiceoverUrl, not both. The request stays open while the recording is fetched, so a large file takes a moment to answer.