API Reference

Authentication

All API requests must include your API key in the Authorization header.

Authorization: Bearer mvk_your_api_key_here

Create and manage API keys from your dashboard. Keys start with mvk_ and should be kept secret. The only unauthenticated endpoint is GET /v1/health — it returns {"status":"ok"} for uptime checks.

Create an async video generation job. miltos-5 (default) produces a full multi-scene video with optional narration, music and SFX; miltos-3/4 produce single-scene animations. Returns 202 with a job id immediately — poll GET /v1/videos/{id} or receive a webhook.

Request Body

Example

curl -X POST https://us-central1-motionvid-ai.cloudfunctions.net/api/v1/videos \
  -H "Authorization: Bearer mvk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A 60-second explainer on how solar panels work",
    "model": "miltos-5",
    "enhance_prompt": true,
    "duration": 60,
    "aspect_ratio": "16:9",
    "narration": true,
    "music": true,
    "render": true,
    "webhook_url": "https://example.com/webhooks/motionvid"
  }'

Response (202 Accepted)

{
  "id": "vj_abc123",
  "status": "queued",
  "model": "miltos-5",
  "estimated_credits": 21
}

Poll a video job. Multi-scene jobs report live progress as scenes are committed. Statuses: queued → processing → rendering (when render: true) → completed | failed | canceled, with phase giving the finer step inside processing. Multi-scene jobs typically take around 5 minutes, occasionally up to 15.

Response

{
  "id": "vj_abc123",
  "status": "processing",
  "phase": "generating",
  "phase_detail": "Building scenes — 3 of 6 committed. Scenes are built one at a time, roughly 30-90 seconds each, so a steady count between polls is normal, not a stall.",
  "poll_after_seconds": 30,
  "model": "miltos-5",
  "prompt": "A 60-second explainer on how solar panels work",
  "enhanced_prompt": "Create a cinematic 60-second explainer...",
  "project_id": "proj_789",
  "progress": { "scenes_committed": 3, "scenes_planned": 6 },
  "scenes": [
    { "id": "s1", "title": "Hook — the sun's energy", "duration_seconds": 8 },
    { "id": "s2", "title": "Photovoltaic effect", "duration_seconds": 11 }
  ],
  "app_url": "https://motionvid.ai/motion-graphics/proj_789",
  "created_at": "2026-07-07T10:00:00.000Z",
  "updated_at": "2026-07-07T10:03:12.000Z"
}

A job is not stuck just because it looks idle: the AI writes the script and plan before any scene exists, so phase: "planning" with zero committed scenes is normal for the first several minutes. updated_at tracks job-record writes only and stays frozen through generation — poll on phase, not on it.

When completed (and rendered), the response additionally carriescredits_cost and a download_url — a ~15-minute signed link. Re-fetch this endpoint any time for a fresh link. app_url never expires and opens the video in MotionVid, so it is the better link to show a person.

Change a finished video by describing the change — the same AI agent that powers in-app editing runs your instruction against the job's project, with the original build as conversation context. Edits are surgical: only what the instruction names is regenerated, so a wording or color change costs a fraction of a rebuild. Multi-scene (miltos-5) jobs only; the source job must be in a terminal state (completed, failed, or canceled — asking a failed build to finish is a valid edit).

Request body

Example

curl -X POST https://api.motionvid.ai/v1/videos/vj_abc123/edit \
  -H "Authorization: Bearer mvk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The map in scene 2 is wrong — show only the EU member states, colored in our brand blue",
    "render": true
  }'

Returns 202 with a new job id — poll it via GET /v1/videos/{id} exactly like a created job. Credits are charged for what the edit actually regenerates: text and layout changes are cheap, regenerating AI clips bills like generation.

Capability matrix for the selectable generation models — use it to pick the model for POST /v1/videos.

Response

{
  "models": [
    {
      "id": "miltos-5",
      "label": "Miltos 5.0",
      "description": "Our most intelligent model yet",
      "multi_scene": true,
      "supports": { "narration": true, "music": true, "sfx": true, "ai_video": true },
      "duration_options": [15, 30, 60, 120],
      "max_duration_seconds": 120,
      "min_credits_to_start": 7,
      "default": true
    },
    {
      "id": "miltos-4",
      "label": "Miltos 4.0",
      "description": "High-quality single-scene infographics",
      "multi_scene": false,
      "supports": { "narration": false, "music": false, "sfx": false, "ai_video": false },
      "duration_options": [15, 30, 60],
      "max_duration_seconds": 60,
      "flat_credit_estimate": 5,
      "default": false
    }
  ]
}

Your saved brand kits for the brand_kit_id parameter. Read-only — create and edit kits in the MotionVid app (Brand Kits page).

Response

{
  "brand_kits": [
    {
      "id": "aBc123",
      "name": "Acme",
      "description": "Bold, developer-first tone",
      "website_url": "https://acme.dev",
      "colors": { "primary": "#6366F1", "secondary": "#8B5CF6", "accent": "#EC4899" },
      "fonts": { "heading": "Inter", "body": "Inter" },
      "has_logo": true
    }
  ]
}

Narration voice catalog for the narration_voice parameter (ElevenLabs premade voices). Omit narration_voice to auto-pick a voice fitting the content.

Response

{
  "voices": [
    {
      "id": "JBFqnCBsd6RMkjVDRZzb",
      "name": "George",
      "description": "Warm resonance that instantly captivates listeners.",
      "gender": "male",
      "accent": "British",
      "age": "middle_aged",
      "use_case": "narration",
      "languages": ["en", "es", "fr", "de"]
    }
  ]
}

Live catalog of visual style packs for the animation_style parameter. Styles are curated in-app, so fetch this rather than hardcoding ids. default_style is what you get when animation_style is omitted; no_style disables style guidance entirely.

Response

{
  "default_style": "taste-default",
  "no_style": "no-style",
  "styles": [
    {
      "id": "editorial-print",
      "name": "Editorial Print",
      "vibe": "Refined magazine layouts, serif headlines",
      "palette": [
        { "label": "Background", "hex": "#F7F4EE" },
        { "label": "Accent", "hex": "#C8442A" }
      ]
    }
  ]
}

MCP — Connect AI Agents

MotionVid ships a hosted Model Context Protocol server, so Claude, Claude Code, Cursor, and any MCP-compatible agent can generate videos for you. It exposes the same capabilities as this REST API: create_video, get_video_status, edit_video, preview_video, approve_video, render_video, cancel_video, list_videos, list_models, list_animation_styles, list_voices, list_brand_kits, enhance_prompt, get_credit_balance, and whoami.

Endpoint: https://motionvid.ai/mcp  (Streamable HTTP)

1. Desktop: Claude → Settings → Connectors
   Web: claude.ai/customize/connectors
2. Add custom connector
3. Name: MotionVid — URL: https://motionvid.ai/mcp
4. Click Connect and sign in with your MotionVid account

Generate a new infographic animation from a text prompt. Returns synchronously with the generated project. Pass render: true to also kick off a video render in the same call.

Request Body

Brand Settings Object

Document Object

Supported mimeType values: application/pdf, text/csv, text/plain

curl -X POST https://us-central1-motionvid-ai.cloudfunctions.net/api/v1/infographics/generate \
  -H "Authorization: Bearer mvk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Monthly revenue growth showing 45% increase",
    "dimensions": {"width": 1920, "height": 1080},
    "duration": 12,
    "brandSettings": {
      "primaryColor": "#6366F1",
      "headingFont": "Poppins",
      "brandName": "Acme Corp"
    }
  }'

Render a generated infographic to video. Returns immediately with a 202 status — the result is delivered via webhook.

curl -X POST https://us-central1-motionvid-ai.cloudfunctions.net/api/v1/infographics/abc123/render \
  -H "Authorization: Bearer mvk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "versionId": "def456",
    "dimensions": {"width": 1920, "height": 1080},
    "webhookUrl": "https://your-server.com/webhook"
  }'

List your projects, newest first. Supports cursor-based pagination.

Query Parameters

curl "https://us-central1-motionvid-ai.cloudfunctions.net/api/v1/infographics?limit=20" \
  -H "Authorization: Bearer mvk_your_key"

# Next page:
curl "https://us-central1-motionvid-ai.cloudfunctions.net/api/v1/infographics?limit=20&cursor=abc123" \
  -H "Authorization: Bearer mvk_your_key"

Get project details and all versions.

curl https://us-central1-motionvid-ai.cloudfunctions.net/api/v1/infographics/abc123 \
  -H "Authorization: Bearer mvk_your_key"

Get version details including status, settings, and the full settings schema for customization.

curl https://us-central1-motionvid-ai.cloudfunctions.net/api/v1/infographics/abc123/versions/def456 \
  -H "Authorization: Bearer mvk_your_key"

Webhooks

When a render completes or fails, we send a POST request to your webhook URL. Configure a default webhook URL when creating your API key, or pass one per-request.

Payload

{
  "event": "render.completed",
  "data": {
    "projectId": "abc123",
    "versionId": "def456",
    "renderId": "render_789",
    "url": "https://storage.googleapis.com/...",
    "dimensions": { "width": 1920, "height": 1080 },
    "fps": 30,
    "duration": 12
  },
  "timestamp": "2024-12-01T10:35:00.000Z"
}

Events

Signature Verification

Deliveries are signed two ways with your webhook secret — use whichever is easier. Recommended: the Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature) verified with any off-the-shelf library:

import { Webhook } from "standardwebhooks"; // npm i standardwebhooks

const wh = new Webhook(process.env.WEBHOOK_SECRET);
// Throws on bad signature or stale timestamp (replay protection):
const payload = wh.verify(rawBody, {
  "webhook-id": req.headers["webhook-id"],
  "webhook-timestamp": req.headers["webhook-timestamp"],
  "webhook-signature": req.headers["webhook-signature"],
});

Alternatively, the legacy X-MotionVid-Signature header carries a hex HMAC-SHA256 of the raw request body:

import crypto from 'crypto';

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-motionvid-signature'];
  const isValid = verifyWebhook(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );

  if (!isValid) return res.status(401).send('Invalid signature');

  const { event, data } = req.body;
  if (event === 'render.completed') {
    console.log('Video URL:', data.url);
  }

  res.status(200).send('OK');
});

Error Codes

All errors return a consistent JSON structure:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Monthly generation limit reached.",
    "status": 402
  }
}

Rate Limits

Rate limits are applied per API key. Exceeding them returns a 429 status.

Rate limit headers (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset) are included in every response.