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.
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
| Scope | Allows |
|---|---|
account:read | Account, balance, models, characters, status and download of your own videos |
assets:write | Uploading reference pictures and sound clips |
videos:read | Quotes, listing videos, status, download |
videos:write | Creating videos (charges credits) |
images:write | Creating 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": "…" } }.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | A field is missing or out of range, the message says which |
| 401 | unauthorized | No key, unknown key or revoked key |
| 402 | insufficient_credits | Not enough credits, need and have are included |
| 402 | plan_required | The model needs a higher plan |
| 402 | key_limit_reached | The key's monthly credit limit is spent |
| 403 | forbidden_scope | The key lacks the scope |
| 404 | not_found | Unknown id, or not yours |
| 409 | quote_expired · quote_exceeds_max · idempotency_conflict | Quote too old, price above max_credits, same key with a different body |
| 422 | content_blocked | The prompt or a picture failed moderation |
| 429 | rate_limited | Slow down, see Retry-After |
| 503 | model_unavailable | The 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
| Tool | What it does |
|---|---|
velumi_get_capabilities | Models, flows, resolutions, prices and the key's mode and limits |
velumi_get_balance | Credits, plan and bonus generations left |
velumi_quote_video | Exact credits for a described video, nothing charged |
velumi_prepare_video | Saves 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_status | Progress of a job by id |
velumi_get_video_download | A signed download link for a finished video |
velumi_generate_video | Starts 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]