Kling 3.0 Omni Reference-to-Video API

POST Base URL: https://api.hiapi.ai /v1/tasks

Copy Page

Image, video, and audio models are called through theUnified Async API POST /v1/tasks endpoint; only the input fields differ (see input parameters below).

Model summary

Model name	kling-3.0-omni/reference-to-video
Type	Video generation (reference-to-video)
Endpoint	POST /v1/tasks
Pricing	See HiAPI Pricing

Kling 3.0 Omni reference-to-video generates a 3–15 second clip at 720p to 4k from 1–7 reference images and an optional reference video, keeping the subject, style, and motion of the references, with 16:9 / 9:16 / 1:1 output, native audio, smart multi-shot planning, and @name subject references.

Production guidance

Production guidance

• For production, pass callback.url at the top level of the request body so HiAPI can notify your service when the task reaches a terminal state.
• GET /v1/tasks/:id is better for local debugging, low-volume jobs, or fallback reconciliation if a callback is missed.
• Use callback.when=final. Both success and fail are terminal states, so your service should deduplicate by taskId.

Best suited for

Subject and style references

Keep a subject, product, or art style consistent with reference images while the prompt describes the new scene.

image_urlsprompt

Motion and camera references

Add one reference video so the new clip follows its motion rhythm and camera work.

video_urls

Multiple subjects in one scene

Name each character in elements and direct them in the prompt as @name.

elements

Multi-shot clips with audio

Without a reference video you can enable audio and prefer_multi_shots to get multi-shot content with sound in one generation.

audioprefer_multi_shots

Request parameters

</> Generate example code

model string required

Fixed value kling-3.0-omni/reference-to-video.

example kling-3.0-omni/reference-to-video

input object required

Model-specific parameters. Put the Kling 3.0 Omni Reference-to-Video configuration here.

prompt string required

Describe the scene, subject motion, and camera work. To use a subject from elements, mention it in the prompt as @name. 1–3072 characters.

image_urls string[] required

1–7 reference images, up to 4 when a reference video is added. Reference images and elements subjects together may not exceed 7 (4 with a reference video). JPG/PNG, up to 50MB each, shortest side at least 300px.

video_urls string[] optional

Optional reference video, exactly 1 clip, used as a motion and camera reference. MP4/MOV, up to 200MB, 3–15.5 seconds, width and height 700–4553px, 24–60fps. When set, audio must be false, prefer_multi_shots cannot be enabled, and image_urls is limited to 4.

example ["https://static.hiapi.ai/admin-assets/2026/10/13/1791861859228-2b40d774dd4b2262-kling-omni-t2v-golden.mp4"]

duration integer optional

Video length in seconds; any integer from 3 to 15.

default 5

resolution enum optional

Resolution of the generated video.

default 720p enum: 720p1080p4k

audio boolean optional

Whether to generate native audio synchronized with the picture (ambience and sound effects). Must be false when a reference video is set.

default false example true

aspect_ratio enum optional

Aspect ratio of the generated video.

default 16:9 enum: 16:99:161:1

prefer_multi_shots boolean optional

Smart multi-shot: when enabled, the model plans multiple shots from the prompt automatically. Cannot be enabled when a reference video is set.

default false example true

elements object[] optional

Reusable subjects, up to 7. Each has a name, a short description, and 2–4 images of the same subject; reference it in the prompt as @name to keep the character or object consistent across the video. Together with reference images, no more than 7 (4 with a reference video).

example [{"name":"lin","description":"Little girl with a ponytail in a pale yellow dress","element_input_urls":["https://example.com/lin-front.jpg","https://example.com/lin-side.jpg"]}]

name string required

Unique subject name without spaces; referenced in the prompt as @name.

description string required

Short description of the subject.

element_input_urls string[] required

2–4 image URLs of the same subject, JPG/PNG.

callback object optional

Optional callback configuration. When set, HiAPI notifies your service when the task reaches a terminal state.

url string required

Required when callback is set; HTTPS URL that receives terminal task notifications.

example https://your-domain.com/hiapi/callback

when enum optional

Callback trigger timing. Use final.

default final enum: final

Limits when a reference video is set

• When video_urls is set, audio must be false, prefer_multi_shots cannot be enabled, image_urls is limited to 4, and reference images plus elements subjects may not exceed 4 in total. Requests that break these rules are rejected and no task is created.
• Only one reference video is accepted: MP4/MOV, up to 200MB, 3–15.5 seconds, width and height 700–4553px, 24–60fps.

Example requests

Reference image + reference video

One reference image keeps the paper boat's look and one reference video supplies the tracking camera move; audio is false because a reference video is set. 3 seconds, 720p, 16:9.

Request body⧉

{
  "model": "kling-3.0-omni/reference-to-video",
  "input": {
    "prompt": "The same white paper boat from the reference drifts along a sunlit forest stream at golden hour, leaves floating beside it, camera tracks low alongside it with the same smooth motion as the reference video. Cinematic, shallow depth of field.",
    "image_urls": [
      "https://static.hiapi.ai/admin-assets/2026/10/13/1791861888668-6554d6167af93003-kling-omni-boat-frame.jpg"
    ],
    "video_urls": [
      "https://static.hiapi.ai/admin-assets/2026/10/13/1791861859228-2b40d774dd4b2262-kling-omni-t2v-golden.mp4"
    ],
    "duration": 3,
    "resolution": "720p",
    "audio": false,
    "aspect_ratio": "16:9"
  }
}

Multiple reference images at 1080p with audio

With reference images only (no reference video), native audio can be enabled. Replace the example URL with a publicly accessible reference image.

Request body⧉

{
  "model": "kling-3.0-omni/reference-to-video",
  "input": {
    "prompt": "The white paper boat from the reference drifts down a city gutter at dusk; neon signs ripple on the water and raindrops splash beside the boat as the camera tracks low and steady. Cinematic, shallow depth of field, with the sound of rain and distant traffic.",
    "image_urls": [
      "https://static.hiapi.ai/admin-assets/2026/10/13/1791861888668-6554d6167af93003-kling-omni-boat-frame.jpg",
      "https://example.com/neon-street-reference.jpg"
    ],
    "duration": 6,
    "resolution": "1080p",
    "audio": true,
    "aspect_ratio": "9:16"
  }
}

Reference image + subject elements + smart multi-shot

The reference image sets the scene style, elements carries three images of a character referenced as @lin, and smart multi-shot is enabled for a 10-second clip (no reference video). Replace the example URLs with publicly accessible images.

Request body⧉

{
  "model": "kling-3.0-omni/reference-to-video",
  "input": {
    "prompt": "@lin crouches by the stream and sets the white paper boat on the water; it drifts away and she stands up and slowly follows it along the bank. Several shots: close-up releasing the boat, medium shot standing up, wide shot of the bank. Golden-hour light, cinematic.",
    "image_urls": [
      "https://static.hiapi.ai/admin-assets/2026/10/13/1791861888668-6554d6167af93003-kling-omni-boat-frame.jpg"
    ],
    "elements": [
      {
        "name": "lin",
        "description": "Little girl with a ponytail in a pale yellow dress",
        "element_input_urls": [
          "https://example.com/lin-front.jpg",
          "https://example.com/lin-side.jpg",
          "https://example.com/lin-back.jpg"
        ]
      }
    ],
    "duration": 10,
    "resolution": "1080p",
    "audio": false,
    "aspect_ratio": "16:9",
    "prefer_multi_shots": true
  }
}

Getting the result

1. The response returns a taskId immediately without waiting for generation to finish.
2. In production, prefer waiting for callback.url to receive the terminal notification. For local debugging, poll GET /v1/tasks/:id.
3. When status=success, download the generated video from output[].url.
4. When status=fail, fix the request based on the returned error instead of retrying the same invalid payload.

FAQ

What do reference images and the reference video each control?

Reference images supply the subject's look, composition, and style; the reference video supplies motion rhythm and camera work. The video is optional; at least one reference image is required.

Why can't I enable audio or smart multi-shot with a reference video?

In reference-video mode, audio must be false, prefer_multi_shots cannot be enabled, and image_urls is limited to 4. Pass reference images only when you need native audio or multi-shot output.

Is there a combined limit on reference images and elements subjects?

Yes. Without a reference video the total may not exceed 7; with a reference video it may not exceed 4.

What determines the output aspect ratio?

aspect_ratio: 16:9, 9:16, or 1:1, defaulting to 16:9.

How is it billed?

See the live prices on the HiAPI pricing page. View pricing

Next steps

• Get an API key
• View Kling 3.0 Omni Reference-to-Video pricing
• Compare AI video APIs
• Try it in Playground