Kling 3.0
curl --request POST \
--url https://whollyapi.com/api/v1/jobs/createTask \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "<string>",
"input": {
"prompt": "<string>",
"image_url": [
"<string>"
],
"duration": "<string>",
"sound": true,
"aspect_ratio": "<string>",
"multi_shots": true,
"multi_prompt": [
{
"prompt": "<string>",
"duration": 123
}
],
"kling_elements": [
{
"name": "<string>",
"description": "<string>",
"element_input_urls": [
"<string>"
],
"element_input_audio_urls": [
"<string>"
],
"start_time": 123,
"end_time": 123
}
]
}
}
'import requests
url = "https://whollyapi.com/api/v1/jobs/createTask"
payload = {
"model": "<string>",
"input": {
"prompt": "<string>",
"image_url": ["<string>"],
"duration": "<string>",
"sound": True,
"aspect_ratio": "<string>",
"multi_shots": True,
"multi_prompt": [
{
"prompt": "<string>",
"duration": 123
}
],
"kling_elements": [
{
"name": "<string>",
"description": "<string>",
"element_input_urls": ["<string>"],
"element_input_audio_urls": ["<string>"],
"start_time": 123,
"end_time": 123
}
]
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
model: '<string>',
input: {
prompt: '<string>',
image_url: ['<string>'],
duration: '<string>',
sound: true,
aspect_ratio: '<string>',
multi_shots: true,
multi_prompt: [{prompt: '<string>', duration: 123}],
kling_elements: [
{
name: '<string>',
description: '<string>',
element_input_urls: ['<string>'],
element_input_audio_urls: ['<string>'],
start_time: 123,
end_time: 123
}
]
}
})
};
fetch('https://whollyapi.com/api/v1/jobs/createTask', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://whollyapi.com/api/v1/jobs/createTask",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => '<string>',
'input' => [
'prompt' => '<string>',
'image_url' => [
'<string>'
],
'duration' => '<string>',
'sound' => true,
'aspect_ratio' => '<string>',
'multi_shots' => true,
'multi_prompt' => [
[
'prompt' => '<string>',
'duration' => 123
]
],
'kling_elements' => [
[
'name' => '<string>',
'description' => '<string>',
'element_input_urls' => [
'<string>'
],
'element_input_audio_urls' => [
'<string>'
],
'start_time' => 123,
'end_time' => 123
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://whollyapi.com/api/v1/jobs/createTask"
payload := strings.NewReader("{\n \"model\": \"<string>\",\n \"input\": {\n \"prompt\": \"<string>\",\n \"image_url\": [\n \"<string>\"\n ],\n \"duration\": \"<string>\",\n \"sound\": true,\n \"aspect_ratio\": \"<string>\",\n \"multi_shots\": true,\n \"multi_prompt\": [\n {\n \"prompt\": \"<string>\",\n \"duration\": 123\n }\n ],\n \"kling_elements\": [\n {\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"element_input_urls\": [\n \"<string>\"\n ],\n \"element_input_audio_urls\": [\n \"<string>\"\n ],\n \"start_time\": 123,\n \"end_time\": 123\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://whollyapi.com/api/v1/jobs/createTask")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"<string>\",\n \"input\": {\n \"prompt\": \"<string>\",\n \"image_url\": [\n \"<string>\"\n ],\n \"duration\": \"<string>\",\n \"sound\": true,\n \"aspect_ratio\": \"<string>\",\n \"multi_shots\": true,\n \"multi_prompt\": [\n {\n \"prompt\": \"<string>\",\n \"duration\": 123\n }\n ],\n \"kling_elements\": [\n {\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"element_input_urls\": [\n \"<string>\"\n ],\n \"element_input_audio_urls\": [\n \"<string>\"\n ],\n \"start_time\": 123,\n \"end_time\": 123\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://whollyapi.com/api/v1/jobs/createTask")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"<string>\",\n \"input\": {\n \"prompt\": \"<string>\",\n \"image_url\": [\n \"<string>\"\n ],\n \"duration\": \"<string>\",\n \"sound\": true,\n \"aspect_ratio\": \"<string>\",\n \"multi_shots\": true,\n \"multi_prompt\": [\n {\n \"prompt\": \"<string>\",\n \"duration\": 123\n }\n ],\n \"kling_elements\": [\n {\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"element_input_urls\": [\n \"<string>\"\n ],\n \"element_input_audio_urls\": [\n \"<string>\"\n ],\n \"start_time\": 123,\n \"end_time\": 123\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"code": 123,
"msg": "<string>",
"data": {
"taskId": "<string>"
}
}Kling
Kling 3.0
POST
/
api
/
v1
/
jobs
/
createTask
Kling 3.0
curl --request POST \
--url https://whollyapi.com/api/v1/jobs/createTask \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "<string>",
"input": {
"prompt": "<string>",
"image_url": [
"<string>"
],
"duration": "<string>",
"sound": true,
"aspect_ratio": "<string>",
"multi_shots": true,
"multi_prompt": [
{
"prompt": "<string>",
"duration": 123
}
],
"kling_elements": [
{
"name": "<string>",
"description": "<string>",
"element_input_urls": [
"<string>"
],
"element_input_audio_urls": [
"<string>"
],
"start_time": 123,
"end_time": 123
}
]
}
}
'import requests
url = "https://whollyapi.com/api/v1/jobs/createTask"
payload = {
"model": "<string>",
"input": {
"prompt": "<string>",
"image_url": ["<string>"],
"duration": "<string>",
"sound": True,
"aspect_ratio": "<string>",
"multi_shots": True,
"multi_prompt": [
{
"prompt": "<string>",
"duration": 123
}
],
"kling_elements": [
{
"name": "<string>",
"description": "<string>",
"element_input_urls": ["<string>"],
"element_input_audio_urls": ["<string>"],
"start_time": 123,
"end_time": 123
}
]
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
model: '<string>',
input: {
prompt: '<string>',
image_url: ['<string>'],
duration: '<string>',
sound: true,
aspect_ratio: '<string>',
multi_shots: true,
multi_prompt: [{prompt: '<string>', duration: 123}],
kling_elements: [
{
name: '<string>',
description: '<string>',
element_input_urls: ['<string>'],
element_input_audio_urls: ['<string>'],
start_time: 123,
end_time: 123
}
]
}
})
};
fetch('https://whollyapi.com/api/v1/jobs/createTask', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://whollyapi.com/api/v1/jobs/createTask",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => '<string>',
'input' => [
'prompt' => '<string>',
'image_url' => [
'<string>'
],
'duration' => '<string>',
'sound' => true,
'aspect_ratio' => '<string>',
'multi_shots' => true,
'multi_prompt' => [
[
'prompt' => '<string>',
'duration' => 123
]
],
'kling_elements' => [
[
'name' => '<string>',
'description' => '<string>',
'element_input_urls' => [
'<string>'
],
'element_input_audio_urls' => [
'<string>'
],
'start_time' => 123,
'end_time' => 123
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://whollyapi.com/api/v1/jobs/createTask"
payload := strings.NewReader("{\n \"model\": \"<string>\",\n \"input\": {\n \"prompt\": \"<string>\",\n \"image_url\": [\n \"<string>\"\n ],\n \"duration\": \"<string>\",\n \"sound\": true,\n \"aspect_ratio\": \"<string>\",\n \"multi_shots\": true,\n \"multi_prompt\": [\n {\n \"prompt\": \"<string>\",\n \"duration\": 123\n }\n ],\n \"kling_elements\": [\n {\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"element_input_urls\": [\n \"<string>\"\n ],\n \"element_input_audio_urls\": [\n \"<string>\"\n ],\n \"start_time\": 123,\n \"end_time\": 123\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://whollyapi.com/api/v1/jobs/createTask")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"<string>\",\n \"input\": {\n \"prompt\": \"<string>\",\n \"image_url\": [\n \"<string>\"\n ],\n \"duration\": \"<string>\",\n \"sound\": true,\n \"aspect_ratio\": \"<string>\",\n \"multi_shots\": true,\n \"multi_prompt\": [\n {\n \"prompt\": \"<string>\",\n \"duration\": 123\n }\n ],\n \"kling_elements\": [\n {\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"element_input_urls\": [\n \"<string>\"\n ],\n \"element_input_audio_urls\": [\n \"<string>\"\n ],\n \"start_time\": 123,\n \"end_time\": 123\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://whollyapi.com/api/v1/jobs/createTask")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"<string>\",\n \"input\": {\n \"prompt\": \"<string>\",\n \"image_url\": [\n \"<string>\"\n ],\n \"duration\": \"<string>\",\n \"sound\": true,\n \"aspect_ratio\": \"<string>\",\n \"multi_shots\": true,\n \"multi_prompt\": [\n {\n \"prompt\": \"<string>\",\n \"duration\": 123\n }\n ],\n \"kling_elements\": [\n {\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"element_input_urls\": [\n \"<string>\"\n ],\n \"element_input_audio_urls\": [\n \"<string>\"\n ],\n \"start_time\": 123,\n \"end_time\": 123\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"code": 123,
"msg": "<string>",
"data": {
"taskId": "<string>"
}
}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.
Standard Mode (
Pro Mode (
4K Mode (
Single-Shot Mode (
Multi-Shot Mode (
Use the returned
Key Features
- Multiple Generation Modes: Choose between
std(standard resolution),pro(higher resolution), and4K(ultra-high resolution) modes. - Multi-Shot Support: Create videos with multiple shots, each with its own prompt and duration.
- Element Reference: Use the
@element_namesyntax 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, and1:1aspect ratios. - Configurable Duration: Create videos with durations from 3 to 15 seconds.
Resolution Mappings
The resolution depends on both themode and aspect_ratio parameters.
Standard Mode (std)
| Aspect Ratio | Resolution |
|---|---|
16:9 | 1280×720 |
9:16 | 720×1280 |
1:1 | 720×720 |
Pro Mode (pro)
| Aspect Ratio | Resolution |
|---|---|
16:9 | 1920×1080 |
9:16 | 1080×1920 |
1:1 | 1080×1080 |
4K Mode (4K)
| Aspect Ratio | Resolution |
|---|---|
16:9 | 3840×2160 |
9:16 | 2160×3840 |
1:1 | 2160×2160 |
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
promptfield 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_promptarray 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 provideimage_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:
JPGPNG
MP4MOV
- The video duration must be at least 3 seconds.
- The effective segment length should be between 3 and 8 seconds.
- 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
| Field | Type | Required | Description |
|---|---|---|---|
model | string | Yes | The model used for video generation. |
input | object | Yes | Input parameters for the video generation task. |
string
required
Must be
kling-3.0/video.object
required
Input Parameters
Theinput 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 Single-Shot Mode (
Multi-Shot Mode (
Only the first frame is supported.
@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"
"5"boolean
Default:
falseControls whether sound effects are enabled for the generated video.true— Enables sound effects.false— Disables sound effects.
Whenmulti_shotsis set totrue, this field defaults totrue.
string
default:"16:9"
required
Specifies the aspect ratio of the generated video.
Allowed Values
16:99:161: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:9boolean
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 inmulti_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:
| Constraint | Value |
|---|---|
| Minimum | 1 |
| Maximum | 12 |
1–12 secondsobject[]
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 thekling_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:@element_dog
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 MBper 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_timemust be greater thanstart_time.- The difference between
end_timeandstart_timemust be between 3000 and 8000 milliseconds.
Usage Examples
Single-Shot Video with Element Reference
{
"model": "kling-3.0/video",
"input": {
"prompt": "In a bright rehearsal room, sunlight streams through the window @element_dog",
"image_urls": [
"https://example.com/demo/input-image.png"
],
"sound": true,
"duration": "5",
"aspect_ratio": "16:9",
"mode": "pro",
"multi_shots": false,
"kling_elements": [
{
"name": "element_dog",
"description": "dog",
"element_input_urls": [
"https://example.com/demo/dog-1.jpg",
"https://example.com/demo/dog-2.png"
]
}
]
}
}
Multi-Shot Video
{
"model": "kling-3.0/video",
"input": {
"multi_shots": true,
"image_urls": [
"https://example.com/demo/input-image.png"
],
"duration": "5",
"aspect_ratio": "16:9",
"mode": "pro",
"multi_prompt": [
{
"prompt": "A happy dog running with @element_cat",
"duration": 3
},
{
"prompt": "A happy dog playing with @element_cat",
"duration": 3
}
],
"kling_elements": [
{
"name": "element_cat",
"description": "cat",
"element_input_urls": [
"https://example.com/demo/cat-1.jpg",
"https://example.com/demo/cat-2.png"
]
},
{
"name": "element_dog",
"description": "dog",
"element_input_urls": [
"https://example.com/demo/dog-1.jpg",
"https://example.com/demo/dog-2.png"
]
}
]
}
}
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:
successobject
required
The task data object containing task id.
string
required
The unique identifier for this task.Example:
task_123456taskId 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
{
"code": 500,
"msg": "Server Error - An unexpected error occurred while processing the request",
"data": null
}
Response Codes
| Code | Meaning |
|---|---|
200 | Success — the request was successfully processed. |
401 | Unauthorized — authentication credentials are missing or invalid. |
402 | Insufficient Credits — the account does not have enough credits. |
404 | Not Found — the requested resource or interface does not exist. |
408 | Upstream service issue — no result has been returned for over 10 minutes. |
422 | Validation Error — request parameters failed validation. |
429 | Rate Limited — request frequency limit has been exceeded. |
433 | Request Limit — sub-key usage exceeded the limit. |
455 | Service Unavailable — system is undergoing maintenance. |
500 | Server Error — an unexpected error occurred while processing the request. |
501 | Generation Failed — content generation failed. |
505 | Feature Disabled — the requested feature is disabled. |
