Docs
One REST API that answers exactly like kie.ai’s Seedance 2.5 API, plus an MCP server for Claude. Base URL: https://kal-api-kavana-kena.vercel.app. Every request is JSON over HTTPS with a bearer key.
On this page
Quickstart
- Create an account, sign the face-rights declaration, add credit and create a key. The key starts with
kal_live_and is shown once. - Create a task. You get a
taskIdback at once. - Read the task until
stateissuccess(about 1–4 minutes), or pass acallBackUrland wait for the webhook.
curl -X POST https://kal-api-kavana-kena.vercel.app/api/v1/jobs/createTask \
-H "Authorization: Bearer $KAL_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: serum-ugc-0001" \
-d '{
"model": "bytedance/seedance-2-5",
"callBackUrl": "https://example.com/kal-webhook",
"input": {
"prompt": "Handheld phone video. The person from @image1 shows the serum from @image2 to the lens.",
"reference_image_urls": [
"https://cdn.example.com/maya.jpg",
"https://cdn.example.com/serum.png"
],
"resolution": "720p",
"aspect_ratio": "9:16",
"duration": 10,
"face_rights": true
}
}'{ "code": 200, "msg": "success", "data": { "taskId": "job_7KqP2mXv9TnRb4WcYh3s" } }curl "https://kal-api-kavana-kena.vercel.app/api/v1/jobs/recordInfo?taskId=job_7KqP2mXv9TnRb4WcYh3s" \ -H "Authorization: Bearer $KAL_KEY"
Authentication
Send your key in the Authorization header on every request, REST and MCP alike:
Authorization: Bearer kal_live_…
- Keys are shown once. We store only a hash; if you lose one, create a new one and revoke the old one.
- Every request spends from the account the key belongs to. A key can carry a monthly cap; past it, requests return
429. - A missing, unknown or revoked key returns
code: 401. A suspended account also returns401with a message saying so. - Keys can be set to “always confirmed” for real faces (see Real faces).
Create a task
The body is KIE’s: a model, an optional callBackUrl and an input object. The reply is { code: 200, msg: "success", data: { taskId } }; the price is held at that moment.
Body
| Field | Type | Rules |
|---|---|---|
| model | string | Required. bytedance/seedance-2-5 (the alias bytedance/seedance-2.5 also works). Flash and Draft models return 505. |
| callBackUrl | string | Optional. An http(s) URL that receives the result when the task succeeds or fails. See Webhooks. |
| input | object | The fields below. |
input
| Field | Type | Rules |
|---|---|---|
| prompt | string | Up to 20,480 characters. Required unless you send references or a first frame. Refer to references as @image1, @video1, @audio1; KAL rewrites them to what Seedance reads (“Image 1”). |
| reference_image_urls | string[] | Up to 30. Each a public https:// URL or asset://…. jpeg, png or webp. |
| reference_video_urls | string[] | Up to 10. mp4, mov or mkv, 2–30 s each, 30 s in total. Changes the price (see billing). |
| reference_audio_urls | string[] | Up to 10. wav, mp3, aac or ogg, 2–30 s each, 30 s in total. |
| first_frame_url | string | The video starts on this image. Cannot be combined with reference images, videos or audio. |
| last_frame_url | string | The video ends on this image. Only together with first_frame_url. |
| resolution | string | 480p, 720p or 1080p. Default 720p. |
| aspect_ratio | string | 16:9, 9:16, 1:1, 4:3, 3:4, 21:9 or adaptive. Default adaptive. First-frame, edit and extend tasks always run as adaptive. |
| duration | integer | 4–30 seconds, or -1 to let the model choose. Default 5. |
| generate_audio | boolean | Default true. Audio costs nothing extra. |
| return_last_frame | boolean | Default false. Adds a JPEG of the last frame to resultJson.lastFrameUrl. |
| output_format | string | mp4 (default) or mov. |
| omni_reference_task_type | string | auto, reference, edit or extend. Only with references; edit and extend need reference_video_urls. |
| face_rights | boolean | KAL extension. Default false. true confirms your company holds written consent for every real person in this request’s references. See Real faces. |
| template | string | KAL extension. Optional label stored with the task (for example ugc-in-hand). Over REST the prompt is yours; the MCP tool builds it from a template. |
Headers
| Header | Type | Rules |
|---|---|---|
| Authorization | string | Bearer kal_live_…. Required. |
| Idempotency-Key | string | Optional, up to 200 characters. Retrying with the same key returns the same taskId and holds nothing twice. |
Get a task
Reading a task is free. Poll every 10–15 seconds, or use a webhook. An unknown task, or one from another account, returns code: 422 with msg: "recordInfo is null".
| state | KAL status | Meaning |
|---|---|---|
| waiting | queued | Accepted, waiting for a free slot. |
| queuing | submitting | Being sent to the model. |
| generating | processing | The model is making the video. |
| success | succeeded | Done. The URL is in resultJson; the price is charged. |
| fail | failed | Failed. failMsg says why; nothing is charged. |
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_7KqP2mXv9TnRb4WcYh3s",
"model": "bytedance/seedance-2-5",
"state": "success",
"param": "{\"model\":\"bytedance/seedance-2-5\",\"input\":\"{…}\"}",
"resultJson": "{\"resultUrls\":[\"https://…/job_7KqP2mXv9TnRb4WcYh3s.mp4?token=…\"]}",
"failCode": "",
"failMsg": "",
"costTime": 94,
"completeTime": 1794931294000,
"createTime": 1794931200000,
"updateTime": 1794931294000,
"creditsConsumed": 568,
"priceUsd": 2.84
}
}resultJsonis a JSON string:{"resultUrls":[url],"lastFrameUrl":[url]}(lastFrameUrlonly withreturn_last_frame).- Video URLs are signed links valid for up to 7 days. Read the task again for a fresh link. Videos are deleted after 14 days; after that
failCodeis404. - On failure,
failCodeis501andfailMsgis<error_code>: <sentence>. - Times are Unix milliseconds;
costTimeis seconds.creditsConsumedis in KIE credits;priceUsdis a KAL extra (0 on failure).
Credits
Your balance in KIE’s credit unit, so existing balance checks keep working: 1 USD = 200 credits. balanceUsd is a KAL extra.
{ "code": 200, "msg": "success", "data": 1700, "balanceUsd": 8.5 }Errors
Like KIE, every /api/v1 response is HTTP 200. The outcome is the body’s code; msg is a sentence you can show. Always check code.
| code | Name | When |
|---|---|---|
| 200 | success | The request worked. |
| 401 | unauthorized | Missing, unknown or revoked key; or the account is suspended. |
| 402 | insufficient_credit | The balance can’t cover the held price. Add credit or turn on auto top-up. |
| 422 | validation | A field is wrong: invalid model, prompt, resolution, duration, aspect ratio, URL, too many references, a mode combination that can’t be mixed, a bad callBackUrl, or an unknown task. |
| 429 | key_cap_reached | This key reached its monthly cap. Raise it in the dashboard or use another key. |
| 500 | internal | Something broke on our side. Safe to retry with the same Idempotency-Key. |
| 505 | feature_disabled | Seedance 2.5 Flash, Draft mode, or another feature KAL doesn’t offer yet. |
A task that was accepted and then failed is not an HTTP error: it ends in state: "fail" with failCode: "501". Common reasons in failMsg:
| failMsg starts with | Kind | What to do |
|---|---|---|
| face_rights_required | real person | A reference shows a real person and the request had no face rights. Confirm and send again. |
| …SensitiveContent… | content rules | The model refused the prompt or references. Change them. |
| …PolicyViolation… | copyright | The model refused for copyright reasons. Change the references or the prompt. |
| …OutputAudioSensitive… | music | The audio looked like copyrighted music. Remove it, or set generate_audio: false. |
Every failure message ends with “Nothing was charged.”, because nothing was.
Real faces
Seedance refuses reference images of real people unless the rights are cleared. KAL clears them for people your company holds written consent for.
- At signup your company signs the rights declaration: written consent from every real person you send, never minors or public figures, and responsibility for the faces you send.
- Each request confirms it with
input.face_rights: true, or the key (or the whole account) is set to always confirmed in the dashboard. A key’s own setting wins over the account’s. - KAL first sends the task as is. If the model sees a real person and the request is confirmed, the images go into your account’s private library at the provider and the task runs. The confirmation is recorded with the declaration version.
Without rights, a task with a real face fails at $0 with failMsg starting face_rights_required. Nothing is held after that; send it again with face_rights: true.
The Acceptable Use Policy applies: no minors, no public figures, no one without consent, no deception.
Pricing & billing
| Resolution | Per second | With a reference video |
|---|---|---|
| 480p | $0.126 | $0.0765 / s |
| 720p | $0.284 | $0.171 / s |
| 1080p | $0.711 | $0.4275 / s |
- Hold → charge. When a task is created, its price is held from your balance (
402if it can’t be). When it succeeds the hold is charged; when it fails the hold is released and you pay $0. - Seconds. Billed per whole second of output, 4 s minimum. A 10 s 720p video is $2.84.
- Auto length (
duration: -1) holds 30 s and settles on the seconds the model actually made, never more than the hold. - Reference video. Billed at the reference-video rate on (reference seconds + output seconds). The hold adds 30 s for the references and settles on what the provider actually billed.
- Reference images and audio add nothing. Audio output adds nothing.
- Volume over $10K a month: lower rates, paid by bank transfer.
Webhooks
With a callBackUrl, KAL POSTs the result when the task succeeds or fails. The body is KIE’s callback: code 200 ("Playground task completed successfully.") or 501 ("Playground task failed."), and data is the same object recordInfo returns (creditsConsumed: 0 on failure).
| Header | Format | Signs |
|---|---|---|
| X-KAL-Signature | t=<unix s>,v1=<hex> | HMAC-SHA256 of <t>.<raw body> with your webhook secret. Covers the whole body. Use this one. |
| X-Webhook-Timestamp | unix seconds | KIE’s header, sent so existing KIE checks keep working. |
| X-Webhook-Signature | base64 | KIE’s signature: HMAC-SHA256 of taskId + "." + timestamp with the same secret. Does not cover the body. |
Your webhook secret is in the dashboard. Reply with any 2xx within 10 seconds. Otherwise KAL retries after 1 min, 5 min, 30 min, 2 h and 6 h, then gives up; every attempt is visible on the task in the dashboard.
import { createHmac, timingSafeEqual } from 'node:crypto';
// Verify X-KAL-Signature against the RAW request body (before JSON.parse).
export function verifyKal(rawBody, header, secret, toleranceSeconds = 300) {
const m = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header ?? '');
if (!m) return false;
const t = Number(m[1]);
if (Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
return timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]));
}
// KIE's headers are sent too, so an existing KIE check keeps working:
// X-Webhook-Signature = base64(HMAC-SHA256(taskId + "." + X-Webhook-Timestamp, secret))
export function verifyKie(taskId, timestamp, signature, secret) {
const expected = createHmac('sha256', secret).update(`${taskId}.${timestamp}`).digest('base64');
if (expected.length !== signature.length) return false;
return timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}Claude / MCP
KAL is an MCP server at https://kal-api-kavana-kena.vercel.app/mcp (Streamable HTTP). Every tool spends from the key in the header.
Claude Code
claude mcp add --transport http kal https://kal-api-kavana-kena.vercel.app/mcp \ --header "Authorization: Bearer kal_live_…"
Claude Desktop
Through mcp-remote, in claude_desktop_config.json:
{
"mcpServers": {
"kal": {
"command": "npx",
"args": [
"-y", "mcp-remote", "https://kal-api-kavana-kena.vercel.app/mcp",
"--header", "Authorization:${KAL_AUTH}"
],
"env": { "KAL_AUTH": "Bearer kal_live_…" }
}
}
}Tools
| Tool | Takes | Does |
|---|---|---|
| generate_video | prompt or template | Starts 1–5 videos (count). Takes a prompt, or a template plus template_fields, and the same references, resolution, aspect_ratio, duration, generate_audio and face_rights as REST. Defaults: the template’s, else 720p, 9:16, 10 s. Returns task ids. |
| get_video | task_id | Status, URL and cost. With wait_seconds (up to 240) it waits for the video. |
| quote | resolution, duration | The price on KAL and on KIE before you generate. Optional count (up to 50) and has_reference_video. |
| balance | — | The account’s credit and this key’s monthly cap. |
| list_templates | — | The e-commerce templates (ugc-in-hand, unboxing, hero-shot) and the fields each needs. |
Then just ask: “Make 3 UGC videos of our serum with @maya, 9:16, 720p, label readable.”
Switching from KIE
Change the base URL and the key. The endpoints, bodies, responses and callbacks stay the same.
- const BASE = 'https://api.kie.ai'; - const KEY = process.env.KIE_API_KEY; + const BASE = 'https://kal-api-kavana-kena.vercel.app'; + const KEY = process.env.KAL_API_KEY;
What is different:
- Task ids look like
job_…. - Real faces work, with
face_rights: trueor an always-confirmed key. - Webhooks are always signed, with KIE’s headers and
X-KAL-Signature, using your KAL webhook secret. - Extras you can ignore:
priceUsdon tasks,balanceUsdon credit. - Only Seedance 2.5 is served; see Not supported yet.
Limits
| Limit | Value | Note |
|---|---|---|
| duration | 4–30 s, or -1 | Integer seconds. |
| prompt | 20,480 characters | |
| reference_image_urls | 30 | https or asset:// URLs. |
| reference_video_urls | 10 | 30 s in total. |
| reference_audio_urls | 10 | 30 s in total. |
| Video retention | 14 days | Then deleted. Signed links last up to 7 days. |
| Idempotency-Key | 200 characters | Same key, same task, one hold. |
| MCP generate_video | 5 videos per call | get_video waits up to 240 s. |
| Webhook reply | 10 seconds | Then retried. |
Not supported yet
bytedance/seedance-2-5-flash: returns505.bytedance/seedance-2-5-draftandinput.draft: true: return505.web_search: accepted and ignored.nsfw_checker: accepted and ignored. The model’s own content rules still apply.- KIE’s other endpoints (file upload, download-url): not offered. Send public https URLs.