Video Generation

Generate videos from text or images asynchronously, with optional audio, resolution and aspect-ratio control.

POST/v1/videos/generations

Video generation runs asynchronously: the endpoint returns a 202 with a job.id immediately, and the video renders in the background. Poll GET /v1/jobs/:id (see Async Jobs) until status becomes completed or failed. The SDK's createAndWait(...) helper does both in one call.

Billing is per second of output and depends on the model and resolution:

ModelRates (credits / second)
seedance-2480p = 226 · 720p = 510
seedance-2-fast480p = 226 · 720p = 480
kling-v3720p = 440 (660 with audio) · 1080p = 590 (880 with audio) · 4K = 1,100
kling-v3-motion-control720p = 185 · 1080p = 320 — billed as a reserve, see below

Each model's page shows its current rates — the table above is a snapshot. If a job fails after billing (upstream error, timeout), the charged credits are automatically refunded.

Parameters

ParameterTypeRequiredDescription
modelstringYesseedance-2 (ByteDance Seedance 2.0), seedance-2-fast (ByteDance Seedance 2.0 Fast), kling-v3 (Kuaishou Kling V3) or kling-v3-motion-control (Kuaishou Kling V3 Motion Control).
promptstringYesText description of the scene and motion.
durationintegerNoSeconds — bounds vary per model: Seedance models 1–15 or -1 for auto (billed at 10s), kling-v3 3–15. Not accepted by kling-v3-motion-control (output length follows the reference video). Default 5.
resolutionstringNoPer model: Seedance models "480p"/"720p" · kling-v3 "720p"/"1080p"/"4K" · kling-v3-motion-control "720p"/"1080p".
aspect_ratiostringNo16:9, 9:16, 1:1, 4:3, 3:4, or adaptive. Default "16:9". Not accepted by kling-v3-motion-control (framing derives from the inputs).
generate_audiobooleanNoSynthesize a soundtrack (dialogue, SFX, music). Default true. Not accepted by kling-v3-motion-control — use keep_original_sound instead.
negative_promptstringNoWhat to avoid in the output. kling-v3 only.
seedintegerNoFixes output for reproducibility. Seedance models only.
image_urlstringNo*First-frame reference (HTTP URL). Enables image-to-video. *Required for kling-v3-motion-control (the character to animate).
last_frame_image_urlstringNoLast-frame target. Requires image_url. Not accepted by kling-v3-motion-control.
reference_imagesstring[]NoUp to 9 URLs. Mutually exclusive with image_url. Referenced in the prompt as [Image1], [Image2], … Seedance models only.
reference_videosstring[]NoUp to 3 URLs (combined ≤ 15 s). Referenced as [Video1], … Seedance models only.
reference_audiosstring[]NoUp to 3 URLs. Requires image_url or reference_images. Referenced as [Audio1], … Seedance models only.
reference_video_urlstringYes*kling-v3-motion-control only: 3–30s motion reference video whose movement is transferred onto the character image.
character_orientationstringNokling-v3-motion-control only: output framing follows "image" (max 10s) or "video" (max 30s). Default "image".
keep_original_soundbooleanNokling-v3-motion-control only: keep the reference video's audio track. Default true.

Motion control billing

kling-v3-motion-control has no duration parameter — sending one returns a 400. The output length is decided by the reference video (capped at 10s with character_orientation: "image", 30s with "video"), so credits are billed reserve-then-refund:

  1. At submit, the orientation cap × per-second rate is deducted from your balance (e.g. 1080p + "image" → 10 × 320 = 3,200 credits held). Your balance must cover the cap.
  2. On completion, the actual output length is measured and the unused part of the reserve is refunded automatically. A ~6-second clip at 1080p bills 7 × 320 = 2,240 credits and refunds 960.
  3. The completed job reports the net charge: tchavi.credits_used (net) and tchavi.credits_refunded, with output.duration set to the actual length. If the job fails, the full reserve is refunded.
@tchavi/sdk
const job = await client.videos.generations.createAndWait({
  model: 'kling-v3-motion-control',
  prompt: 'The character performs the dance, keeping its exact appearance',
  resolution: '1080p',
  image_url: 'https://your-host.example.com/character.png',
  reference_video_url: 'https://your-host.example.com/motion-reference.mp4',
  character_orientation: 'image', // max 10s output
  keep_original_sound: true,
  // no `duration` — output length follows the reference video
});

console.log(job.output?.duration); // actual seconds rendered
console.log(job.tchavi?.credits_used); // net charge after refund
console.log(job.tchavi?.credits_refunded); // unused part of the reserve

Example

import Tchavi from '@tchavi/sdk';

const client = new Tchavi({ apiKey: 'YOUR_API_KEY' });

// One-liner: submit + poll until completed/failed
const job = await client.videos.generations.createAndWait({
  model: 'seedance-2',
  prompt: 'A cinematic shot of the Cotonou Amazone statue at golden hour',
  duration: 5,
  resolution: '480p',
  aspect_ratio: '9:16',
  generate_audio: true,
});

if (job.status === 'completed') {
  console.log('Video URL:', job.output?.video_url);
  console.log('Credits used:', job.tchavi?.credits_used);
} else {
  console.error('Failed:', job.error?.message);
}

On this page