Kling AI API Examples

Kling models must be called over HTTP rather than through the OpenAI SDK. Based on the local klingai-api.html bundle and the referenced parameter spec, the recommended endpoints are Text to Video, Image to Video, Motion Control, and Omni Video.

Basic Configuration

Before using the API, make sure you already have an API key. If not, please see Create API Key.

Request Information

API Base URL: https://api.agentsflare.com
Authentication: Authorization: Bearer <API_KEY>
Content Type: application/json

Vendor reference: Kling parameter reference (original): https://zhipu-ai.feishu.cn/wiki/FcKlwx326iYa5fkZ9dscba8KnCf

Capability / Model Matrix

Capability	Path	Recommended Models	Notes
Text to Video	`/klingai/v1/videos/text2video`	`kling-v3`	Generate a video from a prompt
Image to Video	`/klingai/v1/videos/image2video`	`kling-v3`	Generate from a keyframe or start/end frames
Motion Control	`/klingai/v1/videos/motion-control`	`kling-v3-motion-control`	Drive the subject with a reference video
Omni Video	`/klingai/v1/videos/omni-video`	`kling-v3-omni`	Continuation, multi-shot, element/video reference
Task Query	`GET /klingai/v1/videos/<endpoint>/{id}`	-	Poll task status and final result

Common Headers

http

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

Common Fields

Field	Type	Description
`model_name`	string	Model name
`prompt`	string	Main prompt describing subject, motion, camera, and lighting
`negative_prompt`	string	Negative prompt, often left empty
`duration`	number	Common values are `5` or `10`
`mode`	string	Quality mode, commonly `std` or `pro`
`aspect_ratio`	string	For example `16:9`, `9:16`, or `1:1`
`sound`	string	Whether to keep/generate audio, commonly `off`
`callback_url`	string	Optional async callback URL
`external_task_id`	string	Optional business-side tracking ID

Note: older examples on this site use Base64 images for image2video, while the current bundled spec also shows public image / image_tail URLs. Use whichever format is enabled on your gateway.

Text to Video

Use this endpoint when you want to generate a short video directly from a text prompt.

Main Parameters

Parameter	Required	Description
`model_name`	Yes	Recommended: `kling-v3`
`prompt`	Yes	Describe the scene and motion
`negative_prompt`	No	Undesired content
`duration`	Yes	Example: `5`
`mode`	No	`pro` gives higher quality
`sound`	No	Start with `off`
`aspect_ratio`	No	Such as `16:9`

cURLNode.jsPythonJava

bash

curl -X POST "https://api.agentsflare.com/klingai/v1/videos/text2video" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "kling-v3",
    "prompt": "A cute little rabbit running on the road fast as a racing car",
    "negative_prompt": "",
    "duration": 5,
    "mode": "pro",
    "sound": "off",
    "aspect_ratio": "1:1",
    "callback_url": "",
    "external_task_id": ""
  }'

javascript

const response = await fetch('https://api.agentsflare.com/klingai/v1/videos/text2video', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model_name: 'kling-v3',
    prompt: 'A cute little rabbit running on the road fast as a racing car',
    negative_prompt: '',
    duration: 5,
    mode: 'pro',
    sound: 'off',
    aspect_ratio: '1:1',
    callback_url: '',
    external_task_id: ''
  })
});

console.log(await response.json());

python

import os
import requests

API_BASE = 'https://api.agentsflare.com/klingai/v1/videos/text2video'
API_KEY = os.getenv('API_KEY')

payload = {
  'model_name': 'kling-v3',
  'prompt': 'A cute little rabbit running on the road fast as a racing car',
  'negative_prompt': '',
  'duration': 5,
  'mode': 'pro',
  'sound': 'off',
  'aspect_ratio': '1:1'
}

headers = {'Authorization': f'Bearer {API_KEY}', 'Content-Type': 'application/json'}
resp = requests.post(API_BASE, json=payload, headers=headers)
print(resp.status_code)
print(resp.text)

java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class KlingText2V {
  public static void main(String[] args) throws Exception {
    String apiBase = "https://api.agentsflare.com/klingai/v1/videos/text2video";
    String apiKey = System.getenv("API_KEY");
    String json = "{\"model_name\":\"kling-v3\",\"prompt\":\"A cute little rabbit running on the road fast as a racing car\",\"negative_prompt\":\"\",\"duration\":5,\"mode\":\"pro\",\"sound\":\"off\",\"aspect_ratio\":\"1:1\"}";

    HttpRequest req = HttpRequest.newBuilder()
      .uri(URI.create(apiBase))
      .header("Authorization", "Bearer " + apiKey)
      .header("Content-Type", "application/json")
      .POST(HttpRequest.BodyPublishers.ofString(json))
      .build();

    HttpResponse<String> resp = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
    System.out.println(resp.statusCode());
    System.out.println(resp.body());
  }
}

Response Example

json

{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "2026040901144560ed39e7182144d8"
  }
}

Image to Video

Use this endpoint to animate a still image. You can also pass image_tail for a start/end frame transition workflow.

Main Parameters

Parameter	Required	Description
`model_name`	Yes	Recommended: `kling-v3`
`image`	Yes	Public image URL or image content supported by your gateway
`image_tail`	No	Optional end frame
`prompt`	Yes	Motion / camera instructions
`duration`	Yes	Example: `5`
`mode`	No	`std` / `pro`
`sound`	No	Usually `off`

cURLNode.jsPythonJava

bash

curl -X POST "https://api.agentsflare.com/klingai/v1/videos/image2video" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "kling-v3",
    "image": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-2.png",
    "image_tail": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-1.png",
    "prompt": "Camera zooms out, the girl smiles",
    "negative_prompt": "",
    "duration": 5,
    "mode": "pro",
    "sound": "off",
    "callback_url": "",
    "external_task_id": ""
  }'

javascript

const payload = {
  model_name: 'kling-v3',
  image: process.env.KLING_IMAGE_URL,
  image_tail: process.env.KLING_IMAGE_TAIL_URL || '',
  prompt: 'Camera zooms out, the girl smiles',
  negative_prompt: '',
  duration: 5,
  mode: 'pro',
  sound: 'off',
  callback_url: '',
  external_task_id: ''
};

const response = await fetch('https://api.agentsflare.com/klingai/v1/videos/image2video', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

console.log(await response.json());

python

import os
import requests

API_BASE = 'https://api.agentsflare.com/klingai/v1/videos/image2video'
API_KEY = os.getenv('API_KEY')

payload = {
  'model_name': 'kling-v3',
  'image': 'https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-2.png',
  'image_tail': 'https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-1.png',
  'prompt': 'Camera zooms out, the girl smiles',
  'duration': 5,
}

headers = {'Authorization': f'Bearer {API_KEY}', 'Content-Type': 'application/json'}
resp = requests.post(API_BASE, json=payload, headers=headers)
print(resp.status_code)
print(resp.text)

java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class KlingImage2V {
  public static void main(String[] args) throws Exception {
    String apiBase = "https://api.agentsflare.com/klingai/v1/videos/image2video";
    String apiKey = System.getenv("API_KEY");
    String json = "{\"model_name\":\"kling-v3\",\"image\":\"https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-2.png\",\"image_tail\":\"https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-1.png\",\"prompt\":\"Camera zooms out, the girl smiles\",\"duration\":5}";

    HttpRequest req = HttpRequest.newBuilder()
      .uri(URI.create(apiBase))
      .header("Authorization", "Bearer " + apiKey)
      .header("Content-Type", "application/json")
      .POST(HttpRequest.BodyPublishers.ofString(json))
      .build();

    HttpResponse<String> resp = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
    System.out.println(resp.statusCode());
    System.out.println(resp.body());
  }
}

Motion Control

kling-v2-6 is suitable for scenarios like “character image + reference motion video”.

Recommended Parameters

Parameter	Required	Description
`model_name`	Yes	`kling-v3-motion-control`
`image_url`	Yes	Subject / character image
`video_url`	Yes	Motion reference video
`prompt`	No	Extra styling or scene instructions
`keep_original_sound`	No	`yes` / `no`
`character_orientation`	No	Example value: `image`
`mode`	No	Recommended: `pro`

bash

curl -X POST "https://api.agentsflare.com/klingai/v1/videos/motion-control" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "kling-v3-motion-control",
    "image_url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-3.ng.png",
    "video_url": "https://your-public-video.mp4",
    "prompt": "The girl is wearing a loose gray T-shirt and denim shorts",
    "keep_original_sound": "yes",
    "character_orientation": "image",
    "mode": "pro",
    "callback_url": "",
    "external_task_id": "demo-motion-001"
  }'

Omni Video

kling-v3-omni is designed for advanced workflows such as continuation, multi-shot scripts, or prompt-based element references.

Key Parameters

Parameter	Description
`model_name`	`kling-v3-omni`
`prompt`	Can reference material using `<<<video_1>>>`, `<<<image_1>>>`, etc.
`video_list`	Input material list, commonly containing `video_url`, `refer_type`, and `keep_original_sound`
`multi_shot`	Enables multi-shot mode
`shot_type`	Shot organization method
`multi_prompt`	Per-shot `prompt` and `duration` configuration
`aspect_ratio`	Output aspect ratio
`mode`	Quality mode

bash

curl -X POST "https://api.agentsflare.com/klingai/v1/videos/omni-video" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "kling-v3-omni",
    "prompt": "Based on <<<video_1>>>, generate the next shot.",
    "video_list": [
      {
        "video_url": "https://your-public-video.mp4",
        "refer_type": "feature",
        "keep_original_sound": "yes"
      }
    ],
    "aspect_ratio": "16:9",
    "mode": "pro"
  }'

Multi-shot Example Structure

json

{
  "model_name": "kling-v3-omni",
  "multi_shot": true,
  "shot_type": "customize",
  "multi_prompt": [
    { "index": 1, "prompt": "Wide shot of the city at dusk", "duration": 2 },
    { "index": 2, "prompt": "Camera pushes toward the balcony", "duration": 3 }
  ],
  "aspect_ratio": "16:9",
  "mode": "pro"
}

Query Task

After creating a task, poll it with the returned task_id.

Query Paths

GET /klingai/v1/videos/text2video/{id}
GET /klingai/v1/videos/image2video/{id}
GET /klingai/v1/videos/motion-control/{id}
GET /klingai/v1/videos/omni-video/{id}

bash

curl -X GET "https://api.agentsflare.com/klingai/v1/videos/text2video/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

Legacy Multi-Image to Video

If your channel still exposes the legacy multi-image2video capability, you can keep using it. For new integrations, image2video + image_tail or omni-video is usually the better choice.

json

{
  "model_name": "kling-v3",
  "image_list": [
    { "image": "<image_1>" },
    { "image": "<image_2>" }
  ],
  "prompt": "smooth transition between the two images",
  "aspect_ratio": "16:9",
  "duration": 5
}

Debugging Tips

Submit a task first, then poll GET /{id} instead of waiting on one long request.
Make sure the image / video URLs are publicly accessible.
Good prompts usually describe subject + motion + camera + lighting + style.
If you need business-side tracing, always set external_task_id.
Examples are provided in cURL, Python, Node and Go; for detailed parameters refer to the vendor reference above.

Supported Models

The following models are available through this interface (sorted by recommendation):

kling-element
kling-v3
kling-v3-omni
kling-v3-motion-control
kling-custom-voice

💡 Tip

The model field in the request example can be replaced with any model name above.

Kling AI API Examples ​

Basic Configuration ​

Request Information ​

Capability / Model Matrix ​

Common Headers ​

Common Fields ​

Text to Video ​

Main Parameters ​

Response Example ​

Image to Video ​

Main Parameters ​

Motion Control ​

Recommended Parameters ​

Omni Video ​

Key Parameters ​

Multi-shot Example Structure ​

Query Task ​

Query Paths ​

Legacy Multi-Image to Video ​

Debugging Tips ​

Supported Models ​

Kling AI API Examples

Basic Configuration

Request Information

Capability / Model Matrix

Common Headers

Common Fields

Text to Video

Main Parameters

Response Example

Image to Video

Main Parameters

Motion Control

Recommended Parameters

Omni Video

Key Parameters

Multi-shot Example Structure

Query Task

Query Paths

Legacy Multi-Image to Video

Debugging Tips

Supported Models