Get API key

Core

Create videos

Creating a video is one call. Pick a mode, send a prompt, get an id back. The render runs in the background — poll it or get a webhook when it's done.

POST/v1/videos

Start a video render. Returns immediately with a video id — the render finishes in the background.

Parameters
modestringrequired
"auto" — Vivideo writes the script and builds a full avatar video."manual" — send your prompt straight to a model you pick.
promptstringrequired
What the video should show or say. 1–5000 characters.
modelstringoptional
Manual only. A model id from GET /v1/models (e.g. veo31_fast).
duration_secondsintegeroptional
Length of the video. Auto: 5–300. Manual: must be one of the model's allowed durations.
resolutionstringoptional
Manual only. Must be one of the model's resolutions (e.g. 720p, 1080p).
aspect_ratiostringoptional
Manual only. One of the model's aspect ratios (e.g. 16:9, 9:16).
avatar_idstringoptional
Auto only. An avatar from GET /v1/avatars. Omit for a default presenter.
voice_idstringoptional
Auto only. A voice from GET /v1/voices.
brand_kit_idstringoptional
Auto only. Apply your logo, colors and fonts — a br_… id from brand kits.
image_urlstringoptional
Manual only. A public https image → turns the request into image-to-video.
folder_idstringoptional
File the video in a folder. Defaults to your library root.

Advanced (manual, where the model supports it): negative_prompt, seed, generate_audio, style, movement_amplitude, cfg_scale, first_frame_url + last_frame_url, image_urls. See Models.

Header — send this for safe retries
Idempotency-Keystringoptional
Any unique string. If the request is retried with the same key, you get the original response back instead of a second video. Prevents duplicate charges.
Returns

A video object with a new id and status: "processing" (paid) or status: "preview" (free accounts — see billing).

Example — auto mode
POST /v1/videos
curl https://api.vivideo.ai/v1/videos \
  -H "Authorization: Bearer $VIVIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "auto",
    "prompt": "A 30-second product intro for our meal-planning app, upbeat",
    "duration_seconds": 30,
    "avatar_id": "Abigail_expressive_2024112501",
    "voice_id": "1bd001e7e50f421d891986aad5158bc8",
    "brand_kit_id": "br_1a2b3c4d",
    "orientation": "landscape"
  }'
Example — manual mode
POST /v1/videos
curl https://api.vivideo.ai/v1/videos \
  -H "Authorization: Bearer $VIVIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-first-video-001" \
  -d '{
    "mode": "manual",
    "model": "veo31_fast",
    "prompt": "A golden retriever surfing a wave at sunset, cinematic",
    "duration_seconds": 8,
    "resolution": "1080p",
    "aspect_ratio": "16:9"
  }'
201 Created
{
  "id": "9c1a7e2b40f14b7f9d3f2a6c8e5d4b21",
  "object": "video",
  "mode": "manual",
  "model": "veo31_fast",
  "status": "processing",
  "credits_charged": 16,
  "poll_interval_seconds": 5
}
✓
How manual picks the operation: text-to-video by default; add image_url for image-to-video; first_frame_url + last_frame_url for a first/last-frame morph; image_urls for multi-image reference. You don't set it — it's inferred from the fields you send.
GET/v1/videos/{id}

Check a video's status and get the finished file. Poll this until status is completed.

Returns

The video object. While rendering, status moves through these states:

statuswhat it means
queuedAccepted, waiting to render.
processingRendering. Manual videos add a progress object.
completedDone — video_url is your MP4.
failedRender failed. Credits are refunded automatically; see error.
previewFree-account preview — see billing.
Example
poll until ready
curl https://api.vivideo.ai/v1/videos/VIDEO_ID \
  -H "Authorization: Bearer $VIVIDEO_API_KEY"

# → { "id": "...", "status": "completed", "video_url": "https://...mp4" }
200 OK
{
  "id": "9c1a7e2b...",
  "object": "video",
  "status": "completed",
  "video_url": "https://vivideocdn.com/outputs/....mp4",
  "caption_url": "https://.../....srt",
  "duration_seconds": 8
}
✓
Don't want to poll? Register a webhook and get a signed video.completed event the moment a render finishes.
GET/v1/videos

List your videos, newest first.

Query parameters
statusstringoptional
Filter by status (e.g. completed).
folder_idstringoptional
Only videos in this folder.
limitintegeroptional
How many to return. 1–100, default 20.
Returns

A list of video objects with count and total.

GET/v1/folders

List your folders. Pass a folder_id when creating a video to file it there.

Returns

A list of folder objects (id, name, created_at).

← Previous
Models
Machine-readable: interactive reference · openapi.yaml · llms-api.txt. Base URL https://api.vivideo.ai.