Kling 4.0 Keyframe 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 a video from first, middle, and last keyframe images with Kling 4.0. Mention frames in the prompt using @first_frame, @keyframe_1, and @last_frame.

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 query task status and obtain generation results

TIP

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

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

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/keyframe-to-video` model Default：`"kling-4.0/keyframe-to-video"`。 Allowed values：`kling-4.0/keyframe-to-video`。示例：`kling-4.0/keyframe-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 `@first_frame`, `@keyframe_1`, `@keyframe_2`, …, `@last_frame` to mention frames that you uploaded in this request. You can only mention frames that are actually provided. 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. 示例：`The girl in @first_frame walks out, passes the street in @keyframe_1, and arrives at the party in @last_frame`。
`input.duration`	`integer`	No	Output video duration in seconds. Integer from 3 to 30. Default: `5`. Also caps the total number of frames (first + middle + last): - 3 s → 4 frames - 4 s → 5 frames - 5 s → 6 frames - 6 s → 7 frames - 7 s → 8 frames - 8 s → 9 frames - 9 s or longer → 10 frames 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. Only used when no frame is provided (text-to-video); default is `16:9`. If any frame is provided, the output follows the first frame's aspect ratio. Allowed values：`auto` / `16:9` / `9:16` / `1:1` / `21:9`。示例：`auto`。
`input.first_frame_url`	`string`	No	First-frame image URL. Mention it in the prompt as `@first_frame`.
`input.keyframe_urls`	`array<string>`	No	Middle-frame image URLs, in chronological order. Up to 8 images, also limited by `duration`. Mention them in the prompt as `@keyframe_1`, `@keyframe_2`, …. Default：`[]`。
`input.last_frame_url`	`string`	No	Last-frame image URL. Mention it in the prompt as `@last_frame`.

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/keyframe-to-video",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "The girl in @first_frame walks out, passes the street in @keyframe_1, and arrives at the party in @last_frame",
    "duration": 10,
    "resolution": "720p",
    "first_frame_url": "https://example.com/first.png",
    "keyframe_urls": [
      "https://example.com/street.png"
    ],
    "last_frame_url": "https://example.com/party.png"
  }
}'

json

{
  "model": "kling-4.0/keyframe-to-video",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "The girl in @first_frame walks out, passes the street in @keyframe_1, and arrives at the party in @last_frame",
    "duration": 10,
    "resolution": "720p",
    "first_frame_url": "https://example.com/first.png",
    "keyframe_urls": [
      "https://example.com/street.png"
    ],
    "last_frame_url": "https://example.com/party.png"
  }
}

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-keyframe-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/keyframe-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/keyframe-to-video`。示例：`kling-4.0/keyframe-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`, `first_frame_url`, `keyframe_urls`, `last_frame_url`).
`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 frame-count error (`duration 5s allows at most 6 frames (first + keyframes + last), got 7`), a missing `first_frame_url`, an undeclared `@first_frame` / `@keyframe_N` / `@last_frame` mention, or an upstream original message about image fetch/moderation/size.

Task completed successfully

json

{
  "code": 200,
  "data": {
    "completeTime": 1792670085074,
    "costTime": 718,
    "createTime": 1792669367000,
    "creditsConsumed": 285,
    "model": "kling-4.0/keyframe-to-video",
    "param": "{\"input\":\"{\\\"duration\\\":10,\\\"keyframe_urls\\\":[],\\\"prompt\\\":\\\"女孩出门\\\",\\\"resolution\\\":\\\"720p\\\"}\",\"callBackUrl\":\"https://webhook.uutool.cn/bfa7de80-8dd8-4844-9e34-4032ddbbf3c1\",\"model\":\"kling-4.0/keyframe-to-video\"}",
    "resultJson": "{\"resultUrls\":[\"https://tempfile.aiquickdraw.com/k/ce115adfa78260a99009eebddac1d187_1_1792670083_1582.mp4\"]}",
    "state": "success",
    "taskId": "ce115adfa78260a99009eebddac1d187",
    "updateTime": 1792669367000
  },
  "msg": "Playground task completed successfully."
}

Task failed

json

{
  "code": 501,
  "data": {
    "completeTime": 1792670085074,
    "costTime": 718,
    "createTime": 1792669367000,
    "creditsConsumed": 0,
    "failCode": "400",
    "failMsg": "duration 5s allows at most 6 frames (first + keyframes + last), got 7",
    "model": "kling-4.0/keyframe-to-video",
    "param": "{\"input\":\"{\\\"duration\\\":5,\\\"first_frame_url\\\":\\\"https://example.com/first.png\\\",\\\"keyframe_urls\\\":[\\\"https://example.com/k1.png\\\",\\\"https://example.com/k2.png\\\",\\\"https://example.com/k3.png\\\",\\\"https://example.com/k4.png\\\",\\\"https://example.com/k5.png\\\"],\\\"last_frame_url\\\":\\\"https://example.com/last.png\\\",\\\"prompt\\\":\\\"女孩出门\\\",\\\"resolution\\\":\\\"720p\\\"}\",\"callBackUrl\":\"https://webhook.uutool.cn/bfa7de80-8dd8-4844-9e34-4032ddbbf3c1\",\"model\":\"kling-4.0/keyframe-to-video\"}",
    "state": "fail",
    "taskId": "ce115adfa78260a99009eebddac1d187",
    "updateTime": 1792669367000
  },
  "msg": "Playground task failed."
}

Kling 4.0 Keyframe To Video ​

Endpoint ​

Query Task Status ​

Related Resources ​

Request Parameters ​

Body (application/json) ​

Request Example ​

Response ​

200 — Request Successful ​

Callback ​

videoTaskCompleted ​

Kling 4.0 Keyframe To Video

Endpoint

Query Task Status

Related Resources

Request Parameters

Body (application/json)

Request Example

Response

200 — Request Successful

Callback

videoTaskCompleted