Kling 4.0 Flash Reference To Video

接口

POST /jobs/createTask

完整 URL: https://modelfold.ai/v1/jobs/createTask

鉴权：所有请求都需要 Authorization: Bearer <API_KEY> 请求头。

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

请求参数

请求体 (application/json)

参数	类型	必填	说明
`model`	`string`	是	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 默认值：`"kling-4.0/flash-reference-to-video"`。可选值：`kling-4.0/flash-reference-to-video`。示例：`kling-4.0/flash-reference-to-video`。
`callBackUrl`	`string`	否	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`	是	Input parameters for the generation task.
`input.prompt`	`string`	是	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`. 示例：`Replace the environment and characters throughout the video with the content from Image.`。
`input.duration`	`integer`	否	Output video duration in seconds. Integer from 3 to 20. Default: `5`. 默认值：`5`。 minimum: `3`. maximum: `20`. 示例：`5`。
`input.resolution`	`string`	否	Output resolution. Kling 4.0 Flash only supports `720p`. Default: `720p`. 默认值：`"720p"`。可选值：`720p`。示例：`720p`。
`input.aspect_ratio`	`string`	否	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` 可选值：`auto` / `16:9` / `9:16` / `1:1` / `21:9`。示例：`auto`。
`input.image_urls`	`array<string>`	否	Reference images, up to 10 publicly accessible URLs. Mention them in the prompt as `@image_1`, `@image_2`, … in array order. 默认值：`[]`。 maxItems: `10`.
`input.video_urls`	`array<string>`	否	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. 默认值：`[]`。 maxItems: `5`.
`input.keep_original_sound`	`boolean`	否	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. 默认值：`false`。示例：`false`。
`input.elements`	`array<object>`	否	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. 默认值：`[]`。 maxItems: `7`.
`input.elements[].name`	`string`	是	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}$`. 示例：`Hero`。
`input.elements[].image_urls`	`array<string>`	否	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`	否	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`	否	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. 可选值：`character` / `animal` / `prop` / `costume` / `scene` / `effect` / `others`。示例：`character`。
`input.elements[].description`	`string`	否	Optional subject description. Maximum 100 characters. maxLength: `100`.
`input.elements[].voice_url`	`string`	否	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`	否	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`. 默认值：`"image"`。可选值：`image` / `video`。示例：`image`。

请求示例

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"
      }
    ]
  }
}

响应

200 — Request Successful

参数	类型	必填	说明
`code`	`integer`	否	请读取响应字段，并根据返回状态处理后重试。
`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"
  }
}

回调

videoTaskCompleted

回调地址：{request.body#/callBackUrl}（即请求体里的 callBackUrl）。

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

回调体参数

参数	类型	必填	说明
`code`	`integer`	是	Unified callback code: `200` for success, `501` for failure. 可选值：`200` / `501`。示例：`200`。
`msg`	`string`	是	Unified callback message. 可选值：`Playground task completed successfully.` / `Playground task failed.`。示例：`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. 可选值：`kling-4.0/flash-reference-to-video`。示例：`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. 可选值：`success` / `fail`。示例：`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 ​

接口 ​

Materials and References ​

Query Task Status ​

Related Resources ​

请求参数 ​

请求体 (application/json) ​

请求示例 ​

响应 ​

200 — Request Successful ​

回调 ​

videoTaskCompleted ​

Kling 4.0 Flash Reference To Video

接口

Materials and References

Query Task Status

Related Resources

请求参数

请求体 (application/json)

请求示例

响应

200 — Request Successful

回调

videoTaskCompleted