Vaideo
Log in Start free
Vaideo API · v1

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.

FieldTypeDescription
prompt *stringWhat the video is about (5-4000 characters, any language). We write the script. You can mention tone, audience, a call to action…
duration_secinteger6-300. Default 60.
aspect_ratiostring9:16 (Shorts, TikTok, Reels) or 16:9 (YouTube). Default 9:16.
languagestringNarration language code (see reference). Default: the language the prompt asks for or is written in.
voicestringVoice id from GET /voices?language=xx, or none for no narration. Pro (HD) voices are included.
stylestringVisual style id from GET /styles. Default photo.
ai_imagesbooleanAI-generated images made for each scene instead of stock footage (+1 credit).
subtitlesbooleanBurned-in animated subtitles. Default true.
webhook_urlstringPublic https URL we call when the video completes or fails.
metadataobjectYour 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”.

URLhttps://app2.vaideo.org/mcp (Streamable HTTP)
AuthHeader Authorization: Bearer vd_live_… (same key as the API)
Toolscreate_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 lengthCredits
up to 60 s1
up to 120 s2
up to 180 s3
up to 300 s5
AI images (instead of stock)+1
PackCreditsPricePer credit
Starter10029 €0.29 €
Growth500119 €0.24 €
Scale2000399 €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}}
HTTPtypeMeaning
400invalid_requestA field is missing or wrong (the message says which).
401authentication_errorMissing, wrong or revoked key.
402insufficient_creditsNot enough credits. Nothing was charged.
404not_foundNo video with that id in your account.
409not_readyDownload asked before the video was completed.
422content_blockedThe prompt breaks our content policy. Nothing was charged.
429rate_limitedToo 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.