Keyvello API & Agents

Overview

The Keyvello API turns a prompt into a finished vertical video: script, AI images or footage, narration, captions, and a rendered MP4. Everything the web app can do is being exposed here, endpoint by endpoint.

It is built for two kinds of caller. First, AI agents — Claude Code, Claude Desktop, Cursor, or your own chatbot — talking to Keyvello through the MCP server so "make me a 60-second video about the Roman Empire" just works. Second, scripts and backends that want to batch-produce content on a schedule.

Base URL:

https://www.keyvello.com/api/v1

Requests and responses are JSON. Every field name is camelCase. Credits are spent from the same balance as the web app, so an API render and a dashboard render are billed identically.

Authentication

Create a key at /dashboard/api-keys. Keys look like kv_live_.... Pass one on every request — the canonical form is a bearer token:

Authorization: Bearer kv_live_xxxxxxxxxxxxxxxxxxxxxxxx

The x-api-key header is also accepted as a shorthand for clients that cannot set Authorization:

x-api-key: kv_live_xxxxxxxxxxxxxxxxxxxxxxxx

• Keys are hashed at rest (SHA-256). We store only the hash and a short display prefix, so a database leak never leaks a usable credential.
• The plaintext key is shown exactly once, at creation. Copy it then — it cannot be recovered afterwards, only revoked and replaced.
• A key carries your full account permissions and spends your credits. Keep it server-side: never ship it in a browser bundle, mobile app, or public repo.
• Revoke a key from the dashboard the moment it leaks. Revocation takes effect on the next request.

A missing or invalid key returns 401 with code UNAUTHORIZED.

Quickstart

Three calls: check your balance, queue a video, poll until it is ready.

1. Check your credits

curl https://www.keyvello.com/api/v1/credits \
  -H "Authorization: Bearer $KEYVELLO_API_KEY"

{
  "credits": 132,
  "plan": "starter"
}

2. Create a video Shipping shortly

Video creation over the API is shipping shortly — the read endpoints below are live today, and POST /api/v1/videos lands next. The request shape is frozen and documented here so you can build against it now.

curl -X POST https://www.keyvello.com/api/v1/videos \
  -H "Authorization: Bearer $KEYVELLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "faceless_shorts",
    "input": { "type": "topic", "content": "3 facts about deep sea creatures" },
    "durationSeconds": 60,
    "voiceId": "openai-cedar",
    "imageStyle": "cinematic",
    "captions": true
  }'

The call returns as soon as the job is queued — it does not wait for the render.

{
  "id": "8f14e45f-ceea-467a-9b3c-2b1f0d6e77aa",
  "status": "queued",
  "creditsUsed": 20
}

3. Poll until it is ready

curl https://www.keyvello.com/api/v1/videos/8f14e45f-ceea-467a-9b3c-2b1f0d6e77aa \
  -H "Authorization: Bearer $KEYVELLO_API_KEY"

{
  "id": "8f14e45f-ceea-467a-9b3c-2b1f0d6e77aa",
  "status": "ready",
  "progress": 100,
  "statusMessage": null,
  "videoUrl": "https://cdn.keyvello.com/videos/8f14e45f.mp4",
  "thumbnailUrl": "https://cdn.keyvello.com/thumbs/8f14e45f.jpg",
  "duration": 58.4,
  "template": "faceless_shorts",
  "title": "3 Facts About Deep Sea Creatures",
  "creditsUsed": 20,
  "createdAt": "2026-08-04T11:02:44.812Z"
}

Poll every 3-5 seconds. A typical render takes 2-5 minutes. When status is ready, call the download endpoint for a file URL (paid plans only).

Endpoints reference

All paths are relative to https://www.keyvello.com/api/v1. Every response — success or error — carries the rate-limit headers described in Rate limits.

curl https://www.keyvello.com/api/v1/credits \
  -H "Authorization: Bearer $KEYVELLO_API_KEY"

{
  "credits": 132,
  "plan": "starter"
}

curl https://www.keyvello.com/api/v1/voices \
  -H "Authorization: Bearer $KEYVELLO_API_KEY"

{
  "voices": [
    {
      "id": "openai-cedar",
      "name": "Cedar",
      "gender": "male",
      "accent": "American",
      "provider": "openai",
      "requiresPaidPlan": false
    },
    {
      "id": "pNInz6obpgDQGcFmaJgB",
      "name": "Adam",
      "gender": "male",
      "accent": "American",
      "provider": "elevenlabs",
      "requiresPaidPlan": true
    }
  ]
}

curl https://www.keyvello.com/api/v1/templates \
  -H "Authorization: Bearer $KEYVELLO_API_KEY"

{
  "templates": [
    {
      "id": "faceless_shorts",
      "name": "AI Stories",
      "description": "Vertical faceless short (30-90s) built from AI images or gameplay footage, with AI narration and word-level captions. The default Keyvello template.",
      "status": "available",
      "params": {
        "input": "{ type: 'topic' | 'script', content: string } — required. ...",
        "durationSeconds": "30 | 60 | 90 (default 30). Ignored when a full script is supplied.",
        "voiceId": "Voice id from GET /api/v1/voices (e.g. 'openai-cedar'). ..."
      },
      "creditsHint": "10-27 credits for 30-90s at base quality"
    }
  ]
}

curl "https://www.keyvello.com/api/v1/videos?limit=2&status=ready" \
  -H "Authorization: Bearer $KEYVELLO_API_KEY"

{
  "videos": [
    {
      "id": "8f14e45f-ceea-467a-9b3c-2b1f0d6e77aa",
      "status": "ready",
      "progress": 100,
      "statusMessage": null,
      "videoUrl": "https://cdn.keyvello.com/videos/8f14e45f.mp4",
      "thumbnailUrl": "https://cdn.keyvello.com/thumbs/8f14e45f.jpg",
      "duration": 58.4,
      "template": "faceless_shorts",
      "title": "3 Facts About Deep Sea Creatures",
      "creditsUsed": 20,
      "createdAt": "2026-08-04T11:02:44.812Z"
    }
  ],
  "hasMore": true
}

curl https://www.keyvello.com/api/v1/videos/8f14e45f-ceea-467a-9b3c-2b1f0d6e77aa \
  -H "Authorization: Bearer $KEYVELLO_API_KEY"

{
  "id": "8f14e45f-ceea-467a-9b3c-2b1f0d6e77aa",
  "status": "generating",
  "progress": 45,
  "statusMessage": "Rendering scenes",
  "videoUrl": null,
  "thumbnailUrl": null,
  "duration": null,
  "template": "faceless_shorts",
  "title": "3 Facts About Deep Sea Creatures",
  "creditsUsed": 20,
  "createdAt": "2026-08-04T11:02:44.812Z"
}

curl "https://www.keyvello.com/api/v1/videos/8f14e45f-ceea-467a-9b3c-2b1f0d6e77aa/download?aspect=portrait" \
  -H "Authorization: Bearer $KEYVELLO_API_KEY"

{
  "url": "https://cdn.keyvello.com/videos/8f14e45f-portrait.mp4",
  "aspect": "portrait"
}

HTTP/1.1 402 Payment Required

{
  "error": "Upgrade to a paid plan to download videos.",
  "code": "PAYMENT_REQUIRED",
  "details": { "pricingUrl": "https://www.keyvello.com/pricing" }
}

curl -X POST https://www.keyvello.com/api/v1/videos \
  -H "Authorization: Bearer $KEYVELLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "faceless_shorts",
    "input": { "type": "topic", "content": "3 facts about deep sea creatures" },
    "durationSeconds": 60,
    "voiceId": "openai-cedar",
    "imageStyle": "cinematic",
    "aspectRatio": "portrait",
    "qualityTier": "base",
    "captions": true
  }'

{
  "id": "8f14e45f-ceea-467a-9b3c-2b1f0d6e77aa",
  "status": "queued",
  "creditsUsed": 20
}

Templates

Rendered from the same catalog GET /api/v1/templates serves, so this page can never drift from the API. Credit hints are estimates — the real cost comes back on the create call.

Available

Coming soon

These templates exist in the Keyvello app today but are not exposed through the public API yet. They are listed so you can plan around the roadmap; their parameters are published when each one opens up.

Video lifecycle

draft → queued → generating → processing → ready
                              ↘ failed

• Poll GET /api/v1/videos/{id} every 3-5 seconds. Anything faster just burns your 60 req/min budget.
• A typical render finishes in 2-5 minutes. Longer formats and higher quality tiers take longer.
• Failed generations refund their credits automatically — do not build your own refund logic on top.

Errors

Every error uses the same JSON shape. details is optional and its contents depend on the code.

{
  "error": "Insufficient credits",
  "code": "INSUFFICIENT_CREDITS",
  "details": { "required": 20, "available": 6 }
}

Branch on code, not on the human-readable error string — messages get reworded, codes do not.

Rate limits

• 60 requests per minute per API key across all of /api/v1 and /api/mcp. The budget is keyed to the key, not the account — a runaway integration only throttles itself.
• Video creation is additionally limited to 5 per minute per user, and that budget is shared with the web app: renders you start in the dashboard count against the same 5.

Every response carries the current state of your budget:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1785926400
Retry-After: 17

{
  "error": "Too many requests. Please try again later.",
  "code": "RATE_LIMITED",
  "details": { "retryAfter": 17, "reset": "2026-08-04T11:20:00.000Z" }
}

MCP (Claude & other agents)

The Model Context Protocol server gives an AI assistant direct access to Keyvello. Ask for "a 60-second faceless video about the Roman Empire" and it picks a voice, queues the render, polls until it is done, and hands back the download link.

Remote server (no install) Shipping shortly

If your client supports remote MCP servers, skip the local process entirely and connect to https://www.keyvello.com/api/mcp with an Authorization header.

claude mcp add --transport http keyvello https://www.keyvello.com/api/mcp \
  --header "Authorization: Bearer kv_live_xxx"

Local server (npx)

Runs the keyvello-mcp package locally. Requires Node.js 20 or newer. No install step — npx fetches it on demand.

Claude Code

claude mcp add keyvello -e KEYVELLO_API_KEY=kv_live_xxx -- npx -y keyvello-mcp

Claude Desktop

Edit claude_desktop_config.json — on macOS ~/Library/Application Support/Claude/claude_desktop_config.json, on Windows %APPDATA%\Claude\claude_desktop_config.json — then restart Claude Desktop.

{
  "mcpServers": {
    "keyvello": {
      "command": "npx",
      "args": ["-y", "keyvello-mcp"],
      "env": {
        "KEYVELLO_API_KEY": "kv_live_xxx"
      }
    }
  }
}

Cursor

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json inside a project.

{
  "mcpServers": {
    "keyvello": {
      "command": "npx",
      "args": ["-y", "keyvello-mcp"],
      "env": {
        "KEYVELLO_API_KEY": "kv_live_xxx"
      }
    }
  }
}

Environment variables

Tools

• create_video returns as soon as the job is queued — have the agent poll get_video_status roughly every 15 seconds.
• For faceless_shorts pass exactly one of topic or script.
• Other templates take different fields: call list_templates, then pass them through create_video's extraParams object — it is shallow-merged over the request body.

CLI

The keyvello CLI wraps the same API for terminals, cron jobs, and shell scripts. Requires Node.js 20 or newer.

npm i -g keyvello

# 1. Save your API key (create one at /dashboard/api-keys)
keyvello login

# 2. See what a video will cost before spending credits
keyvello create --template faceless_shorts --topic "3 facts about deep sea creatures" --estimate

# 3. Create it and wait for the render
keyvello create --template faceless_shorts --topic "3 facts about deep sea creatures" --duration 60 --wait

# 4. Download it
keyvello download 8f14e45f-ceea-467a-9b3c-2b1f0d6e77aa -o deep-sea.mp4

Commands

Environment variables

KEYVELLO_API_KEY takes priority over the saved config file; KEYVELLO_API_URL overrides the base URL. With neither a key nor a config file, the CLI tells you to run keyvello login and exits 1.