VelumiAI
Create
Character Image Video Story
More tools
Living Worlds AI Influencer Templates Captions
Explore Pricing Rewards Affiliates · Earn 35% Developers & API FAQ
Log inStart Creating
Developers

API documentation

Everything the Video Generator does, over HTTPS. Base URL https://chrisai.online/api/v1. Requests and responses are JSON unless noted. Prices are the same credits you see in the studio, charged to the account that owns the key.

REST v1MCP · Streamable HTTP60 requests / minuteExact quotes

Authentication

Create a key in Account → Developers. Keys start with vl_live_ and are shown once. Send them as a bearer token:

curl https://chrisai.online/api/v1/account \
  -H "Authorization: Bearer vl_live_…"

Keys can be revoked at any time. A revoked key answers 401 unauthorized.

Scopes and limits

ScopeAllows
account:readAccount, balance, models, characters, status and download of your own videos
assets:writeUploading reference pictures and sound clips
videos:readQuotes, listing videos, status, download
videos:writeCreating videos (charges credits)
images:writeCreating images (charges credits)

Each key can carry a monthly credit limit. Once the key has spent that many credits in a calendar month, writes answer 402 key_limit_reached until the next month. Rate limit: 60 requests a minute per key, with X-RateLimit-Remaining on every response and 429 rate_limited plus Retry-After when it is exceeded.

GET /account

{
  "id": 1042, "email": "[email protected]",
  "plan": { "key": "plus", "name": "Plus", "rank": 3, "status": "active", "interval": "month", "renews_at": "2026-11-28T00:00:00Z" },
  "balance": 1180,
  "bonus": { "allowance": { "sheets": 10, "images": 40, "videos": 1 }, "left": { "sheets": 10, "images": 38, "videos": 1 } },
  "key": { "name": "my laptop", "scopes": ["account:read","videos:read","videos:write"], "mode": "review", "monthly_limit": 600, "used_this_month": 84 }
}

GET /models

The models switched on for your plan, with credits per second by resolution. Models above your plan rank are listed with "available": false and the plan that unlocks them.

{
  "video": [
    { "key": "seedance25", "name": "Kling 4.0", "vendor": "bytedance", "recommended": true, "available": true,
      "flows": ["text","reference","image"], "resolutions": ["480p","720p","1080p"],
      "credits_per_second": { "480p": 12.0, "720p": 6.5, "1080p": 15 },
      "seconds": { "min": 4, "max": 30 }, "aspects": ["9:16","1:1","16:9"], "max_reference_images": 30, "audio": true }
  ],
  "image": [ { "key": "nb21", "name": "Nano Banana 2.1", "resolutions": ["1K","2K","4K"], "credits": { "1K": 3, "2K": 3, "4K": 4 }, "max_reference_images": 10 } ]
}

POST /assets

Upload a reference picture (JPG, PNG, WebP up to 20 MB) or a sound clip (MP3, WAV, M4A) as multipart/form-data with a file field, or send JSON { "url": "https://…" } and we fetch it. Needs assets:write.

{ "id": 88121, "kind": "reference", "mime": "image/jpeg", "width": 1080, "height": 1920, "url": "https://chrisai.online/m/88121.…" }

GET /characters

Your saved characters that have a finished sheet. Pass their ids in character_ids on a quote and their front view is sent as a reference picture.

{ "characters": [ { "id": 311, "name": "Leo", "style": "3d", "reference_asset_id": 88002, "thumbnail_url": "…" } ] }

POST /video-quotes

An exact price, free, valid for 15 minutes. Nothing is charged.

POST /api/v1/video-quotes
{
  "model": "seedance25",
  "flow": "reference",                  // text | image | reference
  "prompt": "Leo walks through a rainy Tokyo alley, slow dolly, says \"we go again tomorrow\"",
  "seconds": 6, "resolution": "720p", "aspect": "9:16", "audio": true,
  "character_ids": [311], "reference_asset_ids": [], "image_asset_id": null
}

200 { "quote_id": "q_7f3…", "credits": 39, "seconds": 6, "resolution": "720p", "model": "Kling 4.0",
      "balance": 1180, "expires_at": "2026-10-29T18:40:00Z" }

POST /videos

Start the render. Either pass a quote_id (recommended) or the same fields as a quote. max_credits aborts with 409 quote_exceeds_max if the price is higher than you expect. Send an Idempotency-Key header to make retries safe: the same key within 24 hours returns the first response.

POST /api/v1/videos
Idempotency-Key: 5d1e…
{ "quote_id": "q_7f3…", "max_credits": 60 }

202 { "id": 90415, "status": "queued", "credits": 39, "model": "Kling 4.0", "seconds": 6, "resolution": "720p", "created_at": "…" }

Credits are reserved when the job is accepted and returned automatically if the render fails or is cancelled.

GET /videos/{id}

{ "id": 90415, "status": "done",        // queued | running | done | failed | cancelled
  "progress": 100, "credits": 39, "error": "",
  "output": { "asset_id": 88190, "duration": 6.0, "width": 720, "height": 1280,
              "url": "https://chrisai.online/m/88190.…", "download_url": "https://chrisai.online/api/v1/videos/90415/download" } }

GET /videos?limit=20&cursor=… lists your API videos newest first. POST /videos/{id}/cancel cancels a queued job and refunds it.

GET /videos/{id}/download

Redirects (302) to a signed MP4 link that works for 3 hours. Follow redirects in your client.

POST /images

POST /api/v1/images
{ "model": "nb21", "prompt": "…", "resolution": "2K", "aspect": "9:16", "num": 1, "reference_asset_ids": [88121], "character_ids": [] }

202 { "id": 90440, "status": "queued", "credits": 3 }
GET /api/v1/images/90440 → { "status": "done", "output": [ { "asset_id": 88201, "url": "…" } ] }

Errors

Every error has the shape { "error": { "code": "…", "message": "…" } }.

StatusCodeMeaning
400invalid_requestA field is missing or out of range, the message says which
401unauthorizedNo key, unknown key or revoked key
402insufficient_creditsNot enough credits, need and have are included
402plan_requiredThe model needs a higher plan
402key_limit_reachedThe key's monthly credit limit is spent
403forbidden_scopeThe key lacks the scope
404not_foundUnknown id, or not yours
409quote_expired · quote_exceeds_max · idempotency_conflictQuote too old, price above max_credits, same key with a different body
422content_blockedThe prompt or a picture failed moderation
429rate_limitedSlow down, see Retry-After
503model_unavailableThe model is off or has no route right now

MCP server

Endpoint https://chrisai.online/mcp, Streamable HTTP transport (JSON-RPC 2.0 over POST, protocol 2025-03-26). Authenticate with the same bearer key. Example client config:

{
  "mcpServers": {
    "velumi": { "url": "https://chrisai.online/mcp", "headers": { "Authorization": "Bearer vl_live_…" } }
  }
}

In Claude Desktop or Cursor add it as a remote MCP server with the URL above; in ChatGPT use the connector settings with the same URL and header.

Tools

ToolWhat it does
velumi_get_capabilitiesModels, flows, resolutions, prices and the key's mode and limits
velumi_get_balanceCredits, plan and bonus generations left
velumi_quote_videoExact credits for a described video, nothing charged
velumi_prepare_videoSaves a draft with the quote and returns a review link. You approve it in Velumi (Account → Developers → Drafts) and the render starts
velumi_get_video_statusProgress of a job by id
velumi_get_video_downloadA signed download link for a finished video
velumi_generate_videoStarts the render immediately. Only on keys in automatic mode

Review mode vs automatic

Review (default) keeps a human in the loop: the assistant can quote and prepare, you approve each draft in the studio before credits move. Automatic lets the assistant generate directly, up to the key's monthly credit limit. Switch the mode per key in Account → Developers; the change applies to the next call.

Questions or a feature you need? [email protected]