API Reference

Generate and render infographics programmatically. All endpoints require an API key with an Ultimate or Creator plan.

Base URL: https://us-central1-motionvid-ai.cloudfunctions.net/api

Version: v1

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.

POST/v1/infographics/generate

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

Parameter	Type	Description
`prompt`*	string	Description of the infographic to generate
`dimensions`	{width, height}	Canvas size in pixels. Default: 1280x720
`duration`	number	Animation duration in seconds. Default: 15
`animationStyle`	string	Animation style preset
`backgroundColor`	string	Hex color for background. Default: auto-detected
`brandSettings`	object	Brand colors, fonts, and visual style
`images`	array	Reference images [{url, context}]
`webhookUrl`	string	URL to receive render completion webhooks
`render`	boolean	If true, immediately starts a render after generation. Result is delivered via webhook.

Brand Settings Object

Parameter	Type	Description
`primaryColor`	string	Primary brand color (hex)
`secondaryColor`	string	Secondary brand color (hex)
`accentColor`	string	Accent color (hex)
`headingFont`	string	Google Font name for headings
`bodyFont`	string	Google Font name for body text
`visualStyle`	"2d" \| "3d"	Visual style of the infographic
`brandName`	string	Brand name to display

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"
    }
  }'

POST/v1/infographics/:id/render

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

Parameter	Type	Description
`versionId`*	string	Version ID from the generate response
`dimensions`	{width, height}	Render resolution. Default: matches generation
`fps`	number	Frames per second. Default: 30
`webhookUrl`	string	Override the default webhook URL for this render
`settingsValues`	object	Override individual settings for this render (colors, text, fonts, etc). Keys must match those in the version's settingsSchema. Merged with stored defaults.

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"
  }'

GET/v1/infographics

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

Query Parameters

Parameter	Type	Description
`limit`	number	Results per page (max 100, default 20)
`cursor`	string	Project ID to paginate from (use nextCursor from previous response)

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/v1/infographics/:id

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/v1/infographics/:id/versions/:versionId

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/..."
  },
  "timestamp": "2024-12-01T10:35:00.000Z"
}

Events

Event	Description
`render.completed`	Render finished. Includes `url` to the video file.
`render.failed`	Render failed. Includes `error` message. Credits are automatically refunded.

Signature Verification

Every webhook includes an X-MotionVid-Signature header containing an HMAC-SHA256 signature of the request body, signed with your webhook secret.

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');
});

Retry policy: Failed deliveries are retried 3 times with exponential backoff (1s, 5s, 25s). Return a 2xx status to acknowledge receipt.

Error Codes

All errors return a consistent JSON structure:

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

Status	Code	Description
400	`invalid_request`	Missing or invalid request parameters
401	`unauthorized`	Missing, invalid, or revoked API key
402	`insufficient_credits`	Monthly usage limit reached
403	`forbidden`	Plan does not include API access
429	`rate_limited`	Too many requests (see Rate Limits)
500	`internal_error`	Server error — retry or contact support

Rate Limits

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

Endpoint	Limit
All endpoints	60 requests / minute
POST /v1/infographics/generate	10 requests / minute

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