{
  "openapi": "3.1.0",
  "info": {
    "title": "Vadyu AI Video Ad Studio API",
    "version": "3.0.0",
    "description": "Programmatically generate single clips, multi-beat commercial 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 typography cards, synthesized background audio scores, and stark black-screen brand logo slates) from product images and URLs. Also available as a Model Context Protocol (MCP) server at https://vadyu.com/api/mcp.",
    "contact": {
      "name": "Vadyu Support",
      "email": "hello@vadyu.com",
      "url": "https://vadyu.com/api-docs"
    }
  },
  "servers": [
    {
      "url": "https://vadyu.com/api",
      "description": "Production Vadyu REST API (v3, v2 & v1)"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "vadyu_live_<hex>",
        "description": "API key generated from https://vadyu.com/dashboard"
      }
    }
  },
  "paths": {
    "/v3/forks": {
      "get": {
        "operationId": "listStudioForksV3",
        "summary": "List API v3 Virtual Studio Forks, starter fork templates, and upstream 'main' studio blueprint",
        "responses": {
          "200": {
            "description": "List of studio forks, starter templates (nyc_luxury_cameo, director_cast_storyline), and upstream main blueprint"
          }
        }
      },
      "post": {
        "operationId": "createStudioForkV3",
        "summary": "Create a new API v3 Virtual Studio Fork from 'main', a starter template_id, or parent_fork_id",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": { "type": "string", "description": "Name of the Studio Fork" },
                  "description": { "type": "string" },
                  "template_id": {
                    "type": "string",
                    "enum": ["nyc_luxury_cameo", "director_cast_storyline"],
                    "description": "Starter fork template ID"
                  },
                  "parent_fork_id": { "type": "string", "default": "main" },
                  "initial_prompt": {
                    "type": "string",
                    "description": "Optional natural-language prompt for the Interactive Co-Builder to customize cast, blocks, brand text cards, black-screen logo outro, and audio on creation"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Studio Fork created with initial commit and diff against main"
          }
        }
      }
    },
    "/v3/forks/{id}": {
      "get": {
        "operationId": "getStudioForkV3",
        "summary": "Get an API v3 Studio Fork, its blueprint, Co-Builder message history, and Git-style diff against 'main'",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Studio Fork details, blueprint, messages, and diff_vs_main"
          }
        }
      },
      "patch": {
        "operationId": "patchStudioForkV3",
        "summary": "Apply a structured patch or instruction to an API v3 Studio Fork",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Updated Studio Fork and diff"
          }
        }
      }
    },
    "/v3/forks/{id}/collaborate": {
      "post": {
        "operationId": "collaborateOnStudioForkV3",
        "summary": "Interactive Co-Builder turn on an API v3 Studio Fork (natural language + structured blueprint patch)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "message": {
                    "type": "string",
                    "description": "Natural-language feedback or direction to evolve the fork's character cast, scenes, brand text cards, black-screen logo outro, or audio"
                  },
                  "patch": {
                    "type": "object",
                    "description": "Optional structured StudioForkBlueprint patch"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated Studio Fork blueprint, Co-Builder assistant reply, and diff_vs_main"
          }
        }
      }
    },
    "/v3/forks/{id}/promote": {
      "post": {
        "operationId": "promoteStudioForkV3",
        "summary": "Open an upstream Pull Request ('pr_open') against Vadyu 'main' for a Studio Fork",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pr_title": { "type": "string" },
                  "pr_notes": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Pull Request opened against upstream main"
          }
        }
      }
    },
    "/v3/generate": {
      "post": {
        "operationId": "generateVideoAdV3",
        "summary": "Submit an API v3 video ad generation job using a Virtual Studio Fork (fork_id), inline fork_blueprint, Director Recipe, or custom blocks[]",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "image_url": { "type": "string", "description": "Public HTTP/HTTPS URL of the product photo" },
                  "image_base64": { "type": "string", "description": "Base64-encoded image string" },
                  "fork_id": {
                    "type": "string",
                    "description": "API v3 Virtual Studio Fork ID (e.g., 'fork_...') or 'main'"
                  },
                  "fork_blueprint": {
                    "type": "object",
                    "description": "Optional inline StudioForkBlueprint override"
                  },
                  "recipe": {
                    "type": "string",
                    "description": "Director Recipe ID from GET /v2/recipes (e.g., 'nyc_luxury', 'minimal_cinema', 'dtc_story', 'editorial_flagship', 'six_atelier_chapters', 'two_voices_dialogue', 'train_window_passage', 'after_dark_montage', or any of the 50+ Signature and Recipe Foundry presets) or a promoted Studio Fork ID ('fork_...')"
                  },
                  "brand_text": { "type": "string" },
                  "brand_subtext": { "type": "string" },
                  "logo_text": { "type": "string" },
                  "logo_url": { "type": "string" },
                  "cta_text": { "type": "string" },
                  "audio_url": { "type": "string" },
                  "audio_mood": {
                    "type": "string",
                    "enum": ["nyc_dusk", "luxury_ambient", "modern_pulse", "none"]
                  },
                  "blocks": {
                    "type": "array",
                    "items": { "type": "object" }
                  },
                  "prompt": { "type": "string" },
                  "format": {
                    "type": "string",
                    "enum": ["9:16", "1:1", "16:9", "4:5"],
                    "default": "9:16"
                  },
                  "variants": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 3,
                    "default": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "API v3 generation job accepted and queued"
          }
        }
      }
    },
    "/v3/videos/{id}": {
      "get": {
        "operationId": "getVideoStatusV3",
        "summary": "Poll API v3 rendering status, fork_id, fork_blueprint, recipe block timeline, and signed MP4 download URL",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "integer" }
          }
        ],
        "responses": {
          "200": {
            "description": "Video status, Studio Fork metadata, coherence score, and signed MP4 URL"
          }
        }
      }
    },
    "/v3/videos": {
      "get": {
        "operationId": "listVideosV3",
        "summary": "List generated video ads with API v3 Studio Fork and recipe metadata",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "enum": ["done", "processing", "failed"] }
          },
          {
            "name": "fork_id",
            "in": "query",
            "required": false,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated video list with v3 Studio Fork metadata"
          }
        }
      }
    },
    "/v2/generate": {
      "post": {
        "operationId": "generateVideoAdV2",
        "summary": "Submit an API v2 Director Recipe or custom composable timeline video ad generation job",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "image_url": {
                    "type": "string",
                    "description": "Public HTTP/HTTPS URL of the product photo"
                  },
                  "image_base64": {
                    "type": "string",
                    "description": "Base64-encoded image string (alternative to image_url)"
                  },
                  "recipe": {
                    "type": "string",
                    "description": "Director Recipe preset ID from GET /v2/recipes (4 Signature presets + 46+ Recipe Foundry presets across micro bumpers, social hooks, travelogues, silent films, dialogues, and multi-chapter epics) combining AI motion scenes with deterministic 0-credit blocks, themes, transitions, and synthesized audio beds"
                  },
                  "brand_text": {
                    "type": "string",
                    "description": "Editorial headline rendered on deterministic text_card blocks (0 render credits)"
                  },
                  "brand_subtext": {
                    "type": "string",
                    "description": "Subtitle rendered beneath brand_text on text_card blocks"
                  },
                  "logo_text": {
                    "type": "string",
                    "description": "Brand wordmark rendered on the final stark #000000 black-screen logo_outro slate (0 render credits)"
                  },
                  "logo_url": {
                    "type": "string",
                    "description": "Optional public HTTP/HTTPS URL of a PNG/SVG/WebP brand logo for the black-screen logo_outro slate"
                  },
                  "logo_base64": {
                    "type": "string",
                    "description": "Optional base64-encoded brand logo image for the black-screen logo_outro slate"
                  },
                  "cta_text": {
                    "type": "string",
                    "description": "Optional CTA pill button text rendered on cta_endcard blocks (e.g. 'SHOP AT VADYU.COM')"
                  },
                  "audio_url": {
                    "type": "string",
                    "description": "Optional public HTTP/HTTPS URL of a custom .mp3, .wav, or .m4a audio track or voiceover"
                  },
                  "audio_mood": {
                    "type": "string",
                    "enum": ["nyc_dusk", "luxury_ambient", "modern_pulse", "none"],
                    "default": "nyc_dusk"
                  },
                  "scene_prompts": {
                    "type": "array",
                    "items": { "type": "string" },
                    "description": "Optional array of custom motion prompts for each ai_scene block"
                  },
                  "scene_captions": {
                    "type": "array",
                    "items": { "type": "string" },
                    "description": "Optional array of lower-third captions burned onto each ai_scene block"
                  },
                  "theme": {
                    "type": "object",
                    "description": "Optional RecipeTheme override for card backgrounds, accent rules, safe zones, and default transitions",
                    "properties": {
                      "accentColor": { "type": "string", "description": "Hex color (#RRGGBB)" },
                      "backgroundColor": { "type": "string", "description": "Dark hex background (#RRGGBB, relative luminance < 0.12)" },
                      "fontStyle": { "type": "string", "enum": ["serif_luxury", "sans_modern", "mono_editorial"] },
                      "safeZone": { "type": "string", "enum": ["standard", "reels_tiktok"] },
                      "defaultTransition": { "type": "string", "enum": ["hard_cut", "fade_black", "flash_white"] }
                    }
                  },
                  "blocks": {
                    "type": "array",
                    "description": "Optional custom composable timeline (2 to 20 blocks; must include at least 1 ai_scene block). Deterministic text_card, ken_burns_still, flash_cut_intro, cta_endcard, split_before_after, and logo_outro blocks cost 0 render credits.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": ["ai_scene", "text_card", "ken_burns_still", "flash_cut_intro", "cta_endcard", "split_before_after", "logo_outro"]
                        },
                        "label": { "type": "string" },
                        "role": { "type": "string" },
                        "prompt": { "type": "string" },
                        "caption": { "type": "string" },
                        "subcaption": { "type": "string" },
                        "headline": { "type": "string" },
                        "subheadline": { "type": "string" },
                        "cta_text": { "type": "string" },
                        "before_label": { "type": "string" },
                        "after_label": { "type": "string" },
                        "logo_text": { "type": "string" },
                        "transition": { "type": "string", "enum": ["hard_cut", "fade_black", "flash_white"] },
                        "duration_sec": { "type": "number" }
                      },
                      "required": ["type"]
                    }
                  },
                  "prompt": {
                    "type": "string",
                    "description": "Optional camera motion and lighting direction"
                  },
                  "format": {
                    "type": "string",
                    "enum": ["9:16", "1:1", "16:9", "4:5", "vertical", "square", "horizontal", "portrait"],
                    "default": "9:16"
                  },
                  "variants": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 3,
                    "default": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "API v2 generation job accepted and queued"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "Render quota exceeded"
          }
        }
      }
    },
    "/v2/recipes": {
      "get": {
        "operationId": "listRecipesV2",
        "summary": "List API v2 Composable Director Recipes, block schemas, audio moods, and community recipe requests",
        "responses": {
          "200": {
            "description": "Catalog of Director Recipes, composable block types, audio moods, and community blueprints"
          }
        }
      },
      "post": {
        "operationId": "submitRecipeFeedbackV2",
        "summary": "Submit a custom ad recipe idea or multi-scene storyline blueprint",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": { "type": "string" },
                  "storyline": { "type": "string" },
                  "brand_text": { "type": "string" },
                  "logo_text": { "type": "string" },
                  "audio_mood": { "type": "string", "enum": ["nyc_dusk", "luxury_ambient", "modern_pulse", "none"] }
                },
                "required": ["storyline"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Recipe blueprint saved"
          }
        }
      }
    },
    "/v2/videos/{id}": {
      "get": {
        "operationId": "getVideoStatusV2",
        "summary": "Poll API v2 rendering status, recipe block timeline, and signed MP4 download URL",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "integer" }
          }
        ],
        "responses": {
          "200": {
            "description": "Video status, recipe block metadata, coherence score, and signed MP4 URL"
          }
        }
      }
    },
    "/v2/videos": {
      "get": {
        "operationId": "listVideosV2",
        "summary": "List generated video ads with recipe metadata and pagination",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "enum": ["done", "processing", "failed"] }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 1 }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 20 }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated video list with v2 recipe metadata"
          }
        }
      }
    },
    "/v1/generate": {
      "post": {
        "operationId": "generateVideoAd",
        "summary": "Submit a standard v1 product video ad generation job",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "image_url": {
                    "type": "string",
                    "description": "Public HTTP/HTTPS URL of the product photo"
                  },
                  "image_base64": {
                    "type": "string",
                    "description": "Base64-encoded image string (alternative to image_url)"
                  },
                  "prompt": {
                    "type": "string",
                    "description": "Optional camera motion and lighting direction"
                  },
                  "format": {
                    "type": "string",
                    "enum": ["9:16", "1:1", "16:9", "4:5"],
                    "default": "9:16"
                  },
                  "sequence": {
                    "type": "string",
                    "enum": ["problem-solution", "ugc-testimonial", "product-feature", "unboxing", "single"],
                    "default": "problem-solution"
                  },
                  "variants": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 3,
                    "default": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Generation job accepted and queued"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "Render quota exceeded"
          }
        }
      }
    },
    "/v1/videos/{id}": {
      "get": {
        "operationId": "getVideoStatus",
        "summary": "Poll rendering status and retrieve signed MP4 download URL",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "integer" }
          }
        ],
        "responses": {
          "200": {
            "description": "Video status, beat progress, coherence score, and signed MP4 URL"
          }
        }
      }
    },
    "/v1/videos": {
      "get": {
        "operationId": "listVideos",
        "summary": "List generated video ads with pagination",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "enum": ["done", "processing", "failed"] }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 1 }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 20 }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated video list"
          }
        }
      }
    },
    "/v1/account": {
      "get": {
        "operationId": "getAccountQuota",
        "summary": "Retrieve active subscription plan and remaining render credits",
        "responses": {
          "200": {
            "description": "Account quota and subscription status"
          }
        }
      }
    }
  }
}