Video Generation

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

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:

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.

Model limits

Every model takes the universal core — prompt, duration, resolution, aspect_ratio, image_url — with its own bounds. The default resolution is the one billed when you omit the field.

A parameter a model does not accept returns 400 bad_request naming the parameter — nothing is silently dropped or emulated. hailuo-2.3 accepts only 6 or 10 seconds upstream; other values inside its 6–10 range are rejected by the provider.

Parameters

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 reference video's length is read and that many seconds × the per-second rate is held (e.g. a 3s reference at 1080p → 3 × 404 = 1,212 credits). If the length cannot be read, the orientation cap is held instead (10 × 404 = 4,040 for "image"). Your balance must cover the hold.
2. On completion, the actual output length is measured and the hold is settled both ways: an unused part is refunded, and an overrun is charged before the video is released. If your balance cannot cover an overrun, the job fails with error.code: "reserve_exceeded", the hold is kept and no video is delivered — this only happens when a reference video's metadata understates its real length.
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.

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);
}