Kling 3.0 Omni 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.

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.

Related Resources

• 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-3.0-omni/reference-to-video model Default："kling-3.0-omni/reference-to-video"。 Allowed values：kling-3.0-omni/reference-to-video。 示例：kling-3.0-omni/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	object	object`

Request Example

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-omni/reference-to-video",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "Generate a video of the character walking along a city street, using the character appearance in the reference images.",
    "image_urls": [
      "https://example.com/character-reference.png"
    ],
    "customize_multi_shots": true,
    "multi_prompt": [
      {
        "prompt": "A wide shot of the character walking through the city.",
        "duration": 2
      },
      {
        "prompt": "A close-up of the character looking toward the camera.",
        "duration": 3
      }
    ],
    "audio": true,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "duration": 5,
    "elements": []
  }
}'

{
  "model": "kling-3.0-omni/reference-to-video",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "Generate a video of the character walking along a city street, using the character appearance in the reference images.",
    "image_urls": [
      "https://example.com/character-reference.png"
    ],
    "customize_multi_shots": true,
    "multi_prompt": [
      {
        "prompt": "A wide shot of the character walking through the city.",
        "duration": 2
      },
      {
        "prompt": "A close-up of the character looking toward the camera.",
        "duration": 3
      }
    ],
    "audio": true,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "duration": 5,
    "elements": []
  }
}

Response

200 — Request Successful

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_kling-2.6_1765182425861"
  }
}

Callback

videoTaskCompleted

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

The system sends this callback when the kling-3.0-omni/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	是	—
data.taskId	string	是	The unique task identifier.
data.model	string	是	The model used for the task. Allowed values：kling-3.0-omni/reference-to-video。 示例：kling-3.0-omni/reference-to-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

{
  "code": 200,
  "msg": "Playground task completed successfully.",
  "data": {
    "taskId": "task_example_video_webhook_001",
    "model": "kling-3.0-omni/reference-to-video",
    "state": "success",
    "param": "{\"input\":\"{\\\"prompt\\\":\\\"Generate a video of the character walking along a city street, using the character appearance in the reference images.\\\",\\\"image_urls\\\":[\\\"https://example.com/character-reference.png\\\"],\\\"customize_multi_shots\\\":true,\\\"multi_prompt\\\":[{\\\"prompt\\\":\\\"A wide shot of the character walking through the city.\\\",\\\"duration\\\":2},{\\\"prompt\\\":\\\"A close-up of the character looking toward the camera.\\\",\\\"duration\\\":3}],\\\"audio\\\":true,\\\"resolution\\\":\\\"720p\\\",\\\"aspect_ratio\\\":\\\"16:9\\\",\\\"duration\\\":5,\\\"elements\\\":[]}\",\"callBackUrl\":\"https://example.com/callback\",\"model\":\"kling-3.0-omni/reference-to-video\"}",
    "resultJson": "{\"resultUrls\":[\"https://example.com/generated-video.mp4\"]}",
    "costTime": 12,
    "completeTime": 1234567890,
    "createTime": 1234560000,
    "updateTime": 1234567890,
    "creditsConsumed": 1.23
  }
}

Task failed

{
  "code": 501,
  "msg": "Playground task failed.",
  "data": {
    "taskId": "task_example_video_webhook_001",
    "model": "kling-3.0-omni/reference-to-video",
    "state": "fail",
    "param": "{\"input\":\"{\\\"prompt\\\":\\\"Generate a video of the character walking along a city street, using the character appearance in the reference images.\\\",\\\"image_urls\\\":[\\\"https://example.com/character-reference.png\\\"],\\\"customize_multi_shots\\\":true,\\\"multi_prompt\\\":[{\\\"prompt\\\":\\\"A wide shot of the character walking through the city.\\\",\\\"duration\\\":2},{\\\"prompt\\\":\\\"A close-up of the character looking toward the camera.\\\",\\\"duration\\\":3}],\\\"audio\\\":true,\\\"resolution\\\":\\\"720p\\\",\\\"aspect_ratio\\\":\\\"16:9\\\",\\\"duration\\\":5,\\\"elements\\\":[]}\",\"callBackUrl\":\"https://example.com/callback\",\"model\":\"kling-3.0-omni/reference-to-video\"}",
    "failCode": "400",
    "failMsg": "<error detail>",
    "costTime": 12,
    "creditsConsumed": 0
  }
}