Kuaishou
Kling 3.0
kling-3.0/image-to-video
Kling Motion Control video generation: drive a character to reproduce motion and expressions from a character reference image plus a motion reference video, optionally keeping the original sound, up to 30 seconds following the video, output at 720p/1080p
Pricing
kling-3.0/image-to-video per second
Overview
Kling 3.0 is a video generation model from Kuaishou, and what HiAPI offers is its Motion Control route. Developers pass in a character reference image and a motion reference video, and the model makes the character in the image reproduce the motion and expressions from the video — the character's appearance comes from the image, the movement from the video, with the option to keep the reference video's original sound. It suits developers who need precise control over character performance rather than generating motion from text descriptions alone, for use cases such as short-drama performance replication, digital human voiceover, and marketing clips, billed by output seconds.
Highlights
- Motion driven directly by the reference video — motion and expressions come from the reference video while the character's appearance comes from the reference image, giving finer control than text prompts alone.
- Two orientation modes cover different needs — video-following mode suits complex motion, up to 30 seconds; image-following mode suits camera movement, up to 10 seconds.
- Optional retention of the reference video's original sound — keep_original_sound is enabled by default, so the output can reuse the original video's audio, saving post-production syncing.
- Per-second billing, tiered by resolution — costs are settled by output seconds, tiered across 720p and 1080p, making costs predictable.
Capabilities
Character motion replication: Drive the character in the character reference image with a motion reference video, and the model reproduces the motion and expressions from the video; developers get character performance footage directly without describing it frame by frame.
Prompt assists with scene and camera: Use prompts to add scene, style, and camera descriptions, up to 2500 characters; motion and expressions are still determined by the reference video, and the prompt only guides atmosphere and camera.
Original sound toggle: keep_original_sound is enabled by default, so the output reuses the reference video's audio; disable it when you need to re-dub, for easier downstream audio post-production.
Orientation mode switching: character_orientation can be set to video or image; the former makes the output follow the reference video and suits complex motion with a maximum of 30 seconds, while the latter follows the reference image and suits camera movement with a maximum of 10 seconds.
Resolution and billing basis: Output can be 720p or 1080p, billed by output seconds with higher resolutions costing more; developers can trade off final quality against budget.
Use cases
- Dance and performance motion replication — Input a character image and a dance reference video to produce a clip of that character reproducing the same motion, for short-video content production and character re-creation.
- Short-drama character performance and camera movement replication — Use a live-action performance video as motion reference so that in-drama character assets reproduce the performance and camera movement, producing performance clips ready for the editing pipeline.
- Digital human voiceover and lip sync — Input a character image and a voiceover reference video to produce a character voiceover clip with the original sound retained, for digital human broadcast-style content.
- Marketing and product showcase clips — Design character motion with a reference video and produce product showcase assets with character animation, for ad delivery and social media distribution.
- Re-interpretation of existing footage with original sound — Keep the reference video's original sound and replace the character's appearance to produce reusable derivative assets, cutting the work of dubbing and syncing.
Limitations and selection advice
This route requires both a character reference image and a motion reference video; it cannot generate video from text alone. Asset constraints are fairly strict: images must be jpeg/png/jpg, no larger than 10MB, both sides greater than 340px, aspect ratio between 2:5 and 5:2, with clear head, shoulders, and torso; videos must be mp4/mov, no larger than 100MB, 3 to 30 seconds, and a single continuous shot. Output duration is limited by the orientation mode — image-following maxes out at 10 seconds and video-following at 30 seconds. This route supports at most 1080p, so if you need higher resolution or pure text-to-video generation, choose another model or route.
Create a generation task
https://api.hiapi.ai/v1/tasks Headers
AuthorizationstringRequiredAccount API key. Required on every request. Example: Bearer YOUR_HIAPI_API_KEY. Get your API key
Content-TypestringOptionalThe 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-KeystringOptionalIdempotency key, up to 255 bytes. Retries with the same key from the same account create the task only once; replays return the original taskId.
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
modelstringRequiredCurrent fixed value: kling-3.0/image-to-video
routestringOptionalCurrent fixed value: default
inputobjectRequired
Business parameters for kling-3.0/image-to-video and route default — see the parameter table below.
soundbooleanOptionalDefault: falseGenerate synchronized audio (effects/ambience). Costs more when enabled.
promptstringOptionalOptional text prompt to guide the generated motion and style.
durationintegerOptionalDefault: 5min 3max 15Clip length in seconds (3-15). Cost scales with duration.
image_urlsarrayRequiredminItems 1maxItems 21-2 image URLs. 1 = first frame; 2 = [first, last] frame. JPEG/PNG/WEBP.
Array [ string ]
resolutionstringOptionalDefault: "1080p"Output resolution. Higher resolution costs more.
720p1080p4KcallbackobjectOptional
Terminal-state notification config. When omitted, no callback is delivered — poll the task yourself. See the callback note below.
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.
urlstringRequiredRequired 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.
finalstoragestringOptionalDefault: "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.
temppersistentRequest 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/image-to-video",
"input": {
"sound": false,
"duration": 5,
"image_urls": "…",
"resolution": "1080p"
}
}' 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/image-to-video",
input: {
"sound": false,
"duration": 5,
"image_urls": "…",
"resolution": "1080p"
}
}),
});
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/image-to-video",
"input": {
"sound": false,
"duration": 5,
"image_urls": "…",
"resolution": "1080p"
}
},
)
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
https://api.hiapi.ai/v1/tasks/:id Response fields
taskIdstringRequiredTask ID, always prefixed with tk-hiapi-.
modelstringRequiredResolved 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.
routestringOptionalPresent only when the task was submitted with an explicit route parameter; echoes the submitted value.
statusstringRequiredTask status.
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.
creatednumberRequiredTask creation time (Unix seconds).
completednumberRequiredUnix 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
urlstringRequiredArtifact URL, directly downloadable.
typestringRequiredCurrent possible values: video, image, audio, first_frame, last_frame, thumbnail; more may be added later.
expireAtnumberRequiredUnix seconds until which the artifact remains accessible; download or transfer before it expires.
errorobjectOptional
Present only when status == fail.
codestringRequiredBusiness error code.
messagestringRequiredError 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"
}
}
}