How to Generate Multi-Reference & Multi-Shot Video with Kling Omni via the Kling API

Introduction

Kling Omni is the one Kling endpoint that lets you blend several image references into a single shot and storyboard a multi-shot sequence — each scene with its own prompt and duration — in one API job, all from code against your own Kling account. Kling AI is the generative video service from Chinese short-video giant Kuaishou Technology, and useapi.net fronts it with a third-party Kling API that runs your own Kling account over a standard REST endpoint — no enterprise contract, no per-call billing from us. This guide covers Omni specifically. For plain text-to-video and start/end-frame image-to-video, see the core Kling tutorial.

What Omni does

POST /videos/omni is a single endpoint that selects a workflow from the inputs you pass. Three of those are what set Omni apart from the plain text-to-video and frames endpoints:

• Multi-image reference — pass up to 7 reference images (image_1…image_7) and weave each into the prompt with @image_1, @image_2, … syntax, so one shot can combine a character, a prop, and a background.
• Video Elements — reusable saved character/object references created once with POST /elements, then dropped into any later generation as @element_1 (or @object_1). Images and elements share the same pool of 7 slots, so the combined total can't exceed 7.
• Multi-shot (v3 only) — split one video into 2–6 sequential shots, each with its own shot_N_prompt and shot_N_duration, for storytelling with scene cuts in a single job.

Omni also handles a frames workflow (frame_start/frame_end) and a video-reference/transform workflow (video_1), but those overlap with the core endpoints — this guide focuses on the multi-reference, Video Elements, and multi-shot paths.

Two model versions exist, picked with omni_version: v3 (the default) and o1. Multi-shot and VIDEO-type elements are v3 only — o1 supports IMAGE elements and single-clip durations of 3–10s, while v3 runs 3–15s. Pick quality with mode: std (720p), pro (1080p), or 4k (v3 only). Durations of 7s and up, counts of 2–4, and 4K need a VIP Kling plan.

Pricing

You keep your normal Kling website subscription and add a single flat $15/month to useapi.net that covers API access to every supported service, with no per-generation surcharge from us — see the core Kling tutorial's pricing section and the Kling API overview live cost calculator.

This is the consumer-account route. Kuaishou's official Kling API bills per generation at developer rates on a separate developer account, while useapi.net automates the consumer account you already pay for at the website subscription price.

Generate a multi-reference video in two API calls

You need a useapi.net API token and a connected Kling account — export the token so the curl examples below run as-is:

export USEAPI_TOKEN="user:1234-..."

Generation is asynchronous — the create call returns a task object immediately, then you poll until the video is ready.

First, upload each reference image with POST /assets (raw bytes, an image Content-Type, max 10 MB, 300px minimum). It returns a Kling-hosted url:

curl "https://api.useapi.net/v1/kling/assets/?email=[e-mail]" \
  -H "Authorization: Bearer $USEAPI_TOKEN" \
  -H "Content-Type: image/jpeg" \
  --data-binary @character.jpg

{
  "status": 3,
  "url": "https://s21-kling.klingai.com/....jpg",
  "fileName": "abc123def456789.jpg"
}

1. Submit the job — POST https://api.useapi.net/v1/kling/videos/omni. Pass each uploaded URL as image_1, image_2, … and reference them by name in the prompt:

curl -X POST "https://api.useapi.net/v1/kling/videos/omni" \
  -H "Authorization: Bearer $USEAPI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A woman @image_1 walking through the garden @image_2, holding the lantern @image_3, camera pushing in slowly",
    "omni_version": "v3",
    "mode": "pro",
    "aspect_ratio": "16:9",
    "duration": "5",
    "image_1": "https://s21-kling.klingai.com/.../character.jpg",
    "image_2": "https://s21-kling.klingai.com/.../garden.jpg",
    "image_3": "https://s21-kling.klingai.com/.../lantern.jpg"
  }'

The response returns immediately with a task object of type m2v_omni_video. The task id you poll on is task.id (a number):

{
  "task": {
    "id": 123456789,
    "type": "m2v_omni_video",
    "status": 5,
    "status_name": "submitted",
    "status_final": false
  },
  "works": [],
  "status": 5,
  "status_name": "submitted",
  "status_final": false,
  "message": ""
}

The email field is required in the body only when you have more than one Kling account configured. A 500 from Kling almost always means a content-moderation rejection rather than a server fault — read the error text (the message field is generic and often misleading) to tell them apart. prompt maxes out at 1700 characters and references each input by its @-name (@image_1, @element_1, @video_1).

2. Poll for the result — GET https://api.useapi.net/v1/kling/tasks/{task_id}:

curl "https://api.useapi.net/v1/kling/tasks/123456789?email=[e-mail]" \
  -H "Authorization: Bearer $USEAPI_TOKEN"

The task is done when status_final is true. Success is status_name: "succeed" (status: 99); the MP4 is in works[0].resource.resource:

{
  "status": 99,
  "status_name": "succeed",
  "status_final": true,
  "works": [
    {
      "workId": 123456789,
      "status_name": "succeed",
      "resource": {
        "resource": "https://s21-kling.klingai.com/....mp4",
        "height": 720,
        "width": 1280,
        "duration": 5041
      }
    }
  ]
}

The MP4 at works[0].resource.resource is watermarked. To get the clean, non-watermarked master, take the workId from the works array and call GET /assets/download — it returns a cdnUrl to the file (a single workId plus a single fileTypes value yields a direct MP4 link, otherwise a .zip):

curl "https://api.useapi.net/v1/kling/assets/download?email=[e-mail]&workIds=123456789&fileTypes=MP4" \
  -H "Authorization: Bearer $USEAPI_TOKEN"

On the poll, a 404 means the task was deleted, failed at moderation, or your Kling account ran out of credits — check your balance at GET /accounts/email. Prefer not to poll? Pass a replyUrl in the create body to receive a webhook callback when the task completes.

Multi-shot sequences (v3)

Instead of one prompt and one duration, v3 Omni lets you storyboard a single video as 2–6 sequential shots, each with its own shot_N_prompt and matching shot_N_duration. The total of all durations must land between 3 and 15 seconds, shots must be sequential with no gaps (shot_1 + shot_2, never shot_1 + shot_3), and the multi-shot parameters cannot be combined with prompt or duration. Each shot prompt can carry the same @image_N / @element_N references as a single-shot job, so a recurring character holds across cuts:

curl -X POST "https://api.useapi.net/v1/kling/videos/omni" \
  -H "Authorization: Bearer $USEAPI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "omni_version": "v3",
    "mode": "pro",
    "aspect_ratio": "16:9",
    "image_1": "https://s21-kling.klingai.com/.../kitchen.jpg",
    "shot_1_prompt": "Cinematic medium shot, a chef standing behind a stainless steel stove @image_1, focused intently on the pan",
    "shot_1_duration": "3",
    "shot_2_prompt": "Continuous scene at the same stove @image_1. The chef flips the food high into the air, then turns sharply to the camera",
    "shot_2_duration": "3"
  }'

The response, polling, and clean download are identical to the single-shot flow above — the create call returns the same task.id, and the finished sequence comes back as one MP4 in works[0].

Video Elements

A Video Element is a reusable character or object reference you create once and drop into any later Omni job by ID — so the same face, costume, or prop stays consistent across separate generations without re-uploading and re-describing it each time. Create one with POST /elements. There are two types:

• IMAGE elements — built from a coverImage URL (optionally with extra angle views, or AI-generated multi-angle views via generateViews). Usable in both o1 and v3 Omni.
• VIDEO elements — built from a video URL (mp4, minimum 3 seconds, auto-trimmed to 8s), which captures motion and can carry a voice. VIDEO elements work only in v3 Omni.

Upload the cover image (or clip) with POST /assets first, then register the element:

curl -X POST "https://api.useapi.net/v1/kling/elements" \
  -H "Authorization: Bearer $USEAPI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "FashionLady",
    "coverImage": "https://s21-kling.klingai.com/.../character.jpg",
    "tag": "character"
  }'

It returns a generated element id (a 5-character random suffix is appended to your name):

{
  "elements": [
    {
      "id": "u_123456789012345",
      "name": "FashionLady ABC12",
      "description": "Elegant woman in red dress"
    }
  ],
  "count": 1
}

The tag is one of character, animal, prop, costume, scene, effect, or others (from GET /elements/tags) — leave it out to have Kling auto-detect it. List your saved elements anytime with GET /elements. Then reference the element by ID in any Omni prompt, alone or alongside images (remember the combined 7-slot limit):

curl -X POST "https://api.useapi.net/v1/kling/videos/omni" \
  -H "Authorization: Bearer $USEAPI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Character @element_1 walking through a sunlit garden, smiling",
    "omni_version": "v3",
    "mode": "std",
    "duration": "5",
    "element_1": "u_123456789012345"
  }'

A character-tagged element can also carry a voice — an official voice name/ID from GET /elements/voices, or a 5–60s mp4 to clone one from. For a VIDEO element, voice is extracted automatically from the source clip when it has 5–60 seconds of audio.

Batch script

Finding the right shot takes many attempts, and running them by hand is tedious. The Node.js script reads a list of prompts from prompts.json, submits each one to the Omni endpoint — single-shot (prompt + image/element refs) or multi-shot (shots) — then polls every task until it is final and downloads the finished MP4, preferring the clean, non-watermarked master via GET /assets/download and falling back to the watermarked works[0].resource.resource if needed. So you can queue a batch and come back to the winners.

You need Node.js v21 or newer. Put prompts.json and kling-omni.mjs in the same folder and run node ./kling-omni.mjs API_TOKEN EMAIL, where API_TOKEN is your useapi.net API token and EMAIL is your connected Kling account email. The script looks the account up by email automatically. Pass image URLs (already uploaded via POST /assets) as image_1…image_7, and saved element IDs as element_1…element_7.

Examples

The clips below are real Kling Omni generations produced through this Kling API, straight from our blog walkthroughs.

Multi-shot v3 — text-only 2-shot sequence via POST /videos/omni (omni_version: v3)

— from Kling v3: Multi-Shot Storytelling

Video Elements v3 — two VIDEO elements + a background image, 720p ~11s via POST /videos/omni (omni_version: v3, mode: std)

— from Kling v3: 4K Resolution and Video Elements

Frequently asked questions

What is Kling Omni? Omni is a single Kling video endpoint, POST /videos/omni, that picks a workflow from your inputs: blend up to 7 image references (@image_1…@image_7), reuse saved Video Elements (@element_1…), storyboard a v3 multi-shot sequence, run a start/end-frame transition, or guide generation from a reference video. See What Omni does above.

How do I pass multiple image references to Kling? Upload each image with POST /assets, pass the returned URLs as image_1, image_2, … (up to 7), and reference them in the prompt with @image_1, @image_2, etc. Images and saved elements share the same pool of 7 slots, so the combined total can't exceed 7. See Generate a multi-reference video in two API calls above.

What are Video Elements and how do I reuse a character? A Video Element is a reusable character/object reference created once with POST /elements — IMAGE elements from a coverImage, or VIDEO elements from an mp4 clip (v3 only). It returns an id like u_123…, which you then drop into any Omni prompt as @element_1. See Video Elements above.

How does Kling multi-shot work? On v3 Omni, set shot_1_prompt/shot_1_duration through shot_6_prompt/shot_6_duration (minimum 2 shots) instead of a single prompt/duration. Shots must be sequential with no gaps and the total duration must be 3–15 seconds. See Multi-shot sequences (v3) above.

Which Omni version supports multi-shot and Video Elements? Both are v3 only (the default). The o1 version supports IMAGE elements and single clips of 3–10s, while v3 adds VIDEO elements, multi-shot, 4k mode, and 3–15s durations. See What Omni does above.

Why is my Omni video watermarked? The MP4 at works[0].resource.resource returned by the poll is the watermarked preview. To get the clean, non-watermarked master, take the workId from the task's works array and call GET /assets/download — it returns a cdnUrl to the watermark-free file. This requires a paid Kling account. See Generate a multi-reference video in two API calls above.

My generation returns a 500 — what does that mean? Kling reuses the 500 response for content-moderation rejections as well as genuine server faults, and the generic message field rarely makes the difference clear. Read the error text instead. If a job clears creation but the poll later returns 404, the task was deleted, failed at moderation, or your account ran out of credits.

How is this different from the official Kling API? Kuaishou's official Kling API bills per generation at developer rates on a separate developer account. useapi.net instead automates your own consumer Kling account, so you generate at the website subscription price plus a flat $15/month — and the same one subscription covers 10+ other AI services.

Conclusion

Visit our Discord Server or Telegram Channel for any support questions and concerns.

The full runnable example is in the kling-api GitHub repo.