Skip to main content
POST
Kling 3.0
Generate high-quality videos with advanced multi-shot capabilities and element references using Kling 3.0 AI. Kling 3.0 is an advanced video generation model that supports both single-shot and multi-shot video creation with element references. It offers multiple generation modes with different resolution options and supports sound effects for enhanced video output.

Key Features

  • Multiple Generation Modes: Choose between std (standard resolution), pro (higher resolution), and 4K (ultra-high resolution) modes.
  • Multi-Shot Support: Create videos with multiple shots, each with its own prompt and duration.
  • Element Reference: Use the @element_name syntax to reference image, video, or audio elements within prompts.
  • Sound Effects: Optionally add sound effects to enhance video output.
  • Flexible Aspect Ratios: Supports 16:9, 9:16, and 1:1 aspect ratios.
  • Configurable Duration: Create videos with durations from 3 to 15 seconds.

Resolution Mappings

The resolution depends on both the mode and aspect_ratio parameters.

Standard Mode (std)

Pro Mode (pro)

4K Mode (4K)

4K mode provides higher resolution output but may take longer to generate and consume more credits.

Single-Shot vs Multi-Shot Mode

Single-Shot Mode (multi_shots: false)

  • Uses the main prompt field for video generation.
  • Supports first and last frame images via image_urls.
  • Sound effects are optional.

Multi-Shot Mode (multi_shots: true)

  • Uses the multi_prompt array to define multiple shots.
  • Each shot has its own prompt and duration of 1–12 seconds.
  • Only supports the first frame image via image_urls[0].
  • Sound effects are enabled by default.
  • The maximum number of characters per shot is 500.

Aspect Ratio Auto-Adaptation

When you provide image_urls for the first and/or last frame images, the aspect_ratio parameter becomes optional. The system automatically adapts the aspect ratio based on the uploaded images, so you don’t need to specify it manually.
If you upload reference images, you can omit the aspect_ratio parameter and let the system automatically match the aspect ratio of your images.

Element References

You can reference element in your prompts using the @element_name syntax. Define elements in the kling_elements array: Image Elements: Provide 2–4 image URLs. Supported formats:
  • JPG
  • PNG
Each image can be up to 10 MB. Video Elements: Provide up to 1 video URL. Supported formats:
  • MP4
  • MOV
Requirements:
  • The video duration must be at least 3 seconds.
  • The effective segment length should be between 3 and 8 seconds.
Audio Reference: Provide up to 1 audio URL. Requirements:
  • The audio duration must be between 5 and 30 seconds.
Use descriptive element names and ensure the element name in kling_elements matches the name used in your prompt (without the @ symbol). A single task can reference a maximum of 3 elements, and each @element will occupy 37 characters.

Request Body

string
required
Must be kling-3.0/video.
object
required

Input Parameters

The input object contains the parameters used to generate the video.
string
required
The prompt for generating a video. Used when multi_shots is set to false.
string[]
First and last frame image URLs.This field is required when elements are referenced in the prompt using the @element_name syntax.

Single-Shot Mode (multi_shots: false)

  • When the array contains 2 images:
    • image_urls[0] is the first frame.
    • image_urls[1] is the last frame.
  • When the array contains 1 image:
    • The image is used as the first frame.

Multi-Shot Mode (multi_shots: true)

Only the first frame is supported.
string
Use duration to specify the length of the total video duration in seconds.Supported values:
  • "3" to "15"
Default value: "5"
boolean
Default: falseControls whether sound effects are enabled for the generated video.
  • true — Enables sound effects.
  • false — Disables sound effects.
When multi_shots is set to true, this field defaults to true.
string
default:"16:9"
required
Specifies the aspect ratio of the generated video.

Allowed Values

  • 16:9
  • 9:16
  • 1:1
When image_urls containing first and/or last frame images is provided, this parameter becomes optional. The system automatically adapts the aspect ratio based on the uploaded images.
Default: 16:9
boolean
default:"false"
required
Whether to use multi-shot mode. true enables multi-shot mode, while false enables single-shot mode.
object[]
required
Shot prompts. Takes effect when multi_shots is true.Used to describe the text and duration of each shot. Supports up to 5 shots. Each shot duration is 1–12 seconds.

Array Item Properties

Each item in multi_prompt contains the following required properties.
string
required
Prompt text for this shot.Maximum length: 500 charactersEach @element will occupy 37 characters.
number
required
Duration of this shot in seconds.Range: 1–12 seconds
object[]
required
Referenced elements. Detailed information about elements referenced in the prompt. A single task can reference a maximum of three elements.Maximum items: 3

Element Object

Each element in the kling_elements array supports the following properties.
string
required
Element name used in the prompt with an @ prefix.For example, if the element name is element_dog, reference it in the prompt as:
string
required
Description of the element.
string[]
required
Image or video URLs used as the source material for the element.
  • 2–4 URLs are required.
  • Accepted image formats: JPG, PNG.
  • Maximum file size: 10 MB per image.
string[]
Optional list of audio material URLs for characters.The audio duration must be between 5 and 30 seconds.
number
Start time for video character material capture, specified in milliseconds.This parameter is only effective when uploading videos through element_input_urls.If no value is provided, it defaults to 0.
number
End time for video character material capture, specified in milliseconds.This parameter is only effective when uploading videos through element_input_urls.The following requirements apply:
  • end_time must be greater than start_time.
  • The difference between end_time and start_time must be between 3000 and 8000 milliseconds.

Usage Examples

Single-Shot Video with Element Reference

Multi-Shot Video

Response

Successful Response

A successful request returns a task ID.
number
Response status code.
string
Response message. Contains the error description when the request fails.Example: success
object
required
The task data object containing task id.
string
required
The unique identifier for this task.Example: task_123456
Use the returned taskId with the Get Task Details endpoint to check task progress and retrieve the generation results.

Query Task Status

After submitting a task, use the unified query endpoint to check the task progress and retrieve the generated results.

Get Task Details

Check task status, monitor generation progress, and retrieve results.

Error Response

Response Codes