VadyuAPI v1, v2 & v3 · MCP 3.0

Developer REST API v1/v2/v3 & MCP Server 3.0

Programmatic AI Video Ad API & MCP

Turn product images and URLs into high-converting multi-beat video ads, API v2 Composable Director Recipes, and API v3 Virtual Studio Forks (Git-style studio forking with interactive Co-Builder sessions, Movie Director character casting, deterministic brand messaging cards, synthesized audio scores, and stark black-screen logo slates).

REST API v3, v2 & v1

https://vadyu.com/api/v3

MCP Server URL

https://vadyu.com/api/mcp

Auth Scheme

Bearer <vadyu_live_...>

Guaranteed Quality

Zero-Hallucination Check

MODEL CONTEXT PROTOCOL (MCP 3.0)

Connect Vadyu to Claude, Cursor & AI Agents

Let your AI agent create API v3 Virtual Studio Forks, collaborate interactively on character casting & timelines, compose API v2 Director Recipes, generate product video ads, and poll rendering status via native MCP tool calls.

Download vadyu-mcp.mjs

Option A: Remote HTTP MCP (Cursor / Claude Code / Windsurf)

{
  "mcpServers": {
    "vadyu": {
      "url": "https://vadyu.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Option B: Local Stdio Bridge (Claude Desktop)

{
  "mcpServers": {
    "vadyu": {
      "command": "sh",
      "args": ["-c", "curl -fsSL https://vadyu.com/mcp/vadyu-mcp.mjs | node"],
      "env": {
        "VADYU_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Exposed MCP 3.0 Tools (11 Tools)

vadyu_generate_video_ad

Generate video ads from an API v3 Studio Fork (fork_id), API v2 Director Recipe (nyc_luxury, minimal_cinema, dtc_story, blocks[]), or v1 storyboard.

vadyu_create_studio_fork

Fork the Vadyu Studio from main or starter templates (nyc_luxury_cameo, director_cast_storyline) with optional initial_prompt.

vadyu_collaborate_on_fork

Interactive Co-Builder turn on a fork_id: send natural-language direction or a blueprint patch to evolve cast, scenes, brand text, logo outro, and audio.

vadyu_list_studio_forks

List API v3 Studio Forks, starter templates, and the upstream main blueprint.

vadyu_promote_studio_fork

Open an upstream Pull Request (pr_open) against Vadyu main for a high-performing Studio Fork.

vadyu_list_recipes

List API v2 Composable Director Recipes, block schemas (ai_scene, text_card, logo_outro), audio moods, and community blueprints.

vadyu_submit_recipe_feedback

Submit a custom ad recipe idea or multi-scene storyline blueprint directly to Vadyu.

vadyu_get_video_status

Poll beat progress, fork/recipe block timeline, coherence score, and get the signed MP4 video_url.

vadyu_list_videos

List recent generated video ads with status filters and pagination.

vadyu_get_account_quota

Check subscription tier, remaining render credits, and monthly limits.

vadyu_list_sequences_and_formats

Inspect all storyboard templates (problem-solution, ugc-testimonial, product-feature, unboxing, single), v2 recipes, audio moods, and aspect ratios.

NEW · REST API V3

Virtual Studio Forks & Interactive Co-Builder (`/api/v3/*`)

Create a Git-style fork of the Vadyu Studio pipeline before starting, collaborate interactively with the Co-Builder to cast characters with locked visual continuity, customize scene/text/logo blocks, render ads against your fork, and promote top forks upstream via Pull Request.

https://vadyu.com/api/v3

GET / POST/api/v3/forks

Fork the studio from main or starter templates (nyc_luxury_cameo, director_cast_storyline) with optional initial_prompt.

POST/api/v3/forks/:id/collaborate

Interactive Co-Builder turn: send natural-language feedback or a structured patch to evolve cast, scenes, brand text cards, black-screen logo outro, and audio.

POST/api/v3/generate

Render a commercial video ad using your fork_id (or x-vadyu-fork header), inline fork_blueprint, or Director Recipe.

POST/api/v3/forks/:id/promote

Open an upstream Pull Request (pr_open) against Vadyu's core main studio pipeline.

Example (cURL): Fork Studio + Co-Builder Turn + Render via API v3

# 1. Fork the Studio from 'nyc_luxury_cameo' (or 'main')
curl -X POST https://vadyu.com/api/v3/forks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "NYC Dusk Cab Chanel Fork",
    "template_id": "nyc_luxury_cameo",
    "initial_prompt": "Show opening motion, brand text TIMELESS IN MOTION, cut to a woman hailing a cab in NYC with a glimpse of her Chanel bag, then cut to a black screen with logo CHANEL"
  }'

# 2. Collaborate interactively with the Co-Builder on your fork
curl -X POST https://vadyu.com/api/v3/forks/fork_YOUR_ID/collaborate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Cast a protagonist in a tailored camel coat and lock her visual continuity across all AI scenes"
  }'

# 3. Render a video ad against your Studio Fork
curl -X POST https://vadyu.com/api/v3/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/quilted-bag.jpg",
    "fork_id": "fork_YOUR_ID",
    "format": "9:16"
  }'

NEW · REST API V2

Director Recipes & Composable Timelines (`/api/v2/*`)

Combine AI motion scenes with deterministic editorial brand messaging cards, synthesized background audio scores, and stark black-screen brand logo slates. Deterministic text & logo blocks cost 0 render credits.

https://vadyu.com/api/v2

POST/api/v2/generate

Render a preset recipe (nyc_luxury, minimal_cinema, dtc_story) or pass a custom blocks[] timeline with brand_text, logo_text, logo_url, and audio_mood.

GET / POST/api/v2/recipes

Inspect all available recipes, block schemas, and audio moods—or submit new customer/agent storyline blueprints.

GET/api/v2/videos/:id

Poll v2 rendering status with full recipe block metadata, duration, coherence score, and signed MP4 URL.

Example (cURL): NYC Luxury Cameo Recipe via API v2

curl -X POST https://vadyu.com/api/v2/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/quilted-bag.jpg",
    "recipe": "nyc_luxury",
    "brand_text": "TIMELESS IN MOTION",
    "brand_subtext": "NEW YORK · AUTUMN / WINTER",
    "logo_text": "CHANEL",
    "audio_mood": "nyc_dusk",
    "format": "9:16"
  }'

202 Accepted Response (API v2):

{
  "api_version": "v2",
  "id": 712,
  "status": "processing",
  "format": "vertical",
  "sequence": "recipe:nyc_luxury",
  "recipe": "nyc_luxury",
  "blocks": [
    { "type": "ai_scene", "label": "Opening Motion", "duration_sec": 5 },
    { "type": "text_card", "label": "Brand Messaging", "duration_sec": 2 },
    { "type": "ai_scene", "label": "NYC Cab Cameo", "duration_sec": 5 },
    { "type": "logo_outro", "label": "Black Screen Logo", "duration_sec": 2.5 }
  ],
  "audio_mood": "nyc_dusk",
  "ai_renders_reserved": 2,
  "total_duration_seconds": 14.5,
  "poll_url": "https://vadyu.com/api/v2/videos/712"
}

Code Examples

POST/api/v1/generate— Submit a new video ad generation

Parameters (JSON)

image_urlRequired*

Public HTTP/HTTPS URL of the product image (e.g. from CDN or Shopify). Alternatively, provide image_base64.

promptOptional

Creative motion guidance (e.g. "Warm morning sunlight, slow rotation"). If omitted, the sequence's curated beat prompt is used.

formatDefault: "9:16"

Target aspect ratio: "9:16" (TikTok/Reels), "1:1" (Square), "16:9" (Landscape), "4:5" (Portrait Feed).

sequenceDefault: "problem-solution"

Ad structure storyboard: "problem-solution", "ugc-testimonial", "product-feature", "unboxing", "single".

variants1 to 3

Number of creative variant angles to generate in parallel.

Request Example

curl -X POST https://vadyu.com/api/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/product-bottle.jpg",
    "prompt": "Warm golden morning sunlight, cinematic slow rotation showing label crisp and clear",
    "format": "9:16",
    "sequence": "problem-solution",
    "variants": 1
  }'

202 Accepted Response:

{
  "id": 689,
  "status": "processing",
  "format": "9:16",
  "sequence": "problem-solution",
  "beats_total": 4,
  "prompt": "Warm golden morning sunlight, cinematic slow rotation",
  "estimated_seconds": 60,
  "poll_url": "https://vadyu.com/api/v1/videos/689",
  "created_at": "2026-10-23T20:30:00.000Z"
}

GET/api/v1/videos/:id— Retrieve rendering progress and final video download URL

Status Values

processingAd is being rendered through the cloud GPU pipeline. Poll every 3–5 seconds.
doneFinished MP4 ad is ready. video_url contains the download/stream URL.
failedGeneration encountered an error. Remaining credits are automatically refunded.

Coherence Guarantee Score:

Completed multi-beat ads include an automated coherence_score (0–100) ensuring product labels, typography, and shapes remain preserved across all camera cuts.

Status Poll Example

curl https://vadyu.com/api/v1/videos/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

200 OK Response (Completed):

{
  "id": 689,
  "status": "done",
  "video_url": "https://wanput-videos-bucket.s3.us-west-2.amazonaws.com/request_689.mp4?...",
  "preview_url": "https://vadyu.com/samples/featured/supplement.jpg",
  "duration": 20,
  "sequence": "problem-solution",
  "beats_total": 4,
  "beats_done": 4,
  "coherence_score": 96,
  "coherence_note": "Typography and logo remain 100% faithful and sharp across all 4 cuts",
  "created_at": "2026-10-23T20:30:00.000Z"
}

GET/api/v1/account— Check remaining render credits and plan quota

Plan Eligibility & Quota Metering

Developer REST API access is included on the Growth ($299/mo · 200 renders) and Agency ($799/mo · 750 renders) plans.

Credits are metered per render beat. A 4-beat sequence consumes 4 render credits. Check renders_remaining programmatically before kicking off high-volume batches.

View Growth & Agency plans →

Account Check Example

curl https://vadyu.com/api/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"

200 OK Response:

{
  "user_id": 42,
  "email": "dtc-brand@company.com",
  "plan": "pro",
  "plan_name": "Growth",
  "subscription_status": "active",
  "renders_remaining": 184,
  "renders_total": 200,
  "ads_total_per_month": 40,
  "can_generate": true
}

Supported Storyboard Sequences

Choose an automated ad narrative structure optimized for paid performance.

problem-solution4 beats · ~20s

Top-performing direct-response format

Hook attention → Agitate the customer pain point → Reveal your product as the solution → Call to action.

ugc-testimonial4 beats · ~20s

Organic TikTok / Reels creator style

Creator selfie hook → Honest reaction → Product demo in hand → Limited-time promo.

product-feature3 beats · ~15s

Premium brand cinematic focus

Cinematic hero reveal → Macro texture & craftsmanship → Purchase CTA.

unboxing3 beats · ~15s

E-commerce delivery anticipation

Package arrival → Unboxing reveal → First impressions & usage.

single1 beat · ~5s

Single hero motion clip

Continuous smooth 5-second dynamic hero shot with your custom prompt.

Ready to start generating video ads via API?

Generate your API key in the dashboard in 10 seconds.

Go to Dashboard