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 for a landscape video and 4,000 for a portrait one, 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

speed

"slow" | "standard" | "fast"

How soon the images are wanted, which is what they cost. Slow waits up to 6 hours for them and takes 20% off, standard waits up to 3 hours at the normal price, and fast generates them right away for 50% more. Videos from a script under 500 characters are generated right away whichever you pick, and still cost what your option says.

default: standard

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?id=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.

How it differs from AI video V2

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" }'

{ "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?id=9f0c1d5e-3a1b-4c2f-9d7e-8b1a2c3d4e5f" }

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.