Kling 4.0 API

What it does

Kling 4.0 makes a video of 3 to 30 seconds from a prompt, keyframe images, reference images or reference videos, and edits an existing video. A request has one of two shapes. A prompt alone goes in input.prompt. Anything with media goes in input.contents: one prompt item plus image and video items, each named by its type. Settings go in input.settings. The items you send choose the mode:

Every example below is a complete body for POST /v1/generations. Send the same body to POST /v1/estimates first: it is free, creates no task, holds no Credits, and refuses an invalid body with the same 422 as a create. The https://media.vizoapi.com/... files are public samples, so the examples run as they are; replace them with your own file or an uploaded ast_... asset ID.

Modes

Text to video

Send only prompt at the top of input, never together with contents (rule prompt_or_contents). settings.aspect_ratio is 16:9, 9:16, 1:1 or 21:9, and 16:9 when you leave it out; adaptive is refused here (rule value_not_allowed), because there is no image to follow. settings.duration is 3 to 30 seconds; leave it out to let the model choose (see [Output](#output)).

{
  "model": "kling-4-0",
  "input": {
    "prompt": "A paper boat drifts across a still pond at dawn, mist on the water, slow push-in, soft natural light",
    "settings": {
      "resolution": "720p",
      "duration": 5,
      "aspect_ratio": "16:9"
    }
  }
}

First frame

The video starts on your image. contents holds exactly one prompt item (rule prompt_count) and one first_frame. Leave aspect_ratio out to keep the image's shape. The prompt describes what happens next.

{
  "model": "kling-4-0",
  "input": {
    "contents": [
      { "type": "prompt", "text": "The hominids step back as the sun rises behind the monolith, slow push-in" },
      { "type": "first_frame", "url": "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/keyframes/monolith.jpg" }
    ],
    "settings": {
      "resolution": "720p",
      "duration": 5
    }
  }
}

Keyframes

The video passes through your images in order: one first_frame, any number of middle_frame items and one last_frame. A second first_frame or last_frame is refused (rule frame_repeated). When there are two or more middle_frame items, each needs a unique id (rules content_id_required, content_id_duplicate); name them in the prompt as @id. A first_frame and last_frame alone also work.

{
  "model": "kling-4-0",
  "input": {
    "contents": [
      { "type": "prompt", "text": "The camera glides past the ring-shaped station, dives toward the black monolith at @monolith, then rises into the final wide shot" },
      { "type": "first_frame", "url": "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/keyframes/station.jpg" },
      { "type": "middle_frame", "id": "monolith", "url": "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/keyframes/monolith.jpg" },
      { "type": "last_frame", "url": "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/keyframes/ending.jpg" }
    ],
    "settings": {
      "resolution": "720p",
      "duration": 8
    }
  }
}

Reference images

Up to 10 images with type refer_image give the model characters, objects, places or a style to reuse; they do not fix any frame. Give each a unique id and cite it in the prompt as @id. An id is required when there are two or more refer_image items (rule content_id_required). Set aspect_ratio to a fixed value, or adaptive to follow your images.

{
  "model": "kling-4-0",
  "input": {
    "contents": [
      { "type": "prompt", "text": "Shot 1: @monolith stands on a savanna at dawn. Shot 2: match cut to @station tumbling slowly in black space." },
      { "type": "refer_image", "id": "monolith", "url": "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/keyframes/monolith.jpg" },
      { "type": "refer_image", "id": "station", "url": "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/keyframes/station.jpg" }
    ],
    "settings": {
      "resolution": "720p",
      "duration": 8,
      "aspect_ratio": "16:9"
    }
  }
}

Reference video

A feature_video gives the model motion, camera movement or pacing to follow for a new video. Send up to 5 videos (rule too_many_videos), each 3 to 30 seconds and 30 seconds together; several feature_video items need unique ids (rule content_id_required). Images can be added. Any video item moves the task to the -video tier of its resolution, which bills the input video's seconds too (see [How it is billed](#how-it-is-billed)).

{
  "model": "kling-4-0",
  "input": {
    "contents": [
      { "type": "prompt", "text": "Follow the camera movement and pacing of @motion, set on @station drifting past an amber planet" },
      { "type": "feature_video", "id": "motion", "url": "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/1.mp4" },
      { "type": "refer_image", "id": "station", "url": "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/keyframes/station.jpg" }
    ],
    "settings": {
      "resolution": "720p",
      "duration": 5,
      "aspect_ratio": "16:9"
    }
  }
}

Edit a video

Changes the source video: replace an object, restyle a scene, change the sky. Send it as one base_video (a second one is refused, rule frame_repeated) and say the change in the prompt. Leave duration out and the model takes the length from the source; the hold then covers 30 output seconds. Reference images can be added to show what to put in. An edit uses the -video tier like a reference video.

{
  "model": "kling-4-0",
  "input": {
    "contents": [
      { "type": "prompt", "text": "Replace the black monolith with a tall crystal obelisk; keep everything else unchanged" },
      { "type": "base_video", "url": "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/1.mp4" }
    ],
    "settings": {
      "resolution": "720p"
    }
  }
}

Input limits

A media value is a public https URL (up to 4,000 characters) or an ast_... asset ID from your project. Plain http, private or local addresses, URLs with a user name or #fragment, and Base64 data are refused with 422 (rule bad_format). The model fetches a linked file itself, possibly some time after acceptance, so keep it reachable until the task closes. See Model inputs and media.

Output

There is no watermark, seed or audio setting. A succeeded task lists one MP4 in result.outputs: take its asset_id and get a download URL with download an asset. Outputs are kept for 7 days. See Get results.

How it is billed

The input selects the tier: settings.resolution (1080p when left out) alone, or resolution plus -video when contents has any feature_video or base_video. Images never change the tier or the price, and neither does aspect_ratio.

Input seconds are the length of all input videos together, rounded up, at most 30. When a video's length cannot be read at create, the hold counts 30 input seconds. When duration is left out, the hold counts 30 output seconds. The sample video in the examples runs 12.06 seconds, so it holds 13 input seconds.

Holds at 720p:

The hold is only the estimate. A succeeded task is charged for the length of the video delivered, to the millisecond, plus the measured input on a -video tier, raised to 2 × output where that is larger, at the tier's rate. So price.charged can be below the hold (the rest is released) or above it, with no cap. When the delivered length, or on a -video tier the input length, cannot be measured, the charge is the hold. Usage above the hold comes from your available balance; what it cannot cover is owed, and new creates get 402 balance_negative until a top-up. A failed or unresolved task is not charged. Send the body to POST /v1/estimates to see the exact hold and its basis (output_seconds, input_seconds, billed_seconds, auto). See Billing.

Errors and behaviors

This model reports no reason for a failed task, so every refusal, including content safety, closes as generation_failed, never input_moderated or output_moderated. Moderation is always on; no field turns it off. Each task has a deadline of 24 hours from acceptance. A task still unfinished then closes as unresolved, releases its hold and is not charged; if its result arrives later, it is added at no charge and late_result_available becomes true. See Errors and Get results.

Prompting tips

• Give every image and video an id and cite it with @id: "keep the face of @hero", "follow the camera of @motion". The id is what links a word in the prompt to an item.
• Write the shot, not just the subject: subject, action, setting, camera movement, light and style. For several shots, number them ("Shot 1: …, Shot 2: …").
• With keyframes, describe the motion between them; the images already fix where the video starts, passes and ends.
• For an edit, say exactly what changes and what stays ("keep everything else unchanged").
• If you leave duration out, say the length you want in the prompt ("a 6-second shot"); the model reads it from there.
• Set duration when you know the length: it keeps the hold small, because a missing duration holds 30 seconds.

价格

输入决定价格档位。视频按输出秒数计费；含输入视频的档位同时计入输入秒数。

规则

• Send either prompt for text-only generation or contents for images and videos, never both.
• Exactly one prompt, up to 10 images and 5 videos (at most one base_video). Videos must be MP4/MOV, at most 300 MB each, 3–30 seconds each and at most 30 seconds total. Repeated feature_video, refer_image or middle_frame items require unique ids.
• Repeated middle_frame, refer_image or feature_video entries require unique ids, cited in the prompt as @id.
• aspect_ratio adaptive follows your input images, so it needs contents; a text-only request without aspect_ratio is 16:9.

输入字段

在 input 中发送这些字段。表中没有的字段会被拒绝，返回 HTTP 422 invalid_input。

示例

完整的创建请求、202 响应，以及任务成功后的状态。

请求

curl https://api.vizoapi.com/v1/generations \
  -H "Authorization: Bearer $VIZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "kling-4-0",
  "input": {
    "prompt": "A paper boat drifting on a pond at dawn, slow dolly in",
    "settings": {
      "resolution": "720p",
      "duration": 5,
      "aspect_ratio": "16:9"
    }
  },
  "metadata": {
    "client_reference": "my-unique-reference-1"
  }
}'

import os, requests

# Send once: do not retry this request automatically.
task = requests.post(
    "https://api.vizoapi.com/v1/generations",
    headers={"Authorization": f"Bearer {os.environ['VIZO_API_KEY']}"},
    json={
      "model": "kling-4-0",
      "input": {
        "prompt": "A paper boat drifting on a pond at dawn, slow dolly in",
        "settings": {
          "resolution": "720p",
          "duration": 5,
          "aspect_ratio": "16:9"
        }
      },
      "metadata": {
        "client_reference": "my-unique-reference-1"
      }
    },
    timeout=60,
).json()
print(task["id"], task["status"])

// Send once: do not retry this request automatically.
const res = await fetch("https://api.vizoapi.com/v1/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VIZO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "kling-4-0",
    "input": {
      "prompt": "A paper boat drifting on a pond at dawn, slow dolly in",
      "settings": {
        "resolution": "720p",
        "duration": 5,
        "aspect_ratio": "16:9"
      }
    },
    "metadata": {
      "client_reference": "my-unique-reference-1"
    }
  }),
});
const task = await res.json();
console.log(task.id, task.status);

响应

{
  "id": "gen_01JD8Z5QW3XR",
  "model": "kling-4-0",
  "source": "api",
  "created_at": "2026-11-08T09:00:00Z",
  "customer_resolution_deadline": "2026-11-09T09:00:00Z",
  "late_result_available": false,
  "metadata": {
    "client_reference": "my-unique-reference-1"
  },
  "status": "processing",
  "execution_status": "processing",
  "delivery_status": "pending",
  "billing_status": "pending",
  "version": 1,
  "price": {
    "unit": "credit",
    "estimated": "157.000",
    "reserved": "0.000",
    "charged": "0.000",
    "refunded": "0.000"
  },
  "allowed_actions": [],
  "closed_at": null,
  "error": null,
  "result": null
}

{
  "id": "gen_01JD8Z5QW3XR",
  "model": "kling-4-0",
  "source": "api",
  "created_at": "2026-11-08T09:00:00Z",
  "customer_resolution_deadline": "2026-11-09T09:00:00Z",
  "late_result_available": false,
  "metadata": {
    "client_reference": "my-unique-reference-1"
  },
  "status": "succeeded",
  "execution_status": "succeeded",
  "delivery_status": "ready",
  "billing_status": "settled",
  "version": 4,
  "price": {
    "unit": "credit",
    "estimated": "157.000",
    "reserved": "0.000",
    "charged": "157.000",
    "refunded": "0.000"
  },
  "allowed_actions": [],
  "closed_at": "2026-11-08T09:01:31Z",
  "error": null,
  "result": {
    "asset_id": "ast_01JD8Z9M2C4V",
    "outputs": [
      {
        "index": 0,
        "asset_id": "ast_01JD8Z9M2C4V",
        "content_type": "video/mp4"
      }
    ]
  }
}