Kling 3.0

This page is generated from the upstream official OpenAPI documentation. Endpoints, parameters and examples match the official docs; brand and API domain are replaced with ModelFold.

Endpoint

POST /jobs/createTask

Full URL: https://ai.modelfold.online/v1/jobs/createTask

Authentication: every request must include the Authorization: Bearer <API_KEY> header.

Generate high-quality videos with advanced multi-shot capabilities and element references using Kling 3.0 AI

Overview

Kling 3.0 is an advanced video generation model that supports both single-shot and multi-shot video creation with element references. It offers three modes: std, pro and 4K, 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/audio elements within prompts
Native Audio: Speech, sound effects and ambience
Flexible Aspect Ratios: Support for 16:9, 9:16, and 1:1 aspect ratios
Configurable Duration: Video duration from 3 to 15 seconds

TIP

In std and pro modes, enabling sound costs more. In multi-shot mode, billing is based on the sum of the shot durations. For current prices, see ai.modelfold.online/pricing.

Resolution Mappings

The resolution depends on both the mode 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	1440×1440

4K Mode (4K)

Aspect Ratio	Resolution
16:9	3840×2160
9:16	2160×3840
1:1	2160×2160

INFO

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 multi_prompt array to define multiple shots
Each shot has its own prompt and duration (1-12 seconds)
Only supports first frame image (via image_urls[0])
The maximum number of characters per shot is 500

Aspect Ratio Auto-Adaptation

When you provide image_urls (first and/or last frame images), the aspect_ratio parameter becomes optional. The system will automatically adapt the aspect ratio based on the uploaded images, so you don't need to specify it manually.

TIP

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: 2-4 image URLs (JPG/PNG, max 10MB each)
Video Elements: Up to 1 video URL (MP4/MOV format, the video duration must be at least 3 seconds, and the effective segment length should be between 3 and 8 seconds)
Audio Reference: Up to 1 audio URL (audio duration must be between 5 and 30 seconds)

TIP

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.

File Upload Requirements

Before using element references, upload your image files:

1. Upload Files

Use the File Upload API to upload your source images.

File Upload API

Learn how to upload files and get file URLs: File Upload API Quickstart

2. Get File URLs

After upload, you'll receive file URLs that you can use in element_input_urls and element_input_audio_urls. ::: caution

formats:
- Image (JPG, PNG, max 10MB per file, 2-4 files per element)
- Video (MP4, MOV format. Video duration should be at least 3 seconds. The effective video segment length should be between 3 and 8 seconds)
- Audio (Audio duration must be between 5 and 30 seconds)
Ensure file URLs are accessible and not expired :::

Usage Examples

Single-Shot Video with Element Reference

json

{
  "model": "kling-3.0/video",
  "input": {
    "prompt": "In a bright rehearsal room, sunlight streams through the window@element_dog",
    "image_urls": [
      "https://static.aiquickdraw.com/tools/example/1764851002741_i0lEiI8I.png"
    ],
    "sound": false,
    "duration": "5",
    "aspect_ratio": "16:9",
    "mode": "std",
    "multi_shots": false,
    "kling_elements": [
      {
        "name": "element_dog",
        "description": "dog",
        "element_input_urls": [
          "https://example.com/your-image.png",
          "https://example.com/your-image.png"
        ]
      }
    ]
  }
}

Multi-Shot Video

json

{
  "model": "kling-3.0/video",
  "input": {
    "multi_shots": true,
    "image_urls": [
      "https://static.aiquickdraw.com/tools/example/1764851002741_i0lEiI8I.png"
    ],
    "sound": false,
    "duration": "5",
    "aspect_ratio": "16:9",
    "mode": "std",
    "multi_prompt": [
      {
        "prompt": "a happy dog in running@element_cat",
        "duration": 2
      },
      {
        "prompt": "a happy dog play with a cat@element_dog",
        "duration": 3
      }
    ],
    "kling_elements": [
      {
        "name": "element_cat",
        "description": "cat",
        "element_input_urls": [ "https://example.com/your-image.png",    "https://example.com/your-image.png"
        ]
      },
      {
        "name": "element_dog",
        "description": "dog",
        "element_input_urls": [ "https://example.com/your-image.png",    "https://example.com/your-image.png"
        ]
      }
    ]
  }
}

Query Task Status

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

Get Task Details

Learn how to query task status and retrieve generation results: Get Task Details

TIP

For production use, we recommend using the callBackUrl parameter to receive automatic notifications when generation completes, rather than polling the status endpoint.

Best Practices

Prompt Writing: Be specific and descriptive in your prompts. Include details about motion, camera angles, and scene composition
Element Usage: Use high-quality reference images/video/audio for better results. Ensure elements match the style and theme of your video
Duration Planning: For multi-shot videos, plan your shot durations to match the total video duration
Mode Selection: Use 4K mode for final output when quality is important, and std mode for faster iterations
Sound Effects: Enable sound effects for more immersive videos, especially for action or dynamic scenes

Request Parameters

Body (application/json)

Parameter	Type	Required	Description
`model`	`string`	Yes	The model name. Must be kling-3.0/video. Default：`"kling-3.0/video"`。 Allowed values：`kling-3.0/video`。示例：`kling-3.0/video`。
`callBackUrl`	`string`	No	The URL to receive generation task completion updates. Optional but recommended for production use. - System will POST task status and results to this URL when generation completes - Callback includes generated content URLs and task information - Your callback endpoint should accept POST requests with JSON payload containing results - Alternatively, use the Get Task Details endpoint to poll task status - To ensure callback security, see Webhook Verification Guide for signature verification implementation 示例：`https://your-domain.com/api/callback`。
`input`	`object`	No	Input parameters for the generation task
`input.prompt`	`string`	No	Required when multi_shots is false. Up to 2,500 characters. 示例：`In a bright rehearsal room, sunlight streams through the window@element_dog`。
`input.image_urls`	`array<string>`	No	First and last frame image URLs. Optional; not required when using kling_elements. When multi_shots is false: if length is 2, index 0 is the first frame and index 1 is the last frame; if length is 1, the array item serves as the first frame. When multi_shots is true: only the first frame is supported.
`input.sound`	`boolean`	Yes	Required. Whether to generate audio (speech, sound effects, ambience) with the video. Affects price. 示例：`true`。
`input.duration`	`string`	Yes	Required. Video duration in seconds, 3–15 (string, e.g. "5"). In multi-shot mode, output length and billing follow the sum of multi_prompt[].duration (3–15 s); set duration to the same total. Allowed values：`3` / `4` / `5` / `6` / `7` / `8` / `9` / `10` / `11` / `12` / `13` / `14` / `15`。示例：`5`。
`input.aspect_ratio`	`string`	No	Optional when image_urls is provided (the output follows the first frame's aspect ratio). For text-to-video, set it explicitly: 16:9, 9:16 or 1:1. Allowed values：`16:9` / `9:16` / `1:1`。示例：`16:9`。
`input.mode`	`string`	Yes	Required. Generation mode. std has standard resolution, pro has higher resolution, 4K has 4K resolution. Resolution mapping: - std mode: 16:9 (1280×720), 9:16 (720×1280), 1:1 (720×720) - pro mode: 16:9 (1920×1080), 9:16 (1080×1920), 1:1 (1080×1080) - 4K mode: 16:9 (3840×2160), 9:16 (2160×3840), 1:1 (2160×2160) Allowed values：`std` / `pro` / `4K`。示例：`pro`。
`input.multi_shots`	`boolean`	Yes	Required. Whether to use multi-shot mode. true enables multi-shot mode, false enables single-shot mode. 示例：`false`。
`input.multi_prompt`	`array<object>`	No	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. If you need to use elements, add them after the prompt.
`input.multi_prompt[].prompt`	`string`	Yes	Prompt text for this shot, a maximum of 500 characters per shot. Each @element will occupy 37 characters. 示例：`a happy dog in running@element_cat`。
`input.multi_prompt[].duration`	`integer`	Yes	Duration of this shot in seconds. Range: 1-12. 示例：`3`。
`input.kling_elements`	`array<object>`	No	Referenced elements. Detailed information about elements referenced in the prompt. A single task can reference a maximum of three elements.
`input.kling_elements[].name`	`string`	Yes	Element name, used in prompt with @ prefix (e.g., @element_dog) 示例：`element_dog`。
`input.kling_elements[].description`	`string`	Yes	Element description 示例：`dog`。
`input.kling_elements[].element_input_urls`	`array<string>`	Yes	Either 2–4 images (JPG/PNG, up to 10 MB each) or 1 video (MP4/MOV).
`input.kling_elements[].element_input_audio_urls`	`array<string>`	No	Optional. List of audio material URLs for characters. The audio duration must be between 5 and 30 seconds.
`input.kling_elements[].start_time`	`integer`	No	Start time for video character material capture (in milliseconds). Only effective when uploading videos through element_input_urls. If not uploaded, it defaults to 0.
`input.kling_elements[].end_time`	`integer`	No	End time for video character material capture (in milliseconds). Only effective when uploading videos through element_input_urls. Must be greater than start_time, and the difference between end_time and start_time must be within 3000 to 8000 milliseconds.

Request Example

bash

curl -X POST "https://ai.modelfold.online/v1/jobs/createTask" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "kling-3.0/video",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "In a bright rehearsal room, sunlight streams through the window @element_dog",
    "image_urls": [
      "https://static.aiquickdraw.com/tools/example/1764851002741_i0lEiI8I.png"
    ],
    "sound": true,
    "duration": "5",
    "aspect_ratio": "16:9",
    "mode": "pro",
    "multi_shots": false,
    "multi_prompt": [
      {
        "prompt": "a happy dog in running @element_cat",
        "duration": 3
      },
      {
        "prompt": "a happy dog play with a cat @element_dog",
        "duration": 2
      }
    ],
    "kling_elements": [
      {
        "name": "element_dog",
        "description": "dog",
        "element_input_urls": [
          "https://example.com/your-image.png",
          "https://example.com/your-image.png"
        ],
        "element_input_audio_urls": [
          "https://your-cdn.com/wjeoiajfosijfoi.mp3"
        ]
      },
      {
        "name": "element_cat",
        "description": "cat",
        "element_input_urls": [
          "https://your-cdn.com/element_image.mp4"
        ],
        "element_input_audio_urls": [
          "https://your-cdn.com/wjeoiajfosijfoi.mp3"
        ],
        "start_time": 0,
        "end_time": 8000
      }
    ]
  }
}'

json

{
  "model": "kling-3.0/video",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "In a bright rehearsal room, sunlight streams through the window @element_dog",
    "image_urls": [
      "https://static.aiquickdraw.com/tools/example/1764851002741_i0lEiI8I.png"
    ],
    "sound": true,
    "duration": "5",
    "aspect_ratio": "16:9",
    "mode": "pro",
    "multi_shots": false,
    "multi_prompt": [
      {
        "prompt": "a happy dog in running @element_cat",
        "duration": 3
      },
      {
        "prompt": "a happy dog play with a cat @element_dog",
        "duration": 2
      }
    ],
    "kling_elements": [
      {
        "name": "element_dog",
        "description": "dog",
        "element_input_urls": [
          "https://example.com/your-image.png",
          "https://example.com/your-image.png"
        ],
        "element_input_audio_urls": [
          "https://your-cdn.com/wjeoiajfosijfoi.mp3"
        ]
      },
      {
        "name": "element_cat",
        "description": "cat",
        "element_input_urls": [
          "https://your-cdn.com/element_image.mp4"
        ],
        "element_input_audio_urls": [
          "https://your-cdn.com/wjeoiajfosijfoi.mp3"
        ],
        "start_time": 0,
        "end_time": 8000
      }
    ]
  }
}

Response

200 — Request successful

参数	类型	必填	说明
`data`	`object`	否	—
`data.code`	`string`	是	Response status code - 200: Success - Request has been processed successfully - 401: Unauthorized - Authentication credentials are missing or invalid - 402: Insufficient Credits - Account does not have enough credits to perform the operation - 404: Not Found - The requested resource or endpoint does not exist - 422: Validation Error - The request parameters failed validation checks - 429: Rate Limited - Request limit has been exceeded for this resource - 433: Request Limit - Sub-key Usage Exceeds Limit - 455: Service Unavailable - System is currently undergoing maintenance - 500: Server Error - An unexpected error occurred while processing the request - 501: Generation Failed - Content generation task failed - 505: Feature Disabled - The requested feature is currently disabled
`data.msg`	`string`	是	Response message, error description when failed
`data.taskId`	`string`	否	Task ID, can be used with Get Task Details endpoint to query task status 示例：`task_kling-3.0_1765187774173`。

json

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_kling-3.0_1765187774173"
  }
}

Callback

videoTaskCompleted

Callback URL: {request.body#/callBackUrl} (the callBackUrl in the request body).

The system sends this callback when the kling-3.0/video task succeeds or fails.

Callback body parameters

参数	类型	必填	说明
`code`	`integer`	是	Unified callback code: 200 for success, 501 for failure. Allowed values：`200` / `501`。示例：`200`。
`msg`	`string`	是	Unified callback message. Allowed values：`Playground task completed successfully.` / `Playground task failed.`。示例：`Playground task completed successfully.`。
`data`	`object`	是	—
`data.taskId`	`string`	是	The unique task identifier.
`data.model`	`string`	是	The model used for the task. Allowed values：`kling-3.0/video`。示例：`kling-3.0/video`。
`data.state`	`string`	是	Terminal task state. Allowed values：`success` / `fail`。示例：`success`。
`data.param`	`string`	是	JSON string containing the submitted task parameters.
`data.resultJson`	`string`	否	JSON string containing resultUrls, firstFrameUrl, lastFrameUrl, or resultObject when successful. Present only when state is success.
`data.failCode`	`string`	否	Failure code, a numeric string such as "400" or "500". Present only when state is fail.
`data.failMsg`	`string`	否	Failure reason. Present only when state is fail.
`data.costTime`	`integer`	否	Processing time in seconds. Present on both success and failure callbacks.
`data.completeTime`	`integer`	否	Task completion timestamp.
`data.createTime`	`integer`	否	Task creation timestamp.
`data.updateTime`	`integer`	否	Use completeTime as the completion time; updateTime may equal createTime.
`data.creditsConsumed`	`number`	否	Credits consumed by the task; 0 for failed tasks.

Task completed successfully

json

{
  "code": 200,
  "msg": "Playground task completed successfully.",
  "data": {
    "taskId": "task_example_video_webhook_001",
    "model": "kling-3.0/video",
    "state": "success",
    "param": "{\"input\":\"{\\\"prompt\\\":\\\"In a bright rehearsal room, sunlight streams through the window @element_dog\\\",\\\"image_urls\\\":[\\\"https://example.com/input-image.jpg\\\"],\\\"sound\\\":true,\\\"duration\\\":\\\"5\\\",\\\"aspect_ratio\\\":\\\"16:9\\\",\\\"mode\\\":\\\"pro\\\",\\\"multi_shots\\\":false,\\\"multi_prompt\\\":[{\\\"prompt\\\":\\\"a happy dog in running @element_cat\\\",\\\"duration\\\":3}],\\\"kling_elements\\\":[{\\\"name\\\":\\\"element_dog\\\",\\\"description\\\":\\\"dog\\\",\\\"element_input_urls\\\":[\\\"https://example.com/input-image.jpg\\\"],\\\"element_input_audio_urls\\\":[\\\"https://example.com/input-audio.mp3\\\"]}]}\",\"callBackUrl\":\"https://example.com/callback\",\"model\":\"kling-3.0/video\"}",
    "resultJson": "{\"resultUrls\":[\"https://example.com/generated-video.mp4\"]}",
    "costTime": 12,
    "completeTime": 1234567890,
    "createTime": 1234560000,
    "updateTime": 1234567890,
    "creditsConsumed": 1.23
  }
}

Task failed

json

{
  "code": 501,
  "msg": "Playground task failed.",
  "data": {
    "taskId": "task_example_video_webhook_001",
    "model": "kling-3.0/video",
    "state": "fail",
    "param": "{\"input\":\"{\\\"prompt\\\":\\\"In a bright rehearsal room, sunlight streams through the window @element_dog\\\",\\\"image_urls\\\":[\\\"https://example.com/input-image.jpg\\\"],\\\"sound\\\":true,\\\"duration\\\":\\\"5\\\",\\\"aspect_ratio\\\":\\\"16:9\\\",\\\"mode\\\":\\\"pro\\\",\\\"multi_shots\\\":false,\\\"multi_prompt\\\":[{\\\"prompt\\\":\\\"a happy dog in running @element_cat\\\",\\\"duration\\\":3}],\\\"kling_elements\\\":[{\\\"name\\\":\\\"element_dog\\\",\\\"description\\\":\\\"dog\\\",\\\"element_input_urls\\\":[\\\"https://example.com/input-image.jpg\\\"],\\\"element_input_audio_urls\\\":[\\\"https://example.com/input-audio.mp3\\\"]}]}\",\"callBackUrl\":\"https://example.com/callback\",\"model\":\"kling-3.0/video\"}",
    "failCode": "400",
    "failMsg": "<error detail>",
    "costTime": 12,
    "creditsConsumed": 0
  }
}

Kling 3.0 ​

Endpoint ​

Overview ​

Key Features ​

Resolution Mappings ​

Standard Mode (std) ​

Pro Mode (pro) ​

4K Mode (4K) ​

Single-Shot vs Multi-Shot Mode ​

Single-Shot Mode (multi_shots: false) ​

Multi-Shot Mode (multi_shots: true) ​

Aspect Ratio Auto-Adaptation ​

Element References ​

File Upload Requirements ​

1. Upload Files ​

2. Get File URLs ​

Usage Examples ​

Single-Shot Video with Element Reference ​

Multi-Shot Video ​

Query Task Status ​

Best Practices ​

Related Resources ​

Request Parameters ​

Body (application/json) ​

Request Example ​

Response ​

200 — Request successful ​

Callback ​

videoTaskCompleted ​

Kling 3.0

Endpoint

Overview

Key Features

Resolution Mappings

Standard Mode (std)

Pro Mode (pro)

4K Mode (4K)

Single-Shot vs Multi-Shot Mode

Single-Shot Mode (`multi_shots: false`)

Multi-Shot Mode (`multi_shots: true`)

Aspect Ratio Auto-Adaptation

Element References

File Upload Requirements

1. Upload Files

2. Get File URLs

Usage Examples

Single-Shot Video with Element Reference

Multi-Shot Video

Query Task Status

Best Practices

Related Resources

Request Parameters

Body (application/json)

Request Example

Response

200 — Request successful

Callback

videoTaskCompleted