{
 "openapi": "3.1.0",
 "info": {
  "title": "AI Video Atlas API",
  "version": "1.0.0",
  "description": "AI Video Atlas: sourced AI video shots (prompt + model + est. cost + creator), workflows by job, and vendor-stated prices per second. Use plan_shots to storyboard and price a whole video, find_shot for a described shot, recommend_model for \"which model / what cost\", get_prices for prices, get_workflow for how-to, whats_new for news. Read atlas://guide for rules: costs are estimates, legacy models are excluded, \"not stated\" means unknown, and always credit and link the creator. Read-only, free, no key. Use get_guide for sourced per-model prompting guidance (structure, camera language, what to avoid, limits) before writing a prompt for a specific model. Guide: https://aivideoatlas.com/agents/",
  "contact": {
   "url": "https://aivideoatlas.com/agents/"
  }
 },
 "servers": [
  {
   "url": "https://mcp.aivideoatlas.com"
  }
 ],
 "paths": {
  "/v1/plan_shots": {
   "get": {
    "operationId": "plan_shots",
    "summary": "Plan a multi-shot AI video from a plain description (deterministic, built only from Atlas data; no AI generation)",
    "description": "Plan a multi-shot AI video from a plain description (deterministic, built only from Atlas data; no AI generation). Output is staged: decide (model/mode/clip length/aspect/cost with reasons and capability checks), direct (shot list with per-model prompts), assets (every reference/frame with status needs-generation|user-supplied|approved), image_prompts, and steps, which include a STOP: get the user to approve assets before generating any video. Global directives (same X in every shot, vertical, no text, style) apply to all shots; questions and request wording are never planned as shots; an explicit shot count is honored; clips longer than an endpoint's documented max are split. The description is split into beats (sentences, clauses, and cues like \"then\", \"cut to\", \"close-up\", \"wide\"). For each beat it returns a shot type; a recommended model endpoint with its current vendor-stated $/s and source; the generation mode to use (t2v, i2v, reference-to-video, start/end frame, v2v, lip sync; only modes the vendor docs confirm) with a one-line reason; image prompts for any input frames, plus a shared character/product reference sheet when shots must match; an adapted prompt built from the best-matching sourced example (credited and linked), an estimated cost (5 s per shot by default), and a how-to workflow when one applies (lip sync, consistent character…). It also returns a total. budget_usd (total) and/or max_per_shot steer it to cheaper supported endpoints; each shot also offers a cheaper alternative with its cost, and the plan says if the budget can't be met. Use this for \"plan / storyboard / make me a video of…\" requests; use find_shot for a single shot. Before presenting, adapt the wording to the user's voice, context and brand (names, tone, product details), but keep the prices, models, modes, clip lengths and reference tags exactly as returned.",
    "parameters": [
     {
      "name": "force_plan",
      "in": "query",
      "required": false,
      "description": "Return a shot plan even when the request reads as a pricing-only question",
      "schema": {
       "type": "boolean"
      }
     },
     {
      "name": "description",
      "in": "query",
      "required": true,
      "description": "What the video should show, in plain words. Several beats are fine.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "budget_usd",
      "in": "query",
      "required": false,
      "description": "Optional total budget in USD.",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "style",
      "in": "query",
      "required": false,
      "description": "Optional look applied to every shot, e.g. \"35mm film, warm grade\" or \"anime\".",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "max_per_shot",
      "in": "query",
      "required": false,
      "description": "Optional maximum USD per shot.",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "clip_seconds",
      "in": "query",
      "required": false,
      "description": "Seconds per shot (default 5).",
      "schema": {
       "type": "number",
       "default": 5
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Result",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "429": {
      "description": "Rate limited; see Retry-After"
     }
    }
   }
  },
  "/v1/find_shot": {
   "get": {
    "operationId": "find_shot",
    "summary": "Search AI Video Atlas's library of 107 sourced AI video shots (real prompts that creators posted, with the model used, an estimated cost and a link to the original)",
    "description": "Search AI Video Atlas's library of 107 sourced AI video shots (real prompts that creators posted, with the model used, an estimated cost and a link to the original). Use this FIRST when the user describes a shot, scene, style or job (\"product ad with a rotating can\", \"anime fight\", \"lip sync dialogue\", \"drone over mountains\"). Filters: shot_type (ads, music, shorts, characters, product, cinematic, lipsync, anime), model (e.g. kling, veo, seedance), max_cost_usd (estimated cost of the clip; when the prompt states no length we use a 5-second clip). Returns prompt excerpts; call best_prompt with a slug for the full prompt. Do not use for prices alone (use get_prices) or for tools/workflows (use get_workflow).",
    "parameters": [
     {
      "name": "query",
      "in": "query",
      "required": true,
      "description": "What the shot should look like or achieve, in plain words.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "shot_type",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "string",
       "enum": [
        "ads",
        "music",
        "shorts",
        "characters",
        "product",
        "cinematic",
        "lipsync",
        "anime"
       ]
      }
     },
     {
      "name": "model",
      "in": "query",
      "required": false,
      "description": "Only shots made with this model family (strict; comparisons that merely include it are excluded), e.g. kling, veo, seedance, hailuo, runway, luma, wan, ltx, sora",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "max_cost_usd",
      "in": "query",
      "required": false,
      "description": "Max estimated cost per clip in USD",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "integer",
       "default": 5
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Result",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "429": {
      "description": "Rate limited; see Retry-After"
     }
    }
   }
  },
  "/v1/best_prompt": {
   "get": {
    "operationId": "best_prompt",
    "summary": "Get the full, sourced prompt that best matches a shot (free text or a slug from find_shot), optionally for a target model",
    "description": "Get the full, sourced prompt that best matches a shot (free text or a slug from find_shot), optionally for a target model. Returns the exact prompt text as the creator posted it, the creator credit and source, the model it was made with, and factual adaptation notes when the target model differs (other Atlas shots on the target model and its current supported price). Atlas never claims how a prompt will perform on a model it was not made with; treat adaptation notes as guidance.",
    "parameters": [
     {
      "name": "shot",
      "in": "query",
      "required": true,
      "description": "A slug from find_shot or a plain description of the shot.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "model",
      "in": "query",
      "required": false,
      "description": "Target model family (optional).",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Result",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "429": {
      "description": "Rate limited; see Retry-After"
     }
    }
   }
  },
  "/v1/recommend_model": {
   "get": {
    "operationId": "recommend_model",
    "summary": "Recommend which AI video model to use for a shot, with the evidence: how many sourced Atlas shots of that kind were made with each model, the cheapest supported vendor-stated $/s, and an estimated total for the clip length and number of clips",
    "description": "Recommend which AI video model to use for a shot, with the evidence: how many sourced Atlas shots of that kind were made with each model, the cheapest supported vendor-stated $/s, and an estimated total for the clip length and number of clips. Pass budget_usd (total) and/or max_per_shot to drop models whose estimate exceeds it; over-budget models are listed with their cost. Each row includes the generation modes the vendor docs confirm (t2v, i2v, reference-to-video, start/end, v2v, lip sync; unknown where docs do not say). Legacy, deprecated and discontinued models are never recommended. Filters by the required mode FIRST (detected from the shot text or the mode argument; endpoints whose docs say unknown are excluded), then ranks the cheapest qualifying endpoint first and notes when a pricier one has more proof. Includes each endpoint's max clip length and splits long clips.",
    "parameters": [
     {
      "name": "shot",
      "in": "query",
      "required": true,
      "description": "",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "mode",
      "in": "query",
      "required": false,
      "description": "Required generation mode; detected from the shot text when omitted",
      "schema": {
       "type": "string",
       "enum": [
        "t2v",
        "i2v",
        "r2v",
        "start_end",
        "v2v",
        "lipsync"
       ]
      }
     },
     {
      "name": "budget_usd",
      "in": "query",
      "required": false,
      "description": "Total budget for all clips",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "max_per_shot",
      "in": "query",
      "required": false,
      "description": "Max USD per clip",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "clip_seconds",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "number",
       "default": 5
      }
     },
     {
      "name": "clips",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "integer",
       "default": 1
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Result",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "429": {
      "description": "Rate limited; see Retry-After"
     }
    }
   }
  },
  "/v1/get_prices": {
   "get": {
    "operationId": "get_prices",
    "summary": "Vendor-stated AI video prices per second from AI Video Atlas's tracker, each with its source URL and the date we checked it",
    "description": "Vendor-stated AI video prices per second from AI Video Atlas's tracker, each with its source URL and the date we checked it. Filter by model family or host. Legacy, deprecated and discontinued rows are excluded unless include_legacy=true (then they are flagged by status). Use for \"how much does X cost\", \"cheapest model\", or before quoting any cost.",
    "parameters": [
     {
      "name": "model",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "host",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "include_legacy",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "boolean",
       "default": false
      }
     },
     {
      "name": "sort",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "string",
       "enum": [
        "cheapest",
        "model"
       ],
       "default": "cheapest"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Result",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "429": {
      "description": "Rate limited; see Retry-After"
     }
    }
   }
  },
  "/v1/get_workflow": {
   "get": {
    "operationId": "get_workflow",
    "summary": "How-to workflows, tools and model guides for AI video, grouped by job: consistent-character (Keep a character consistent), lip-sync (Lip sync & talking heads), product-ad (Product ads & UGC), camera (Direct the camera), long (Longer & multi-shot videos), i2v (Animate a still image), edit (Edit or restyle footage), upscale (Upscale & smooth), local (Run it on your own GPU), models (Models & hosts)",
    "description": "How-to workflows, tools and model guides for AI video, grouped by job: consistent-character (Keep a character consistent), lip-sync (Lip sync & talking heads), product-ad (Product ads & UGC), camera (Direct the camera), long (Longer & multi-shot videos), i2v (Animate a still image), edit (Edit or restyle footage), upscale (Upscale & smooth), local (Run it on your own GPU), models (Models & hosts). Pass job for a curated list, query for free text (e.g. \"comfyui lipsync\", \"upscale to 4k\"), or slug for one item in full. Returns sources, creators, license and price as stated.",
    "parameters": [
     {
      "name": "job",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "string",
       "enum": [
        "consistent-character",
        "lip-sync",
        "product-ad",
        "camera",
        "long",
        "i2v",
        "edit",
        "upscale",
        "local",
        "models"
       ]
      }
     },
     {
      "name": "query",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "slug",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "integer",
       "default": 8
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Result",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "429": {
      "description": "Rate limited; see Retry-After"
     }
    }
   }
  },
  "/v1/get_guide": {
   "get": {
    "operationId": "get_guide",
    "summary": "Prompting guidance from AI Video Atlas, sourced from vendor prompting docs (Google, BytePlus, Runway, Luma, MiniMax, Alibaba, LTX, xAI, fal) plus proven Atlas examples",
    "description": "Prompting guidance from AI Video Atlas, sourced from vendor prompting docs (Google, BytePlus, Runway, Luma, MiniMax, Alibaba, LTX, xAI, fal) plus proven Atlas examples. Pass model (kling, veo, seedance, runway, luma, hailuo, wan, ltx, grok-imagine…) for prompt structure, camera language, what the model responds to, things to avoid and known limits; or topic (shot-vocabulary, tagging, consistent-characters, i2v-vs-r2v, setup-playbooks). Every item carries its source URL; items marked atlas-editorial are our summary, not a vendor claim. Call with no arguments to list what exists. Use before writing a prompt for a specific model.",
    "parameters": [
     {
      "name": "model",
      "in": "query",
      "required": false,
      "description": "Model family, e.g. kling, veo, seedance, runway, luma, hailuo, wan, ltx, grok-imagine",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "topic",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "string",
       "enum": [
        "consistent-characters",
        "i2v-vs-r2v",
        "setup-playbooks",
        "shot-vocabulary",
        "tagging"
       ]
      }
     },
     {
      "name": "kind",
      "in": "query",
      "required": false,
      "description": "Optional filter, e.g. camera or avoid",
      "schema": {
       "type": "string",
       "enum": [
        "structure",
        "camera",
        "responds_to",
        "mode",
        "consistency",
        "tagging",
        "audio",
        "avoid",
        "limits",
        "workflow",
        "technique",
        "pricing"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Result",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "429": {
      "description": "Rate limited; see Retry-After"
     }
    }
   }
  },
  "/v1/whats_new": {
   "get": {
    "operationId": "whats_new",
    "summary": "What is new in AI Video Atlas: the newest sourced shots and guides added in the last N days (default 7), newest first, with X like counts where we have them (\"new\" otherwise)",
    "description": "What is new in AI Video Atlas: the newest sourced shots and guides added in the last N days (default 7), newest first, with X like counts where we have them (\"new\" otherwise). Use for \"what's new in AI video\", weekly roundups, or trend questions. For the full weekly digest (new models, price changes, new shots, legacy prices) read https://aivideoatlas.com/digest/latest.json.",
    "parameters": [
     {
      "name": "days",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "integer",
       "default": 7
      }
     },
     {
      "name": "kind",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "string",
       "enum": [
        "shots",
        "guides",
        "all"
       ],
       "default": "all"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "integer",
       "default": 10
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Result",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "429": {
      "description": "Rate limited; see Retry-After"
     }
    }
   }
  }
 }
}