Create Kling Omni Video Task

Dedicated route: POST https://maasunion.com/kling/v1/videos/omni · GET https://maasunion.com/kling/v1/videos/omni/{task_id}
Upstream capability: Kling OmniVideo (/v1/videos/omni-video)
Official reference: Kling OmniVideo API

Overview

The Omni model can generate videos from prompts combined with images, subjects, and videos, supporting:

Text-to-Video, Image-to-Video, and first/last-frame video
Image / subject reference video
Instruction-based transform (video editing)
Video reference (camera movement / style / next-shot generation)
Multi-shot video (kling-v3-omni)
Sound effects (kling-v3-omni, sound: on)

Reference materials in the prompt using <<<>>>:

<<<image_1>>> — the 1st reference image (corresponds to image_list[0])
<<<element_1>>> — the 1st subject (corresponds to element_list[0])
<<<video_1>>> — the 1st reference video (corresponds to video_list[0])

The gateway keeps the request/response format consistent with the official Kling OmniVideo API, and the request body is forwarded upstream as-is. No need to use the text2video / image2video style.

Dedicated Route

Item	Description
Create task	`POST https://maasunion.com/kling/v1/videos/omni`
Query task	`GET https://maasunion.com/kling/v1/videos/omni/{task_id}`
Request format	Consistent with the official Kling OmniVideo API (native JSON pass-through)
Response format	Consistent with the official Kling OmniVideo API (`data.task_id` replaced by the gateway task ID)

Supported Models

model_name	Description
`kling-video-o1`	Omni O1, mainly single-shot
`kling-v3-omni`	Omni V3, supports multi-shot, sound effects, etc.

Authentication

Header	Required	Description
`Authorization`	Yes	`Bearer {your_api_token}`, the API token issued by the gateway
`Content-Type`	Required for POST	`application/json`

Clients do not need to (and should not) pass the upstream key.

Prompt Reference Syntax

The prompt must not exceed 2,500 characters
Use the <<<>>> format to specify subjects, images, or videos:
- <<<image_1>>>, <<<image_2>>> — reference the image at the corresponding index in image_list
- <<<element_1>>>, <<<element_2>>> — reference the subject at the corresponding index in element_list
- <<<video_1>>> — reference the video at the corresponding index in video_list
Supported scopes vary by model version and video mode; see the Kling capability map
More effects and prompt examples: Kling Omni Model Examples

Request Body Parameters

POST https://maasunion.com/kling/v1/videos/omni

Submit a video generation task. On success, the task ID is returned; poll the query task endpoint for the result.

Parameter	Type	Required	Default	Description
`model_name`	string	Yes	—	Model name: `kling-video-o1`, `kling-v3-omni`
`multi_shot`	boolean	No	`false`	Whether to use multi-shot. `true` makes `prompt` invalid; `false` makes `shot_type` and `multi_prompt` invalid
`shot_type`	string	Conditional	—	Shot type: `customize` (custom) / `intelligence` (smart). Required when `multi_shot=true`
`prompt`	string	Conditional	—	Text prompt, ≤ 2,500 characters. Must not be empty when `multi_shot=false`, or when `multi_shot=true` and `shot_type=intelligence`
`multi_prompt`	array	Conditional	—	Shot list, see multi_prompt below. Must not be empty when `multi_shot=true` and `shot_type=customize`
`image_list`	array	No	—	Reference image list, see image_list below
`element_list`	array	No	—	Subject reference list, see element_list below
`video_list`	array	No	—	Reference video list, see video_list below
`sound`	string	No	`off`	Generate sound: `on` / `off`. Must be `off` if reference videos are provided
`mode`	string	No	`pro`	Generation mode: `std` (720P) / `pro` (1080P) / `4k` (4K)
`aspect_ratio`	string	Conditional	—	Aspect ratio: `16:9`, `9:16`, `1:1`. Usually required when no first frame or video edit is used
`duration`	string	No	`5`	Video duration in seconds, enum `3`–`15`; some scenarios support 3–10
`watermark_info`	object	No	—	Watermark config, e.g. `{"enabled": false}`
`callback_url`	string	No	—	Callback URL for task status change
`external_task_id`	string	No	—	Custom task ID (unique on user side, saved upstream)

multi_prompt

Defines each shot by index, prompt, and duration:

At most 6 shots, at least 1
Each shot prompt ≤ 512 characters
Each shot duration ≥ 1 second and ≤ total task duration
The sum of all shot durations must equal the total duration

"multi_prompt": [
  { "index": 1, "prompt": "string", "duration": "5" },
  { "index": 2, "prompt": "string", "duration": "5" }
]

image_list

Reference image list, including subject, scene, style, etc., which can also be used as the first or last frame to generate video.

Parameter	Type	Required	Description
`image_url`	string	Yes	Image URL or Base64 (supports `data:image/...;base64,` prefix; the gateway auto-normalizes it)
`type`	string	No	`first_frame` / `end_frame`. If `end_frame` is set, `first_frame` must also be set

Image requirements:

Item	Limit
Format	`.jpg` / `.jpeg` / `.png`
File size	≤ 10 MB
Dimensions	Width and height both ≥ 300 px
Aspect ratio	1:2.5 ~ 2.5:1

Other rules:

If the image is not a first/last frame, do not set the type parameter
Last frame alone is not supported (a last frame must have a first frame)
First/last-frame video generation cannot use the video editing feature
When using kling-video-o1, if the array contains more than 2 images, first/last frames are not supported
image_url must not be empty

element_list

Subject reference list, based on IDs in the Kling subject library.

Parameter	Type	Required	Description
`element_id`	long	Yes	Subject ID in the Kling subject library

Subjects are divided into video-role subjects (video character subjects) and image-role subjects (multi-image subjects), with different applicable scopes. For more details: Kling "Subject Library 3.0" Guide.

Reference video, fetched by URL. Can be used as a feature reference video or as the video to be edited.

Parameter	Type	Required	Default	Description
`video_url`	string	Yes	—	Video URL
`refer_type`	string	No	`base`	`feature` (feature reference) / `base` (to be edited, instruction-based transform)
`keep_original_sound`	string	No	—	Keep original sound: `yes` / `no` (also takes effect for `feature` type)

Video requirements:

Item	Limit
Format	MP4 / MOV only
Duration	≥ 3 seconds; upper limit depends on model version
Resolution	720 px ~ 2160 px (width/height)
Frame rate	24 ~ 60 fps (output is 24 fps)
Count	At most 1 video
Size	≤ 200 MB

Other rules:

When the reference video is a video to be edited (refer_type=base), video first/last frames cannot be defined
When a reference video is provided, sound must be off
video_url must not be empty

mode

Mode	Output resolution
`std`	720P
`pro`	1080P
`4k`	4K

Request Examples

Image-to-Video

curl --request POST \
  --url "https://maasunion.com/kling/v1/videos/omni" \
  --header "Authorization: Bearer sk-xxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "model_name": "kling-video-o1",
    "prompt": "Have the person in <<<image_1>>> wave to the camera",
    "image_list": [
      {
        "image_url": "https://example.com/reference.png"
      }
    ],
    "duration": "5",
    "mode": "pro",
    "aspect_ratio": "16:9"
  }'

Multi-shot (kling-v3-omni)

curl --request POST \
  --url "https://maasunion.com/kling/v1/videos/omni" \
  --header "Authorization: Bearer sk-xxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "model_name": "kling-v3-omni",
    "multi_shot": true,
    "shot_type": "customize",
    "prompt": "",
    "multi_prompt": [
      {
        "index": 1,
        "prompt": "<<<image_1>>>A person sitting on a park bench, sunlight filtering through trees.",
        "duration": "2"
      },
      {
        "index": 2,
        "prompt": "A car speeding down a rainy street, headlights glowing.",
        "duration": "3"
      }
    ],
    "image_list": [
      { "image_url": "https://example.com/frame.png" }
    ],
    "mode": "pro",
    "sound": "on",
    "aspect_ratio": "16:9",
    "duration": "5"
  }'

Response Example (200)

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "task_id": "task_xxxxxxxx",
    "task_info": {
      "external_task_id": "string"
    },
    "task_status": "submitted",
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  }
}

Field	Description
`code`	Error code; `0` means success
`message`	Error or status message
`request_id`	Request trace ID
`data.task_id`	Gateway task ID (used for subsequent queries; field name matches the official one)
`data.task_status`	`submitted` / `processing` / `succeed` / `failed`
`data.created_at` / `updated_at`	Unix millisecond timestamps

Note: The response structure is consistent with Kling's official one. data.task_id is the public task ID assigned by the gateway; please save it for later queries.

Scenario Examples

Image / Subject Reference

Reference characters, props, scenes, and other elements in images/subjects to generate videos flexibly.

curl --location "https://maasunion.com/kling/v1/videos/omni" \
  --header "Authorization: Bearer sk-xxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "model_name": "kling-video-o1",
    "prompt": "<<<image_1>>>Stroll through the streets of Tokyo, run into <<<element_1>>> and <<<element_2>>>, and jump into <<<element_2>>>’s arms. The video style matches <<<image_2>>>",
    "image_list": [
      { "image_url": "https://example.com/a.png" },
      { "image_url": "https://example.com/b.png" }
    ],
    "element_list": [
      { "element_id": 123456789 },
      { "element_id": 987654321 }
    ],
    "mode": "pro",
    "aspect_ratio": "1:1",
    "duration": "7"
  }'

Instruction-based Transform (Video Edit)

Edit a video, such as adding/removing/modifying content, switching shots, or changing perspectives.

curl --location "https://maasunion.com/kling/v1/videos/omni" \
  --header "Authorization: Bearer sk-xxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "model_name": "kling-video-o1",
    "prompt": "Put the crown from <<<image_1>>> on the girl in blue in <<<video_1>>>",
    "image_list": [{ "image_url": "https://example.com/crown.png" }],
    "video_list": [{
      "video_url": "https://example.com/input.mp4",
      "refer_type": "base",
      "keep_original_sound": "yes"
    }],
    "mode": "pro"
  }'

Video Reference (Camera Movement / Style)

Generate the next shot based on a reference video, or reference its style/camera movement.

curl --location "https://maasunion.com/kling/v1/videos/omni" \
  --header "Authorization: Bearer sk-xxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "model_name": "kling-video-o1",
    "prompt": "Reference the camera movement of <<<video_1>>>, generate a video: <<<element_1>>> and <<<element_2>>> strolling through the streets of Tokyo",
    "image_list": [{ "image_url": "https://example.com/scene.png" }],
    "element_list": [
      { "element_id": 123456789 },
      { "element_id": 987654321 }
    ],
    "video_list": [{
      "video_url": "https://example.com/ref.mp4",
      "refer_type": "feature",
      "keep_original_sound": "yes"
    }],
    "mode": "pro",
    "aspect_ratio": "1:1",
    "duration": "7"
  }'

Video Extension (Generate Next Shot)

curl --location "https://maasunion.com/kling/v1/videos/omni" \
  --header "Authorization: Bearer sk-xxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "model_name": "kling-video-o1",
    "prompt": "Based on <<<video_1>>>, generate the next shot",
    "video_list": [{
      "video_url": "https://example.com/ref.mp4",
      "refer_type": "feature",
      "keep_original_sound": "yes"
    }],
    "mode": "pro"
  }'

First & Last Frame

curl --location "https://maasunion.com/kling/v1/videos/omni" \
  --header "Authorization: Bearer sk-xxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "model_name": "kling-video-o1",
    "prompt": "The person in the video dances",
    "image_list": [
      { "image_url": "https://example.com/start.png", "type": "first_frame" },
      { "image_url": "https://example.com/end.png", "type": "end_frame" }
    ],
    "mode": "pro"
  }'

Text-to-Video

curl --location "https://maasunion.com/kling/v1/videos/omni" \
  --header "Authorization: Bearer sk-xxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "model_name": "kling-video-o1",
    "prompt": "A cat plays the piano",
    "mode": "pro",
    "aspect_ratio": "1:1",
    "duration": "7"
  }'

Multi-shot Text-to-Video (kling-v3-omni)

curl --location "https://maasunion.com/kling/v1/videos/omni" \
  --header "Authorization: Bearer sk-xxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "model_name": "kling-v3-omni",
    "multi_shot": true,
    "shot_type": "customize",
    "prompt": "",
    "multi_prompt": [
      { "index": 1, "prompt": "Two friends talking under a streetlight at night.", "duration": "2" },
      { "index": 2, "prompt": "A runner sprinting through a forest, leaves flying.", "duration": "3" },
      { "index": 3, "prompt": "A woman hugging a cat, smiling. Soft sunlight.", "duration": "3" }
    ],
    "image_list": [],
    "sound": "on",
    "element_list": [],
    "video_list": [],
    "mode": "pro",
    "aspect_ratio": "16:9",
    "duration": "8"
  }'

Capability Matrix

Feature	kling-video-o1	kling-v3-omni
Text-to-Video	✅	✅
Image-to-Video	✅	✅
Multi-image Reference	✅	✅
First & Last Frame	✅	✅
Subject Reference	✅	✅
Instruction-based Transform (Video Edit)	✅	✅
Video Reference (Next Shot)	✅	✅
Multi-shot	❌	✅
Sound Effects (`sound`)	❌	✅

Mode	kling-video-o1	kling-v3-omni
std (720P)	✅	✅
pro (1080P)	✅	✅
4k	✅	✅

Element Quantity Limits

Without Reference Video

Scenario	Reference Images + Multi-image Subjects (Total)	Video-role Subjects
Multi-image subjects only	≤ 7	—
Video-role subjects only	—	≤ 3
Both	≤ 4	≤ 3

With Reference Video

Video-role subjects are not supported
The total of reference images and multi-image subjects must be ≤ 4

First & Last Frame Scenario

kling-v3-omni supports at most 3 subjects when using first & last frame
kling-video-o1 does not support subjects when using first & last frame

Billing

The gateway bills based on the credits consumed upstream by Kling:

Scenario	Gateway Behavior
Pre-deduct estimate	At submission, credits are estimated and pre-deducted based on model, mode (std/pro/4k), duration, etc.
Actual settlement	After the task succeeds, credits are settled by the actual `final_unit_deduction`
Credit price	Depends on the configured model price / multiplier

The final_unit_deduction in the response is the actual number of credits deducted upstream and can be used for reconciliation.

FAQ

When can `duration` be specified?

Text-to-Video, Image-to-Video (no first/last frame): optional, 3–10 seconds
Video Edit (refer_type=base): cannot be specified; aligns with the input video
Other scenarios (image/subject without video, or video with refer_type=feature): optional, 3–10 seconds

When is `aspect_ratio` required?

Not supported: instruction-based transform (video edit), image-to-video with first/last frame
Usually required: text-to-video, image/subject reference, video reference, etc.

How do I extend a video?

Use "video reference": pass a video and drive the model with the prompt to "generate the next shot" or "generate the previous shot". See Video Extension.

What is the relationship between `multi_shot` and `prompt`?

When multi_shot=true, prompt is invalid; use multi_prompt (when shot_type=customize) or prompt (when shot_type=intelligence)
When multi_shot=false, shot_type and multi_prompt are invalid

Differences vs. text2video / image2video

Comparison	`/kling/v1/videos/omni`	`/kling/v1/videos/text2video`, etc.
Model	Omni (O1 / V3)	Traditional Kling video models
Parameters	Full official Omni parameters	Text-to-Video / Image-to-Video specific parameters
Multi-shot, video edit, subject reference	✅	❌
Request format	Consistent with the official OmniVideo	Gateway-normalized format

Error Handling

When code != 0, the request fails and message contains the error description. Common cases:

model_name not provided or not available for the current token
Invalid token or insufficient balance
Upstream parameter validation failure (e.g. multi-shot duration sum mismatches duration)
Content moderation block (see task_status=failed and task_status_msg on query)

Notes

Asynchronous task: The create endpoint only returns the task ID; you must poll the query task endpoint for the video URL.
Video URL validity: Generated URLs are valid for about 30 days (anti-hotlink); please download or persist them in time.
model_name is required: The request body must contain model_name.
Base64 images: The gateway automatically strips the data:image/...;base64, prefix before forwarding upstream.
When a reference video is provided: sound can only be off.
Gateway query: Please use the gateway task_id from the create response to query; do not use the upstream original ID.

Document updated: 2026-06-16