Developer Docs/Kling Omni API

Kling Omni API

Build Kling Omni integrations with A2E. Review authentication, request parameters, task creation, status, and result endpoints.

Open API ExplorerTry the ToolProduct GuideOpenAPI JSON

Overview

An extended variant of Kling with additional control parameters for output style, generation quality, and advanced scene handling.

Primary Endpoint

POST/api/v1/klingOmni/start

Generate videos using Kling Omni API (model: kling-v3-omni). This is a simplified wrapper around the official Kling API. **Key Features:** - Multi-reference images: up to 7 images, use `<<<image_N>>>` tags in prompt - Multi-shot editing: AI Director (intelligence) or manual (customize) storyboard - Native sound generation via `sound` parameter - Flexible duration: 3–15 seconds **Simplified vs Official API:** - `image_list`: accepts `string[]` (image URLs); official uses `[{image_url, type?}]`, auto-converted on server - `sound`: accepts `boolean`; official uses `"on"/"off"`, auto-converted on server - `multi_prompt`: items need `prompt` + `duration`; server auto-adds `index` field for official API - `prompt` is required when `multi_shot=false` or `shot_type=intelligence` - `multi_prompt` total duration must equal `duration` when `shot_type=customize` - `element_ids`: `string[]` of Element `asset_id` values (not `_id`). Create an Element with `POST /api/v1/klingAssets/elements` (`name`, frontal `image_url`, 1–3 `reference_image_urls`), poll `GET /api/v1/klingAssets` until `status` is `succeed`, then pass its `asset_id`. With `image_list`, at most 3 Elements are allowed. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body when using the optional controls documented in the request schema. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/klingOmni/allRecords` — Get all Kling Omni video records. - `GET /api/v1/klingOmni/{_id}` — Get Kling Omni video detail. - `PUT /api/v1/klingOmni/{_id}` — Update Kling Omni video name. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).

Request Parameters

NameTypeRequiredDescription
namestringNoTask name (internal use)
promptstringNoText prompt. Use <<<image_N>>> to reference images. Required when multi_shot=false or shot_type=intelligence.
image_listarray<string>NoReference image URLs (up to 7, jpg/jpeg/png, max 10MB). Simplified: pass URLs directly; server converts to official [{image_url}] format.
element_idsarray<string>NoKling Elements to include, as an array of `asset_id` strings (not the record `_id`). Create an Element with POST /api/v1/klingAssets/elements, then poll GET /api/v1/klingAssets until its `status` is succeed and read `asset_id`. Only your own succeeded Elements are accepted; duplicate IDs are rejected; with image_list, at most 3 Elements are allowed.
modeenum: std | proNoVideo generation mode. std=standard (720p), pro=professional (1080p); default: "std"
durationstringNoVideo duration in seconds (3–15); default: "5"
aspect_ratioenum: 16:9 | 9:16 | 1:1Nodefault: "16:9"
soundbooleanNoEnable native sound generation. Simplified: pass boolean; server converts to official 'on'/'off'.; default: false
multi_shotbooleanNoEnable multi-shot mode; default: false
shot_typeenum: intelligence | customizeNoShot type. Required when multi_shot=true.
multi_promptarray<object>NoManual storyboard (required when shot_type=customize, 1–6 items, total duration must equal duration). Server auto-adds index field for official API.
multi_prompt[].promptstringYesPrompt for this shot (max 512 chars)
multi_prompt[].durationstringYesDuration in seconds
webhook_urlstringNoHTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.; maxLength: 2048
webhook_tokenstringNoOptional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.; maxLength: 256
Request schema and conditional rules
{
  "allOf": [
    {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Task name (internal use)",
          "example": "My Kling Omni Video"
        },
        "prompt": {
          "type": "string",
          "description": "Text prompt. Use <<<image_N>>> to reference images. Required when multi_shot=false or shot_type=intelligence.",
          "example": "<<<image_1>>> walks towards <<<image_2>>> in a sunny park"
        },
        "image_list": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Reference image URLs (up to 7, jpg/jpeg/png, max 10MB). Simplified: pass URLs directly; server converts to official [{image_url}] format.",
          "example": [
            "https://example.com/ref1.jpg"
          ]
        },
        "element_ids": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Kling Elements to include, as an array of `asset_id` strings (not the record `_id`). Create an Element with POST /api/v1/klingAssets/elements, then poll GET /api/v1/klingAssets until its `status` is succeed and read `asset_id`. Only your own succeeded Elements are accepted; duplicate IDs are rejected; with image_list, at most 3 Elements are allowed.",
          "example": [
            "860412385741664324"
          ]
        },
        "mode": {
          "type": "string",
          "enum": [
            "std",
            "pro"
          ],
          "description": "Video generation mode. std=standard (720p), pro=professional (1080p)",
          "default": "std"
        },
        "duration": {
          "type": "string",
          "description": "Video duration in seconds (3–15)",
          "default": "5"
        },
        "aspect_ratio": {
          "type": "string",
          "enum": [
            "16:9",
            "9:16",
            "1:1"
          ],
          "default": "16:9"
        },
        "sound": {
          "type": "boolean",
          "description": "Enable native sound generation. Simplified: pass boolean; server converts to official 'on'/'off'.",
          "default": false
        },
        "multi_shot": {
          "type": "boolean",
          "description": "Enable multi-shot mode",
          "default": false
        },
        "shot_type": {
          "type": "string",
          "enum": [
            "intelligence",
            "customize"
          ],
          "description": "Shot type. Required when multi_shot=true."
        },
        "multi_prompt": {
          "type": "array",
          "description": "Manual storyboard (required when shot_type=customize, 1–6 items, total duration must equal duration). Server auto-adds index field for official API.",
          "items": {
            "type": "object",
            "required": [
              "prompt",
              "duration"
            ],
            "properties": {
              "prompt": {
                "type": "string",
                "description": "Prompt for this shot (max 512 chars)",
                "example": "<<<image_1>>> stands up and waves"
              },
              "duration": {
                "type": "string",
                "description": "Duration in seconds",
                "example": "3"
              }
            }
          }
        }
      },
      "required": []
    },
    {
      "$ref": "#/components/schemas/WebhookInput"
    }
  ]
}

Response Fields

code: integer
message: string
data: object
data._id: string
Task ID; use it with the detail, update and delete endpoints
data.name: string
data.prompt: string
data.image_list: array<string>
Reference image URLs
data.mode: enum: std | pro | 4k
data.duration: string
Video duration in seconds
data.aspect_ratio: enum: 16:9 | 9:16 | 1:1
data.sound: boolean
data.multi_shot: boolean
data.shot_type: enum: intelligence | customize
data.multi_prompt: array<object>
data.multi_prompt[].prompt: string
data.multi_prompt[].duration: string
data.multi_shot_mode: enum: off | auto | manual
data.current_status: enum: initialized | sent | queued | processing | completed | failed
completed and failed are terminal states
data.result_url: string
Generated video URL, empty until the task is completed
data.cover_url: string
data.coins: number
Credits charged for this task
data.is_downloaded: boolean
data.is_previewed: boolean
data.failed_code: string
data.failed_message: string
data.failed_reason: string
Public failure reason, present only when the task failed
data.createdAt: string
data.remainingDays: integer
Days left before the result expires
data.expirationDate: string
data.isExpired: boolean
data.expirationDays: integer
Retention period in days
data.shareId: string
Share identifier, present only for completed tasks
trace_id: string
Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.

Request Example

curl -X POST "https://www.a2e.com.cn/api/v1/klingOmni/start" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Related Endpoints

GET/api/v1/klingOmni/{_id}

Get Kling Omni video detail

POST/api/v1/klingOmni/start

Start Kling Omni video generation

GET/api/v1/klingOmni/allRecords

Get all Kling Omni video records

POST/api/v1/klingOmni/batchDetail

Batch get Kling Omni video details

PUT/api/v1/klingOmni/{_id}

Update Kling Omni video name

DELETE/api/v1/klingOmni/{_id}

Delete Kling Omni video

Responses

200

Video generation task started successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.

400

Bad Request - Invalid parameters

401

Unauthorized - Invalid or missing bearer token

Kling Omni API Documentation