Omni video generation

feature_video references a video's features and motion rhythm; base_video edits an existing video. Images, videos, elements, and voices may total up to 15 items and must also meet each asset type's limits. Elements and voices use existing IDs; asset management APIs are not included on this page.

POST/kling/omni-video/kling-4.0

Combine prompts, images, videos, elements, and voices to generate or edit video. feature_video provides a video reference; base_video enables editing. Omni uses the same Kling 4.0 model as the other two generation endpoints.

Authorization

bearerAuth

AuthorizationBearer <token>

Use a platform API Key: Authorization: Bearer your-api-key.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

contents*array<||||>

A prompt with optional reference assets; images, videos, elements, and voices total up to 15 items and must also satisfy individual limits.

Items1 <= items

settings?

options?

Response Body

`application/json`

curl -X POST "https://api.agtcloud.cn/kling/omni-video/kling-4.0" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "type": "prompt",
        "text": "Use the visual style of @scene to generate an aerial coastal video."
      },
      {
        "type": "refer_image",
        "id": "scene",
        "url": "https://example.com/scene.jpg"
      }
    ],
    "settings": {
      "duration": 5,
      "resolution": "1080p",
      "aspect_ratio": "adaptive"
    }
  }'

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "REQUEST_ID",
  "data": {
    "id": "123456789012345678",
    "status": "submitted",
    "message": "",
    "create_time": 1792713600000,
    "update_time": 1792713600000
  }
}

Asset types and references

contents must contain a prompt item type: "prompt". Add other assets as needed. id is used for @reference in prompts; all supplied asset reference IDs must be unique within the task.

Asset	`type`	Source and required fields
Image	`first_frame` / `middle_frame` / `last_frame` / `refer_image`	`url` required; URL or Base64; `id` optional
Video	`feature_video` / `base_video`	`url` required; video URL; `id` optional
Element	`element`	Both `element_id` and `id` required
Voice	`voice`	Both `voice_id` and `id` required

element_id is a system-generated element ID obtained from element APIs. voice_id is a voice ID; use custom voice APIs for custom voices or the system preset voices documented by the provider. These are different from the asset reference id within this request.

See the official element library guide for element concepts and usage, and the official voice customization documentation for voice sources. Use asset IDs for the appropriate region; do not reuse preset IDs from another region.

Asset limits

Asset	Format and size	Dimensions, duration, and count
Image	JPG, JPEG, PNG; up to 30MB each	Width and height at least 300px; ratio 2:5–5:2; up to 10 images
Video	MP4, MOV; up to 300MB each	Each video and total input duration: 3–30 seconds; dimensions 700–4553px, at most 8294400 pixels; ratio 2:5–5:2; input 24–60fps, output 24fps
Element	Multi-image or video character elements	Up to 7 elements, including up to 3 video character elements
Voice	Existing custom or system preset voices	Up to 3

Asset combinations must also satisfy these limits:

Images, videos, elements, and voices total no more than 15 items.
Videos and video character elements total no more than 5; at most 1 base_video video.
Total input video duration includes feature_video, base_video, and the source videos of video character elements.

Common errors and troubleshooting

Response or error	What to check
HTTP 401, `Invalid token`	Check Bearer authentication and whether the API Key belongs to the requested site
HTTP 400, `contents cannot be empty`	Provide a nonempty `contents` array
HTTP 400, `prompt cannot be empty`	Add a nonempty text item of `type: "prompt"` to `contents`
HTTP 400, `contents[0].type ... is invalid`	Use the documented asset types and check the item at the reported index
HTTP 400, `Invalid element id`	Check `element_id`; do not substitute this request's reference `id` for the element ID
HTTP 400, `Invalid voice id`	Check `voice_id`; do not substitute this request's reference `id` for the voice ID
HTTP 400, `invalid JSON request body`	Check JSON quotes, commas, brackets, and comments

HTTP 400 may return code/message/data or an error object. Find the cause of fail_to_fetch_task in message, which may be a JSON string containing code/message/request_id. Keep the request ID for troubleshooting, but do not share your API Key.

Authorization

Request Body

Response Body

200application/json

400application/json

401application/json

Asset types and references

Asset limits

Common errors and troubleshooting

`application/json`

`application/json`

`application/json`