Kling 4.0 Reference To Video

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 videos with Kling 4.0 from reference images, reference videos, elements, and voices. Reference your materials in the prompt using @image_1, @video_1, or custom @name tags.

Materials and References

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

Material	Reference syntax	Limit
Reference images `images`	`@image_1`, `@image_2`, …	10 images
Reference videos `videos`	`@video_1`, `@video_2`, …	5 videos, each 2–30 seconds
Elements `elements`

Reference videos and video elements combined are limited to 5; all four material types combined are limited to 15.
An image element requires 2–4 images, with the first one as the primary shot; a video element requires one 3–8 second single-shot character video.
Custom names must be 1–20 characters of Chinese characters, letters, digits, or underscores, must be unique (case-insensitive), and must not use reserved names such as image_N, video_N, first_frame, or last_frame.
Referencing an undeclared material returns a parameter error and the task is not created.

TIP

When aspect_ratio is omitted, the ratio adapts to your materials if any are provided, and falls back to 16:9 when none are. When videos is provided, keep_original_sound controls whether the original audio is kept; when videos is omitted, native audio is enabled by default.

Check Task Status

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

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

TIP

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

Model Market Overview — Browse all available models
Common API — Check account credits and usage

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/reference-to-video` model Default：`"kling-4.0/reference-to-video"`。 Allowed values：`kling-4.0/reference-to-video`。示例：`kling-4.0/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 示例：`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` or `voices` 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. 示例：`@Hero sits at the desk in @video_1, picks up the doll from @image_1, and greets using @Narrator`。
`input.duration`	`integer`	No	Output video duration in seconds. Integer from 3 to 30. Default: `5`. Default：`5`。示例：`5`。
`input.resolution`	`string`	No	Output resolution. `720p` or `1080p`. Default: `720p`. Default：`"720p"`。 Allowed values：`720p` / `1080p`。示例：`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`。示例：`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. Each side must be 300–65536 pixels; aspect ratio 0.40–2.5. Default：`[]`。
`input.video_urls`	`array<string>`	No	Reference videos, up to 5 clips, each 2–30 seconds. Mention them in the prompt as `@video_1`, `@video_2`, …. Reference videos plus video subjects in `elements` cannot exceed 5 in total. Default：`[]`。
`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`。示例：`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`, `elements`, and `voices` together cannot exceed 15 items. Default：`[]`。
`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` and `voices` (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`. 示例：`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.
`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.
`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`。示例：`character`。
`input.elements[].description`	`string`	No	Optional subject description. Maximum 100 characters.
`input.elements[].voice_url`	`string`	No	Optional reference audio bound to this subject. It cannot be mentioned with `@` on its own and does not count toward the `voices` quota. Only character subjects can bind audio: for image subjects `tag` must be `character` or omitted; for video subjects, if omitted and the video contains speech, that speech is used automatically.
`input.voices`	`array<object>`	No	Standalone voice references used only for this task. Up to 3 items. Mention them in the prompt as `@name`. Audio bound on a subject via `voice_url` is separate and does not count toward this quota. Default：`[]`。
`input.voices[].name`	`string`	Yes	The name used in the prompt as `@Narrator`. 1–20 characters; Chinese, letters, digits, and underscore only. Must be unique across `elements` and `voices` (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`. 示例：`Narrator`。
`input.voices[].audio_url`	`string`	Yes	Publicly accessible reference audio URL. Required. The task fails if no usable voice can be detected.

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-4.0/reference-to-video",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "@Hero sits at the desk in @video_1, picks up the doll from @image_1, and greets using @Narrator",
    "duration": 10,
    "resolution": "1080p",
    "image_urls": [
      "https://example.com/doll.png"
    ],
    "video_urls": [
      "https://example.com/room.mp4"
    ],
    "keep_original_sound": false,
    "elements": [
      {
        "name": "Hero",
        "image_urls": [
          "https://example.com/hero-front.jpg",
          "https://example.com/hero-side.jpg"
        ],
        "tag": "character",
        "description": "Young man in a red jacket"
      }
    ],
    "voices": [
      {
        "name": "Narrator",
        "audio_url": "https://example.com/narrator.mp3"
      }
    ]
  }
}'

json

{
  "model": "kling-4.0/reference-to-video",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "@Hero sits at the desk in @video_1, picks up the doll from @image_1, and greets using @Narrator",
    "duration": 10,
    "resolution": "1080p",
    "image_urls": [
      "https://example.com/doll.png"
    ],
    "video_urls": [
      "https://example.com/room.mp4"
    ],
    "keep_original_sound": false,
    "elements": [
      {
        "name": "Hero",
        "image_urls": [
          "https://example.com/hero-front.jpg",
          "https://example.com/hero-side.jpg"
        ],
        "tag": "character",
        "description": "Young man in a red jacket"
      }
    ],
    "voices": [
      {
        "name": "Narrator",
        "audio_url": "https://example.com/narrator.mp3"
      }
    ]
  }
}

Response

200 — Request Successful

参数	类型	必填	说明
`code`	`integer`	否	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 可选值：`200` / `401` / `402` / `404` / `422` / `429` / `433` / `455` / `500` / `501` / `505`。示例：`200`。
`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-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/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`。示例：`200`。
`msg`	`string`	是	Unified callback message. Allowed values：`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.creditsConsumed`	`number`	否	Credits consumed by the task. `0` for failed tasks.
`data.model`	`string`	是	The model used for the task. Allowed values：`kling-4.0/reference-to-video`。示例：`kling-4.0/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`, `voices`).
`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`。示例：`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 30 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,
    "creditsConsumed": 425,
    "model": "kling-4.0/reference-to-video",
    "param": "{\"input\":\"{\\\"duration\\\":10,\\\"aspect_ratio\\\":\\\"9:16\\\",\\\"keep_original_sound\\\":false,\\\"elements\\\":[],\\\"voices\\\":[],\\\"image_urls\\\":[],\\\"video_urls\\\":[],\\\"prompt\\\":\\\"sits at the desk in\\\",\\\"resolution\\\":\\\"1080p\\\"}\",\"callBackUrl\":\"https://webhook.uutool.cn/bfa7de80-8dd8-4844-9e34-4032ddbbf3c1\",\"model\":\"kling-4.0/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,
    "creditsConsumed": 0,
    "failCode": "400",
    "failMsg": "video_1 duration must be between 2 and 30 seconds, got 45",
    "model": "kling-4.0/reference-to-video",
    "param": "{\"input\":\"{\\\"duration\\\":10,\\\"aspect_ratio\\\":\\\"9:16\\\",\\\"keep_original_sound\\\":false,\\\"elements\\\":[],\\\"voices\\\":[],\\\"image_urls\\\":[],\\\"video_urls\\\":[\\\"https://example.com/room.mp4\\\"],\\\"prompt\\\":\\\"sits at the desk in @video_1\\\",\\\"resolution\\\":\\\"1080p\\\"}\",\"callBackUrl\":\"https://webhook.uutool.cn/bfa7de80-8dd8-4844-9e34-4032ddbbf3c1\",\"model\":\"kling-4.0/reference-to-video\"}",
    "state": "fail",
    "taskId": "1f0176644624b187c7f6add97986875d",
    "updateTime": 1792668903000
  },
  "msg": "Playground task failed."
}

Kling 4.0 Reference To Video ​

Endpoint ​

Materials and References ​

Check Task Status ​

Related Resources ​

Request Parameters ​

Body (application/json) ​

Request Example ​

Response ​

200 — Request Successful ​

Callback ​

videoTaskCompleted ​

Kling 4.0 Reference To Video

Endpoint

Materials and References

Check Task Status

Related Resources

Request Parameters

Body (application/json)

Request Example

Response

200 — Request Successful

Callback

videoTaskCompleted