Text in, finished video out
One HTTP call turns an idea into a narrated video: script, voice-over in 29 languages, images or footage, music, subtitles and a 1080p MP4 with no watermark. Use it from your backend, from n8n/Make/Zapier, or let your AI agent do it through our MCP server.
Quickstart
1. Create a key at /developers/keys. 2. Ask for a video. 3. Poll it (or get a webhook) and download the MP4.
curl https://app2.vaideo.org/api/v1/videos \
-H "Authorization: Bearer $VAIDEO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "3 surprising facts about octopuses, curious and fun tone",
"duration_sec": 45,
"aspect_ratio": "9:16",
"language": "en"
}'
Python
import os, time, requests
API = "https://app2.vaideo.org/api/v1"
H = {"Authorization": f"Bearer {os.environ['VAIDEO_API_KEY']}"}
video = requests.post(f"{API}/videos", headers=H, json={
"prompt": "Why the Roman Empire fell, explained in 60 seconds",
"duration_sec": 60,
}).json()
while video["status"] in ("queued", "processing"):
time.sleep(20)
video = requests.get(f"{API}/videos/{video['id']}", headers=H).json()
print(video["status"], video["video_url"])
Node.js
const API = "https://app2.vaideo.org/api/v1";
const H = { Authorization: `Bearer ${process.env.VAIDEO_API_KEY}`, "Content-Type": "application/json" };
let video = await (await fetch(`${API}/videos`, {
method: "POST", headers: H,
body: JSON.stringify({ prompt: "A day in the life of a honeybee", duration_sec: 30 }),
})).json();
while (["queued", "processing"].includes(video.status)) {
await new Promise(r => setTimeout(r, 20000));
video = await (await fetch(`${API}/videos/${video.id}`, { headers: H })).json();
}
console.log(video.status, video.video_url);
A video usually takes 2-6 minutes, depending on length and the queue.
Authentication
Send your key in every request: Authorization: Bearer vd_live_… (or X-API-Key: vd_live_…).
Keys are secret: keep them on your server, never in a browser or mobile app. You can revoke a key at any time.
Create a video
POST /api/v1/videos — charges the credits and queues the video. Returns 201 with the video object.
| Field | Type | Description |
|---|---|---|
prompt * | string | What the video is about (5-4000 characters, any language). We write the script. You can mention tone, audience, a call to action… |
duration_sec | integer | 6-300. Default 60. |
aspect_ratio | string | 9:16 (Shorts, TikTok, Reels) or 16:9 (YouTube). Default 9:16. |
language | string | Narration language code (see reference). Default: the language the prompt asks for or is written in. |
voice | string | Voice id from GET /voices?language=xx, or none for no narration. Pro (HD) voices are included. |
style | string | Visual style id from GET /styles. Default photo. |
ai_images | boolean | AI-generated images made for each scene instead of stock footage (+1 credit). |
subtitles | boolean | Burned-in animated subtitles. Default true. |
webhook_url | string | Public https URL we call when the video completes or fails. |
metadata | object | Your own data (max 2 KB), returned unchanged in the video and the webhook. |
Idempotency: send an Idempotency-Key header (e.g. a UUID). Retrying with the same key returns the same video and never charges twice.
Estimate first: POST /api/v1/videos/estimate with the same body returns the credits it would cost.
Get, list and download
GET /api/v1/videos/{id} — current status. Poll every 15-30 s, or use a webhook.
GET /api/v1/videos?limit=20&starting_after={id}&status=completed — your videos, newest first.
GET /api/v1/videos/{id}/download — 302 redirect to the MP4.
The video object
{
"id": "a1b2c3d4e5f6",
"object": "video",
"status": "completed", // queued | processing | completed | failed
"progress": 100,
"title": "3 Surprising Facts About Octopuses",
"prompt": "3 surprising facts about octopuses, curious and fun tone",
"language": "en",
"voice": "en-US-AndrewMultilingualNeural",
"aspect_ratio": "9:16",
"style": "photo",
"ai_images": false,
"duration_requested_sec": 45,
"duration_sec": 44.8,
"resolution": 1080,
"credits": 1,
"credits_refunded": false,
"created_at": "2026-11-20T18:03:11Z",
"updated_at": "2026-11-20T18:06:40Z",
"video_url": "https://app2.vaideo.org/api/v1/files/a1b2c3d4e5f6/video?exp=…&sig=…",
"thumbnail_url": "https://app2.vaideo.org/api/v1/files/a1b2c3d4e5f6/thumbnail?exp=…&sig=…",
"error": null,
"metadata": {"order_id": "1234"}
}
video_url is a signed link valid for 24 hours: download the file to your own storage. Ask for the video again to get a fresh link.
Videos made with the API are private: they never appear in our public gallery.
Webhooks
With webhook_url, we POST this when the video finishes (we retry after 1, 5, 30, 120 and 360 minutes until you answer 2xx):
{"type": "video.completed", "created": 1795250000, "data": { …video object… }}
type is video.completed or video.failed. Each request carries
Vaideo-Signature: t=<timestamp>,v1=<hex>: an HMAC-SHA256 of "<timestamp>.<raw body>"
with your webhook secret (shown in your dashboard and in GET /account).
import hmac, hashlib, time
def verify(raw_body: bytes, header: str, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
if abs(time.time() - int(parts["t"])) > 300:
return False
expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])
MCP server (Claude, Cursor, AI agents)
Vaideo is also a remote Model Context Protocol server, so any MCP client can make videos for you: “make a 30-second vertical video about this blog post”.
| URL | https://app2.vaideo.org/mcp (Streamable HTTP) |
| Auth | Header Authorization: Bearer vd_live_… (same key as the API) |
| Tools | create_video, get_video, list_videos, estimate_cost, get_account, list_voices, list_styles |
Claude Code
claude mcp add --transport http vaideo https://app2.vaideo.org/mcp \ --header "Authorization: Bearer vd_live_YOUR_KEY"
Cursor, Windsurf and clients with a JSON config
{
"mcpServers": {
"vaideo": {
"url": "https://app2.vaideo.org/mcp",
"headers": { "Authorization": "Bearer vd_live_YOUR_KEY" }
}
}
}
Claude Desktop and clients that only run local servers
{
"mcpServers": {
"vaideo": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://app2.vaideo.org/mcp",
"--header", "Authorization: Bearer vd_live_YOUR_KEY"]
}
}
}
Tools charge the same credits as the API, and failed videos are refunded the same way.
Pricing
Pay per video with credits. No subscription, credits never expire, and a video that fails is refunded automatically.
| Video length | Credits |
|---|---|
| up to 60 s | 1 |
| up to 120 s | 2 |
| up to 180 s | 3 |
| up to 300 s | 5 |
| AI images (instead of stock) | +1 |
| Pack | Credits | Price | Per credit |
|---|---|---|---|
| Starter | 100 | 29 € | 0.29 € |
| Growth | 500 | 119 € | 0.24 € |
| Scale | 2000 | 399 € | 0.20 € |
Every video: 1080p MP4, no watermark, HD voices, music and subtitles included. Need more than 2,000 videos a month, or a custom volume? Write to us from the chat.
Errors and limits
{"error": {"type": "insufficient_credits", "message": "This video costs 2 credits and your balance is 1.", "required": 2, "balance": 1}}
| HTTP | type | Meaning |
|---|---|---|
| 400 | invalid_request | A field is missing or wrong (the message says which). |
| 401 | authentication_error | Missing, wrong or revoked key. |
| 402 | insufficient_credits | Not enough credits. Nothing was charged. |
| 404 | not_found | No video with that id in your account. |
| 409 | not_ready | Download asked before the video was completed. |
| 422 | content_blocked | The prompt breaks our content policy. Nothing was charged. |
| 429 | rate_limited | Too many requests. |
Limits per key: 30 video creations per minute and 500 per day; 120 read requests per minute. Every response includes X-Credits-Remaining.
Reference
Languages
es Español · en English · pt Português · fr Français · de Deutsch · it Italiano · nl Nederlands · pl Polski · ru Русский · tr Türkçe · uz Oʻzbekcha · ar العربية · ur اردو · fa فارسی · hi हिन्दी · he עברית · bn বাংলা · el Ελληνικά · te తెలుగు · ta தமிழ் · hr Hrvatski · sr Srpski · cs Čeština · sk Slovenčina · zh 中文 · ja 日本語 · ko 한국어 · vi Tiếng Việt · th ไทย
Styles
photo Real photo · cinematic Cinematic · vintage Vintage / Sepia · painting Classical painting · anime Anime / Illustration · minimal Minimal / Abstract · bw Black & white · fantasy Epic fantasy · documentary Documentary · nature Nature
Full machine-readable spec: /api/v1/openapi.json (OpenAPI 3.1) — import it into Postman, Insomnia or your agent's tools.