Kuaishou

Kling 3.0

kling-3.0-omni/reference-to-video

A unified multimodal video generation series supporting text-to-video, image-to-video, reference-to-video, and in-video editing, with native lip sync and multilingual audio

kling-3.0-omni/image-to-video kling-3.0-omni/reference-to-video kling-3.0-omni/text-to-video kling-3.0-omni/transformation kling-3.0/image-to-video kling-3.0/motion-control kling-3.0/text-to-video

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

Input

Subjects

Showcases

View all showcases

Output

video

Fill in the parameters and run — results show up here.

Pricing

kling-3.0-omni/reference-to-video per second

Specifications	720P	1080P	4K
Sound Off · Without Reference Videos	$0.100	$0.129	$0.479
Sound On · Without Reference Videos	$0.129	$0.1645	$0.479
Sound Off · With Reference Videos	$0.143	$0.193	$0.479
Sound On · With Reference Videos	$0.143	$0.193	$0.479

Positioning Overview

kling-3.0-omni/reference-to-video is the reference-image-to-video route in the Kling 3.0 Omni series. It uses 1 to 7 reference images (or up to 7 reusable subject elements) as visual anchors, combined with a text prompt, to generate videos of 3 to 15 seconds. It supports 720p, 1080p, and 4k resolutions and 16:9, 9:16, and 1:1 aspect ratios, and can enable native audio and intelligent multi-shot. It is suitable for developers who need to maintain character or object consistency across shots and produce marketing and social media videos at scale.

Core Highlights

Dual-track anchoring with multiple reference images and subject elements — pass 1 to 7 reference images, or define up to 7 subject elements each containing 2 to 4 images and reference them in the prompt with @name.
Optional reference video overlay — supports adding 1 reference video of 3 to 15.5 seconds to constrain motion and composition; in this case, the combined limit of reference images and subjects is tightened to 4.
Resolution and aspect ratios from portrait to 4K — output can be 720p, 1080p, or 4k, with aspect ratios covering 16:9, 9:16, and 1:1, suitable for both landscape and vertical short-video distribution.
Native audio and multi-shot can be combined — native audio (off by default) and intelligent multi-shot can be enabled at the same time to generate a multi-shot clip with sound in one pass; neither is available when a reference video is used.

Capability Details

Multi-subject consistent generation: define subject names, descriptions, and 2 to 4 images of the same subject via elements, then call them with @name in the prompt so the same character or object keeps a consistent appearance across multiple shots.

Reference video constraints: pass 1 MP4/MOV reference video (up to 200MB, 3 to 15.5 seconds) to guide motion and pacing, suitable for stylized or re-shot generation based on existing footage.

Resolution and aspect ratio control: choose 720p, 1080p, or 4k output according to the distribution channel, and set 16:9, 9:16, or 1:1 aspect ratios to reduce post-production cropping and transcoding.

Native audio and intelligent multi-shot: enable audio to generate sound simultaneously, and enable prefer_multi_shots to let the model automatically split multiple shots based on the prompt; both are available when no reference video is used.

Adjustable duration and prompt length: output duration can be set from 3 to 15 seconds according to narrative needs, and prompts can be up to 3072 characters, enough to describe subjects, actions, and shot scheduling.

Use Cases

Brand marketing teams: reference images + product selling-point prompts — lock the appearance with multi-angle product reference images and produce short clips with specified aspect ratios and resolutions, ready for feed and website campaigns.
Social media operations: character elements + vertical scripts — define fixed character elements and batch-generate 9:16 short videos while keeping the persona consistent, for daily content production.
Film and animation pre-production: reference video + storyboard prompts — use a reference video to constrain motion pacing and output multi-shot preview clips for directors to confirm shot design and edit points.
E-commerce content teams: product image sets to video — upload product reference images and set a 1:1 or 16:9 aspect ratio to generate showcase videos for detail pages and product main-image slots.

Limitations and Selection Advice

The combined number of reference images and subject elements must not exceed 7; after adding a reference video, this is tightened to 4, and native audio and intelligent multi-shot are unavailable in that case. The maximum duration per generation is 15 seconds; long narratives need to be generated in segments and then stitched together. Reference images must be JPG/PNG, no larger than 50MB each, with a shortest side of at least 300px; reference videos must be MP4/MOV and 3 to 15.5 seconds. If you only need single-image-driven or pure text generation, you can choose the image-to-video or text-to-video routes in the same series; if you have specific motion control requirements, you can evaluate motion-control.

What's new

View changelog →

New model New models: Kling 3.0 Omni (可灵 O3) via POST /v1/tasks Oct 12, 2026

Frequently asked questions

View all FAQs →

Does Kling 3.0 Image-to-Video require an input image?

Yes. kling-3.0/image-to-video is an image-to-video route. The image establishes the subject and opening composition; the prompt directs motion, camera, and environmental change.
Which durations and resolutions does Kling 3.0 Image-to-Video support?

The current HiAPI contract supports 3–15s at 720p or 1080p or 4K. Check the page controls and API docs for the current options.
How is Kling 3.0 Image-to-Video billed?

Billing follows output duration and the selected tier. The page follows the global display unit, while the successful task record contains the final charge.
How can I improve subject consistency?

Use a clear, unobstructed source with a complete composition. Describe the main action and camera first, then name the appearance, material, and background relationships that must remain stable. Validate a short clip first.

Create a generation task

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

Headers

AuthorizationstringRequired

Account API key. Required on every request. Example: Bearer YOUR_HIAPI_API_KEY. Get your API key

Content-TypestringOptional

The request body is always parsed as JSON; when sent, only application/json (optionally with charset) is accepted — any other value returns 415. Example: application/json.

Idempotency-KeystringOptional

Idempotency key, up to 255 bytes. Retries with the same key from the same account create the task only once; replays return the original taskId.

Idempotency key

On network timeouts or client retries, the same key creates the task only once — no double charges (scope: the API key's account). Use a business-unique identifier as the key (e.g. "order-42"); replays return the original taskId, and keys expire 24 hours after the first request. See the Unified Async API overview for the full scenario matrix.

Body

modelstringRequired

Current fixed value: kling-3.0-omni/reference-to-video

routestringOptional

Current fixed value: default

inputobjectRequired

Business parameters for kling-3.0-omni/reference-to-video and route default — see the parameter table below.

audiobooleanOptionalDefault: false

Whether to generate native audio synchronized with the visuals when generating the video; boolean, default false; unavailable when a reference video (video_urls) is provided.

promptstringRequiredminLength 1maxLength 3072

Describe the desired video content; to use subjects from elements, reference their names in the prompt in the form @name.

durationintegerOptionalDefault: 5min 3max 15

Output video duration in seconds, integer, range 3-15, default 5.

elementsarrayOptionalmaxItems 7

List of reusable subjects, up to 7; each element contains a name, a short description, and 2-4 images, and can be referenced in the prompt in the form @name.

Array [ object ]

Array items

namestringRequiredminLength 1

Unique name of the subject, used for referencing in the prompt in the form @name; the name must not contain spaces.

descriptionstringRequiredminLength 1

Short descriptive text for the subject, used to help the model recognize and reproduce the subject.

element_input_urlsarrayRequiredminItems 2maxItems 4

Array of reference images for the same subject; 2-4 images required; JPG/PNG supported.

Array [ string ]

image_urlsarrayRequiredminItems 1maxItems 7

Array of reference images; 1-7 images may be provided; if a reference video is added, at most 4, and reference images plus subjects (elements) must total no more than 7 (no more than 4 in total when a reference video is included). JPG/PNG supported, each no larger than 50MB, side length at least 300 px.

Array [ string ]

resolutionstringOptionalDefault: "720p"

Output video resolution, string, default 720p.

Options:720p1080p4k

video_urlsarrayOptionalminItems 1maxItems 1

Optional array of reference videos; MP4 or MOV supported, each no larger than 200MB, duration 3-15.5 seconds, dimensions 700-4553 px, frame rate 24-60 fps; native audio and intelligent multi-shot are not supported after a reference video is added.

Array [ string ]

aspect_ratiostringOptionalDefault: "16:9"

Aspect ratio of the output video, string, default 16:9.

Options:16:99:161:1

prefer_multi_shotsbooleanOptionalDefault: false

Whether to let the model automatically plan multiple shots based on the prompt; boolean, default false; unavailable after a reference video is added.

callbackobjectOptional

Terminal-state notification config. When omitted, no callback is delivered — poll the task yourself. See the callback note below.

Callbacks (Webhook)

Provide callback.url when creating a task and HiAPI POSTs to your service once the task reaches a terminal state — no polling needed. The callback payload mirrors the task detail structure; signature verification, delivery retries and idempotency are documented on the Unified Async API overview page.

urlstringRequired

Required when callback is present. A POST is sent to this URL once the task reaches a terminal state; must be a valid http(s) URL.

whenstringOptionalDefault: "final"

Only final is supported today — notified on both success and fail.

Options:final

storagestringOptionalDefault: "temp"

Artifact storage tier: temp (default, retained about 7 days) or persistent (long-term, billed by size). Insufficient balance or exceeding the storage cap silently downgrades to temp; the effective tier is shown in the task detail response.

Options:temppersistent

Request examples

# Submit an async task; returns a taskId immediately (no waiting for generation)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "kling-3.0-omni/reference-to-video",
  "input": {
    "audio": false,
    "prompt": "…",
    "duration": 5,
    "image_urls": "…",
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "prefer_multi_shots": false
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "kling-3.0-omni/reference-to-video",
    input: {
      "audio": false,
      "prompt": "…",
      "duration": 5,
      "image_urls": "…",
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "prefer_multi_shots": false
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "kling-3.0-omni/reference-to-video",
        "input": {
          "audio": False,
          "prompt": "…",
          "duration": 5,
          "image_urls": "…",
          "resolution": "720p",
          "aspect_ratio": "16:9",
          "prefer_multi_shots": False
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
  }
}

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

Get task detail

GET https://api.hiapi.ai/v1/tasks/:id

Response fields

taskIdstringRequired

Task ID, always prefixed with tk-hiapi-.

modelstringRequired

Resolved full model name. Tasks submitted with the route parameter return base@route (e.g. gpt-image-2/text-to-image@ext); otherwise identical to the name passed at creation.

routestringOptional

Present only when the task was submitted with an explicit route parameter; echoes the submitted value.

statusstringRequired

Task status.

Status values

queued Queued, not started yet. handling Being processed. archiving Processing finished, artifacts being prepared. success Terminal: completed, artifacts available (output returned). fail Terminal: failed (error returned). After submission, check status: success and fail are terminal, everything else is non-terminal. Poll every 1–3 seconds until terminal. On success, download artifacts from output[].url and transfer them before expireAt; pass storage: "persistent" at creation time when long-term retention is needed.

creatednumberRequired

Task creation time (Unix seconds).

completednumberRequired

Unix seconds when the task reached a terminal state; fixed to 0 while not terminal.

outputarrayOptional

Present only when status == success. Artifact list — always an array; a single task may return multiple types at once (e.g. video + first_frame).

Array [ object ]

Array items

urlstringRequired

Artifact URL, directly downloadable.

typestringRequired

Current possible values: video, image, audio, first_frame, last_frame, thumbnail; more may be added later.

expireAtnumberRequired

Unix seconds until which the artifact remains accessible; download or transfer before it expires.

errorobjectOptional

Present only when status == fail.

codestringRequired

Business error code.

messagestringRequired

Error description.

Response examples

Success

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

Processing (non-terminal)

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

Failed

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}