Kling 4.0 Flash Reference To Video

Endpoint

POST /jobs/createTask

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

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

Materials and References

All three material types are optional. When none are provided, the request behaves as plain text-to-video. Once provided, mention them in prompt as shown below:

Material	Mention syntax	Limit
Reference images `image_urls`	`@image_1`, `@image_2`, …	10 images
Reference videos `video_urls`	`@video_1`, `@video_2`, …	5 videos
Elements `elements`	`@name`	7 items, of which at most 3 can be video elements

Reference videos plus video elements cannot exceed 5 in total. The three material types combined cannot exceed 15.
Combined duration of all reference videos and video elements must be 2–20 seconds. If it is outside that range, the completion callback returns a failure.
An image element needs 2–4 images, with the first as the primary view. A video element needs one 3–8 second single-shot character video.
Custom names must be 1–20 characters of Chinese characters, letters, digits, or underscores; unique (case-insensitive); and must not use reserved names such as image_N, video_N, keyframe_N, object_N, audio_N, first_frame, or last_frame.
Mentioning an undeclared material is rejected immediately and the task is not created.
Output resolution is always 720p. Duration is 3–20 seconds.

TIP

When aspect_ratio is omitted, the model uses auto if any reference material is provided, and 16:9 when none are. When video_urls is provided, keep_original_sound controls whether the original audio is kept.

Query Task Status

After submitting a task, you can check the task progress and retrieve generation results via the unified query endpoint:

Get Task Details — Learn how to check the task status and obtain the generated results

TIP

In the production environment, it is recommended to use the callBackUrl parameter to receive the automatic notification upon completion of the generation, rather than polling the status endpoint.

Market Overview — View all available models

Request Parameters

Body (application/json)

Parameter	Type	Required	Description
`model`	`string`	Yes	The name of the model used to generate the task. This field is required. - This endpoint requires the `kling-4.0/flash-reference-to-video` model Default：`"kling-4.0/flash-reference-to-video"`。 Allowed values：`kling-4.0/flash-reference-to-video`。 Example：`kling-4.0/flash-reference-to-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 Example：`https://your-domain.com/api/callback`。
`input`	`object`	Yes	Input parameters for the generation task.
`input.prompt`	`string`	Yes	Video description. Required. Maximum 8000 characters. Use `@` to mention assets uploaded in this request: - `@image_1`, `@image_2`, … map to `image_urls` in order (1-based) - `@video_1`, `@video_2`, … map to `video_urls` - `@name` maps to the `name` of an item in `elements` Every `@` mention must match an asset included in this request, otherwise the request is rejected. Mentions use longest-match against declared names. If the matched name ends with a letter, digit, or underscore, the next character cannot be a letter, digit, or underscore. minLength: `1`. maxLength: `8000`. Example：`Replace the environment and characters throughout the video with the content from Image.`。
`input.duration`	`integer`	No	Output video duration in seconds. Integer from 3 to 20. Default: `5`. Default：`5`。 minimum: `3`. maximum: `20`. Example：`5`。
`input.resolution`	`string`	No	Output resolution. Kling 4.0 Flash only supports `720p`. Default: `720p`. Default：`"720p"`。 Allowed values：`720p`。 Example：`720p`。
`input.aspect_ratio`	`string`	No	Output aspect ratio. Optional. - If omitted and any reference asset is provided, the model uses `auto` - If omitted and no reference asset is provided, the model uses `16:9` Allowed values：`auto` / `16:9` / `9:16` / `1:1` / `21:9`。 Example：`auto`。
`input.image_urls`	`array<string>`	No	Reference images, up to 10 publicly accessible URLs. Mention them in the prompt as `@image_1`, `@image_2`, … in array order. Default：`[]`。 maxItems: `10`.
`input.video_urls`	`array<string>`	No	Reference videos, up to 5 publicly accessible URLs. Mention them in the prompt as `@video_1`, `@video_2`, …. Reference videos plus video subjects in `elements` cannot exceed 5 in total. Combined duration of all reference videos and video elements must be 2–20 seconds; if it is outside that range the completion callback returns a failure. Default：`[]`。 maxItems: `5`.
`input.keep_original_sound`	`boolean`	No	Whether to keep the original audio of the reference videos. Only takes effect when `video_urls` is provided. Default: `false`. If no reference video is provided, native audio is always generated. Default：`false`。 Example：`false`。
`input.elements`	`array<object>`	No	Subjects used only for this task. Up to 7 items, of which at most 3 can be video subjects. Mention them in the prompt as `@name`. `image_urls`, `video_urls`, and `elements` together cannot exceed 15 items. Standalone `voices` is not supported on Flash. Default：`[]`。 maxItems: `7`.
`input.elements[].name`	`string`	Yes	The name used in the prompt as `@Hero`. 1–20 characters; Chinese, letters, digits, and underscore only. Must be unique across `elements` (case-insensitive). Reserved names (case-insensitive, N is a number) cannot be used: `image_N`, `video_N`, `keyframe_N`, `object_N`, `audio_N`, `first_frame`, `last_frame`. pattern: `^[一-龥A-Za-z0-9_]{1,20}$`. Example：`Hero`。
`input.elements[].image_urls`	`array<string>`	No	2–4 publicly accessible image URLs for an image subject. Cannot be used together with `video_url`. The first image is the primary view (front face or main angle); the rest are supporting views. Required when `type` is `image` or omitted. minItems: `2`. maxItems: `4`.
`input.elements[].video_url`	`string`	No	Character video URL for a video subject. Cannot be used together with `image_urls`. One video, 3–8 seconds, a single continuous shot (no cuts), shortest side at least 700 pixels. Required when `type` is `video`. pattern: `^https?://`.
`input.elements[].tag`	`string`	No	Subject category. Optional for image subjects — if omitted, it is inferred from the primary image. Video subjects are always `character`; any other value is rejected. Allowed values：`character` / `animal` / `prop` / `costume` / `scene` / `effect` / `others`。 Example：`character`。
`input.elements[].description`	`string`	No	Optional subject description. Maximum 100 characters. maxLength: `100`.
`input.elements[].voice_url`	`string`	No	Optional reference audio bound to this subject. It cannot be mentioned with `@` on its own. Only character subjects can bind audio: for image subjects `tag` must be `character` or omitted; for video subjects, if omitted the video's original speech is used by default. Standalone `voices` is not supported on Kling 4.0 Flash. pattern: `^https?://`.
`input.elements[].type`	`string`	No	Subject type. Optional, default `image`. - `image`: use `image_urls` (2–4 images of the same subject; first is the primary view). Do not send `video_url`. - `video`: use `video_url` (one 3–8 second single-shot character video). Do not send `image_urls`. Video subjects are always `character`. Default：`"image"`。 Allowed values：`image` / `video`。 Example：`image`。

Request Example

bash

curl -X POST "https://modelfold.ai/v1/jobs/createTask" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "kling-4.0/flash-reference-to-video",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "Replace the environment and characters throughout the video with the content from Image.",
    "image_urls": [
      "https://static.aiquickdraw.com/tools/example/1793864877785_DrXOIEka.png"
    ],
    "video_urls": [
      "https://static.aiquickdraw.com/tools/example/1793864807765_yRE8tJUe.mp4"
    ],
    "keep_original_sound": false,
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "auto",
    "elements": [
      {
        "name": "test",
        "type": "image",
        "image_urls": [
          "https://tempfileb.aiquickdraw.com/kieai/market/1793878290792_SdXlPHYn.jpeg"
        ],
        "tag": "character",
        "description": "测试实测",
        "voice_url": "https://tempfileb.aiquickdraw.com/kieai/market/1793878312680_g5wLYejf.mp3"
      }
    ]
  }
}'

python

import os
import requests

resp = requests.post(
    "https://modelfold.ai/v1/jobs/createTask",
    headers={
        "Authorization": "Bearer " + os.environ["MODELFOLD_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "model": "kling-4.0/flash-reference-to-video",
        "callBackUrl": "https://your-domain.com/api/callback",
        "input": {
            "prompt": "Replace the environment and characters throughout the video with the content from Image.",
            "image_urls": [
                "https://static.aiquickdraw.com/tools/example/1793864877785_DrXOIEka.png",
            ],
            "video_urls": [
                "https://static.aiquickdraw.com/tools/example/1793864807765_yRE8tJUe.mp4",
            ],
            "keep_original_sound": False,
            "duration": 5,
            "resolution": "720p",
            "aspect_ratio": "auto",
            "elements": [
                {
                    "name": "test",
                    "type": "image",
                    "image_urls": [
                        "https://tempfileb.aiquickdraw.com/kieai/market/1793878290792_SdXlPHYn.jpeg",
                    ],
                    "tag": "character",
                    "description": "测试实测",
                    "voice_url": "https://tempfileb.aiquickdraw.com/kieai/market/1793878312680_g5wLYejf.mp3",
                },
            ],
        },
    },
)
print(resp.json())

javascript

const resp = await fetch("https://modelfold.ai/v1/jobs/createTask", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.MODELFOLD_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "kling-4.0/flash-reference-to-video",
    "callBackUrl": "https://your-domain.com/api/callback",
    "input": {
      "prompt": "Replace the environment and characters throughout the video with the content from Image.",
      "image_urls": [
        "https://static.aiquickdraw.com/tools/example/1793864877785_DrXOIEka.png"
      ],
      "video_urls": [
        "https://static.aiquickdraw.com/tools/example/1793864807765_yRE8tJUe.mp4"
      ],
      "keep_original_sound": false,
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "auto",
      "elements": [
        {
          "name": "test",
          "type": "image",
          "image_urls": [
            "https://tempfileb.aiquickdraw.com/kieai/market/1793878290792_SdXlPHYn.jpeg"
          ],
          "tag": "character",
          "description": "测试实测",
          "voice_url": "https://tempfileb.aiquickdraw.com/kieai/market/1793878312680_g5wLYejf.mp3"
        }
      ]
    }
  }),
});
console.log(await resp.json());

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{"model":"kling-4.0/flash-reference-to-video","callBackUrl":"https://your-domain.com/api/callback","input":{"prompt":"Replace the environment and characters throughout the video with the content from Image.","image_urls":["https://static.aiquickdraw.com/tools/example/1793864877785_DrXOIEka.png"],"video_urls":["https://static.aiquickdraw.com/tools/example/1793864807765_yRE8tJUe.mp4"],"keep_original_sound":false,"duration":5,"resolution":"720p","aspect_ratio":"auto","elements":[{"name":"test","type":"image","image_urls":["https://tempfileb.aiquickdraw.com/kieai/market/1793878290792_SdXlPHYn.jpeg"],"tag":"character","description":"测试实测","voice_url":"https://tempfileb.aiquickdraw.com/kieai/market/1793878312680_g5wLYejf.mp3"}]}}`)
	req, _ := http.NewRequest("POST", "https://modelfold.ai/v1/jobs/createTask", body)
	req.Header.Set("Authorization", "Bearer " + os.Getenv("MODELFOLD_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(string(out))
}

java

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

public class Main {
    public static void main(String[] args) throws Exception {
        String body = "{\"model\":\"kling-4.0/flash-reference-to-video\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"input\":{\"prompt\":\"Replace the environment and characters throughout the video with the content from Image.\",\"image_urls\":[\"https://static.aiquickdraw.com/tools/example/1793864877785_DrXOIEka.png\"],\"video_urls\":[\"https://static.aiquickdraw.com/tools/example/1793864807765_yRE8tJUe.mp4\"],\"keep_original_sound\":false,\"duration\":5,\"resolution\":\"720p\",\"aspect_ratio\":\"auto\",\"elements\":[{\"name\":\"test\",\"type\":\"image\",\"image_urls\":[\"https://tempfileb.aiquickdraw.com/kieai/market/1793878290792_SdXlPHYn.jpeg\"],\"tag\":\"character\",\"description\":\"测试实测\",\"voice_url\":\"https://tempfileb.aiquickdraw.com/kieai/market/1793878312680_g5wLYejf.mp3\"}]}}";
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create("https://modelfold.ai/v1/jobs/createTask"))
            .header("Authorization", "Bearer " + System.getenv("MODELFOLD_API_KEY"))
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(body))
            .build();
        HttpResponse<String> resp = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
        System.out.println(resp.body());
    }
}

php

<?php
$ch = curl_init('https://modelfold.ai/v1/jobs/createTask');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv("MODELFOLD_API_KEY"),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{"model":"kling-4.0/flash-reference-to-video","callBackUrl":"https://your-domain.com/api/callback","input":{"prompt":"Replace the environment and characters throughout the video with the content from Image.","image_urls":["https://static.aiquickdraw.com/tools/example/1793864877785_DrXOIEka.png"],"video_urls":["https://static.aiquickdraw.com/tools/example/1793864807765_yRE8tJUe.mp4"],"keep_original_sound":false,"duration":5,"resolution":"720p","aspect_ratio":"auto","elements":[{"name":"test","type":"image","image_urls":["https://tempfileb.aiquickdraw.com/kieai/market/1793878290792_SdXlPHYn.jpeg"],"tag":"character","description":"测试实测","voice_url":"https://tempfileb.aiquickdraw.com/kieai/market/1793878312680_g5wLYejf.mp3"}]}}',
]);
echo curl_exec($ch);
curl_close($ch);

csharp

using System;
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var req = new HttpRequestMessage(new HttpMethod("POST"), "https://modelfold.ai/v1/jobs/createTask");
req.Headers.TryAddWithoutValidation("Authorization", "Bearer " + Environment.GetEnvironmentVariable("MODELFOLD_API_KEY"));
req.Content = new StringContent("{\"model\":\"kling-4.0/flash-reference-to-video\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"input\":{\"prompt\":\"Replace the environment and characters throughout the video with the content from Image.\",\"image_urls\":[\"https://static.aiquickdraw.com/tools/example/1793864877785_DrXOIEka.png\"],\"video_urls\":[\"https://static.aiquickdraw.com/tools/example/1793864807765_yRE8tJUe.mp4\"],\"keep_original_sound\":false,\"duration\":5,\"resolution\":\"720p\",\"aspect_ratio\":\"auto\",\"elements\":[{\"name\":\"test\",\"type\":\"image\",\"image_urls\":[\"https://tempfileb.aiquickdraw.com/kieai/market/1793878290792_SdXlPHYn.jpeg\"],\"tag\":\"character\",\"description\":\"测试实测\",\"voice_url\":\"https://tempfileb.aiquickdraw.com/kieai/market/1793878312680_g5wLYejf.mp3\"}]}}", Encoding.UTF8, "application/json");
var resp = await client.SendAsync(req);
Console.WriteLine(await resp.Content.ReadAsStringAsync());

json

{
  "model": "kling-4.0/flash-reference-to-video",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "Replace the environment and characters throughout the video with the content from Image.",
    "image_urls": [
      "https://static.aiquickdraw.com/tools/example/1793864877785_DrXOIEka.png"
    ],
    "video_urls": [
      "https://static.aiquickdraw.com/tools/example/1793864807765_yRE8tJUe.mp4"
    ],
    "keep_original_sound": false,
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "auto",
    "elements": [
      {
        "name": "test",
        "type": "image",
        "image_urls": [
          "https://tempfileb.aiquickdraw.com/kieai/market/1793878290792_SdXlPHYn.jpeg"
        ],
        "tag": "character",
        "description": "测试实测",
        "voice_url": "https://tempfileb.aiquickdraw.com/kieai/market/1793878312680_g5wLYejf.mp3"
      }
    ]
  }
}

Response

200 — Request Successful

参数	类型	必填	说明
`code`	`integer`	否	See the response field; handle the returned status before retrying.
`msg`	`string`	否	Response message, error description when failed 示例：`success`。
`data`	`object`	是	—
`data.taskId`	`string`	是	Task ID, can be used with Get Task Details endpoint to query task status

json

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_kling-4.0-flash-reference-to-video_abc123"
  }
}

Callback

videoTaskCompleted

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

The system POSTs this callback to callBackUrl when the kling-4.0/flash-reference-to-video task succeeds or fails.

Callback body parameters

参数	类型	必填	说明
`code`	`integer`	是	Unified callback code: `200` for success, `501` for failure. Allowed values：`200` / `501`。 Example：`200`。
`msg`	`string`	是	Unified callback message. Allowed values：`Playground task completed successfully.` / `Playground task failed.`。 Example：`Playground task completed successfully.`。
`data`	`object`	是	Task result. On success, `resultJson` contains `resultUrls`. On failure, `failCode` and `failMsg` are present and `resultJson` is omitted.
`data.completeTime`	`integer`	否	Task completion timestamp in milliseconds. Use this as the completion time.
`data.costTime`	`integer`	否	Processing time in seconds. Present on both success and failure callbacks.
`data.createTime`	`integer`	否	Task creation timestamp in milliseconds.
`data.model`	`string`	是	The model used for the task. Allowed values：`kling-4.0/flash-reference-to-video`。 Example：`kling-4.0/flash-reference-to-video`。
`data.param`	`string`	是	JSON string of the submitted task: `model`, `callBackUrl`, and `input`. `input` matches this endpoint's parameters (`prompt`, `duration`, `resolution`, `aspect_ratio`, `image_urls`, `video_urls`, `keep_original_sound`, `elements`).
`data.resultJson`	`string`	否	JSON string of the generation result. Present only when `state` is `success`. For this model it contains `resultUrls`, an array of `.mp4` URLs.
`data.state`	`string`	是	Terminal task state. Allowed values：`success` / `fail`。 Example：`success`。
`data.taskId`	`string`	是	The unique task identifier. Same as `data.taskId` returned by Create Task.
`data.updateTime`	`integer`	否	Task update timestamp in milliseconds. May equal `createTime`; use `completeTime` as the completion time.
`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`. For this model this may be a reference-video duration error (`video_1 duration must be between 2 and 20 seconds, got 45`), an element/voice creation error, or an upstream original message.

Task completed successfully

json

{
  "code": 200,
  "data": {
    "completeTime": 1792669219001,
    "costTime": 315,
    "createTime": 1792668903000,
    "model": "kling-4.0/flash-reference-to-video",
    "param": "{\"input\":\"{\\\"duration\\\":10,\\\"aspect_ratio\\\":\\\"9:16\\\",\\\"keep_original_sound\\\":false,\\\"elements\\\":[],\\\"image_urls\\\":[],\\\"video_urls\\\":[],\\\"prompt\\\":\\\"sits at the desk in\\\",\\\"resolution\\\":\\\"720p\\\"}\",\"callBackUrl\":\"https://webhook.uutool.cn/bfa7de80-8dd8-4844-9e34-4032ddbbf3c1\",\"model\":\"kling-4.0/flash-reference-to-video\"}",
    "resultJson": "{\"resultUrls\":[\"https://tempfile.aiquickdraw.com/k/1f0176644624b187c7f6add97986875d_1_1792669217_8488.mp4\"]}",
    "state": "success",
    "taskId": "1f0176644624b187c7f6add97986875d",
    "updateTime": 1792668903000
  },
  "msg": "Playground task completed successfully."
}

Task failed

json

{
  "code": 501,
  "data": {
    "completeTime": 1792669219001,
    "costTime": 315,
    "createTime": 1792668903000,
    "failCode": "400",
    "failMsg": "video_1 duration must be between 2 and 20 seconds, got 45",
    "model": "kling-4.0/flash-reference-to-video",
    "param": "{\"input\":\"{\\\"duration\\\":10,\\\"aspect_ratio\\\":\\\"9:16\\\",\\\"keep_original_sound\\\":false,\\\"elements\\\":[],\\\"image_urls\\\":[],\\\"video_urls\\\":[\\\"https://example.com/room.mp4\\\"],\\\"prompt\\\":\\\"sits at the desk in @video_1\\\",\\\"resolution\\\":\\\"720p\\\"}\",\"callBackUrl\":\"https://webhook.uutool.cn/bfa7de80-8dd8-4844-9e34-4032ddbbf3c1\",\"model\":\"kling-4.0/flash-reference-to-video\"}",
    "state": "fail",
    "taskId": "1f0176644624b187c7f6add97986875d",
    "updateTime": 1792668903000
  },
  "msg": "Playground task failed."
}

Kling 4.0 Flash Reference To Video ​

Endpoint ​

Materials and References ​

Query Task Status ​

Related Resources ​

Request Parameters ​

Body (application/json) ​

Request Example ​

Response ​

200 — Request Successful ​

Callback ​

videoTaskCompleted ​

Kling 4.0 Flash Reference To Video

Endpoint

Materials and References

Query Task Status

Related Resources

Request Parameters

Body (application/json)

Request Example

Response

200 — Request Successful

Callback

videoTaskCompleted