Templates

AI video V2

Send a script and Vsub splits it into scenes, records the voice over, generates the images and optionally renders the final mp4. Creation returns immediately, so poll the video or listen with webhooks.

POST/v1/ai-videos

Create an AI video

Starts a new video, credits are charged the same way as videos created in the app.

Body

scriptrequired

string

The narration to turn into a video. Up to 10,000 characters, and short enough to fit your plan's maximum video length.

imageStyle

string

Visual style of the generated images. One of

CREEPY_COMIC, 90s_DISNEY, STUDIO_GHIBLI, ADULT_CARTOON, SIMPSONS, CINEMATIC, CUTE_ANIME, ULTRA_REALISM, DARK_COMIC, B&W_COMIC, COMIC, SATIRICAL_2D, PIXAR, 18TH_CENTURY_HISTORICAL, POLISHED_CARTOON, COMIC_REALISM

default: CREEPY_COMIC

size

"portrait" | "landscape"

Aspect ratio of the video.

default: portrait

voiceId

string

ElevenLabs voice to narrate with. Defaults to the same voice the editor starts with. 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.

transition

"smooth" | "strong-swipe"

How one generated scene gives way to the next.

default: smooth

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: 38

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: 50

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" \
  -H "Authorization: Bearer vp_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90" \
  -H "Content-Type: application/json" \
  -d '{
    "script": "In 1963, a small town woke up to something it could not explain.",
    "imageStyle": "CREEPY_COMIC",
    "size": "portrait",
    "webhookUrl": "https://your-app.example.com/hooks/vsub-video"
  }'

Response 200

{
  "id": "9f0c1d5e-3a1b-4c2f-9d7e-8b1a2c3d4e5f",
  "status": "processing",
  "step": "create-scenes",
  "render": false,
  "createdAt": "2026-08-04T09:20:11.000Z",
  "editorUrl": "https://vsub.io/workspace/editor/9f0c1d5e-3a1b-4c2f-9d7e-8b1a2c3d4e5f"
}

Generation runs in the background. Follow the video with Video status or let a webhook tell you when it's done.