KAL API · Seedance 2.5

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
  1. Quickstart
  2. Authentication
  3. Create a task
  4. Get a task
  5. Credits
  6. Errors
  7. Real faces
  8. Pricing & billing
  9. Webhooks
  10. Claude / MCP
  11. Switching from KIE
  12. Limits
  13. Not supported yet

Quickstart

  1. Create an account, sign the face-rights declaration, add credit and create a key. The key starts with kal_live_ and is shown once.
  2. Create a task. You get a taskId back at once.
  3. Read the task until state is success (about 1–4 minutes), or pass a callBackUrl and 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 returns 401 with a message saying so.
  • Keys can be set to “always confirmed” for real faces (see Real faces).

Create a task

POST/api/v1/jobs/createTask

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

FieldTypeRules
modelstringRequired. bytedance/seedance-2-5 (the alias bytedance/seedance-2.5 also works). Flash and Draft models return 505.
callBackUrlstringOptional. An http(s) URL that receives the result when the task succeeds or fails. See Webhooks.
inputobjectThe fields below.

input

FieldTypeRules
promptstringUp 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_urlsstring[]Up to 30. Each a public https:// URL or asset://…. jpeg, png or webp.
reference_video_urlsstring[]Up to 10. mp4, mov or mkv, 2–30 s each, 30 s in total. Changes the price (see billing).
reference_audio_urlsstring[]Up to 10. wav, mp3, aac or ogg, 2–30 s each, 30 s in total.
first_frame_urlstringThe video starts on this image. Cannot be combined with reference images, videos or audio.
last_frame_urlstringThe video ends on this image. Only together with first_frame_url.
resolutionstring480p, 720p or 1080p. Default 720p.
aspect_ratiostring16: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.
durationinteger4–30 seconds, or -1 to let the model choose. Default 5.
generate_audiobooleanDefault true. Audio costs nothing extra.
return_last_framebooleanDefault false. Adds a JPEG of the last frame to resultJson.lastFrameUrl.
output_formatstringmp4 (default) or mov.
omni_reference_task_typestringauto, reference, edit or extend. Only with references; edit and extend need reference_video_urls.
face_rightsbooleanKAL extension. Default false. true confirms your company holds written consent for every real person in this request’s references. See Real faces.
templatestringKAL 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

HeaderTypeRules
AuthorizationstringBearer kal_live_…. Required.
Idempotency-KeystringOptional, up to 200 characters. Retrying with the same key returns the same taskId and holds nothing twice.

Get a task

GET/api/v1/jobs/recordInfo?taskId=job_…

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".

stateKAL statusMeaning
waitingqueuedAccepted, waiting for a free slot.
queuingsubmittingBeing sent to the model.
generatingprocessingThe model is making the video.
successsucceededDone. The URL is in resultJson; the price is charged.
failfailedFailed. 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
  }
}
  • resultJson is a JSON string: {"resultUrls":[url],"lastFrameUrl":[url]} (lastFrameUrl only with return_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 failCode is 404.
  • On failure, failCode is 501 and failMsg is <error_code>: <sentence>.
  • Times are Unix milliseconds; costTime is seconds. creditsConsumed is in KIE credits; priceUsd is a KAL extra (0 on failure).

Credits

GET/api/v1/chat/credit

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.

codeNameWhen
200successThe request worked.
401unauthorizedMissing, unknown or revoked key; or the account is suspended.
402insufficient_creditThe balance can’t cover the held price. Add credit or turn on auto top-up.
422validationA 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.
429key_cap_reachedThis key reached its monthly cap. Raise it in the dashboard or use another key.
500internalSomething broke on our side. Safe to retry with the same Idempotency-Key.
505feature_disabledSeedance 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 withKindWhat to do
face_rights_requiredreal personA reference shows a real person and the request had no face rights. Confirm and send again.
…SensitiveContent…content rulesThe model refused the prompt or references. Change them.
…PolicyViolation…copyrightThe model refused for copyright reasons. Change the references or the prompt.
…OutputAudioSensitive…musicThe 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.

  1. 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.
  2. 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.
  3. 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

ResolutionPer secondWith 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 (402 if 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).

HeaderFormatSigns
X-KAL-Signaturet=<unix s>,v1=<hex>HMAC-SHA256 of <t>.<raw body> with your webhook secret. Covers the whole body. Use this one.
X-Webhook-Timestampunix secondsKIE’s header, sent so existing KIE checks keep working.
X-Webhook-Signaturebase64KIE’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

ToolTakesDoes
generate_videoprompt or templateStarts 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_videotask_idStatus, URL and cost. With wait_seconds (up to 240) it waits for the video.
quoteresolution, durationThe 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: true or 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: priceUsd on tasks, balanceUsd on credit.
  • Only Seedance 2.5 is served; see Not supported yet.

Limits

LimitValueNote
duration4–30 s, or -1Integer seconds.
prompt20,480 characters
reference_image_urls30https or asset:// URLs.
reference_video_urls1030 s in total.
reference_audio_urls1030 s in total.
Video retention14 daysThen deleted. Signed links last up to 7 days.
Idempotency-Key200 charactersSame key, same task, one hold.
MCP generate_video5 videos per callget_video waits up to 240 s.
Webhook reply10 secondsThen retried.

Not supported yet

  • bytedance/seedance-2-5-flash: returns 505.
  • bytedance/seedance-2-5-draft and input.draft: true: return 505.
  • 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.