Kling 4.0 API: Text, Keyframe & Reference Video

Overview

Kling 4.0 creates videos from text, ordered keyframes, or reference materials. Use named subjects and voices to describe which materials should appear in the video.

Capability	Value
Model ID	`kling-4-0`
Modes	`text-to-video`, `image-to-video`, `reference-to-video`
Prompt	Required in all modes; up to 8000 characters
Duration	Integer `3-30` seconds; default `5`
Resolution	`720p`, `1080p`; default `720p`
Keyframes	First frame, optional last frame, and up to 8 middle frames
References	Images, videos, named subjects, and voices
Output	Video URLs in the JSON string `data.resultJson`

Endpoint and authentication

Base URL: https://api.apixo.ai/api/v1.

Method	Endpoint	Purpose
`POST`	`/generateTask/kling-4-0`	Create a generation task
`GET`	`/statusTask/kling-4-0?taskId={taskId}`	Query status and retrieve results

Use Authorization: Bearer YOUR_API_KEY on both endpoints. Send JSON requests with Content-Type: application/json.

Copy-paste async quickstart

curl -X POST "https://api.apixo.ai/api/v1/generateTask/kling-4-0" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "async",
    "input": {
      "mode": "text-to-video",
      "prompt": "A cinematic city skyline at sunset, with a gentle camera move.",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

A successful submission returns a task ID. Save it for subsequent status requests.

{
  "code": 200,
  "message": "success",
  "data": { "taskId": "task_12345678" }
}

Parameters

string

default:"async"

Result delivery mode: async for polling or callback for webhook delivery.

string

Required when request_type=callback. Use a public HTTPS endpoint that can receive the final task payload. See Webhooks.

object

required

Kling 4.0 generation parameters.

Show properties

string

required

text-to-video, image-to-video, or reference-to-video. Select a mode explicitly.

string

required

Non-empty video description, up to 8000 characters. Material mentions such as @image_1 or @Hero must refer to materials declared in this request.

integer

default:"5"

Output duration in seconds. Supports integers from 3 through 30.

string

default:"720p"

Output resolution: 720p or 1080p.

string

auto, 16:9, 9:16, 1:1, or 21:9. Defaults to 16:9 for text mode and auto for reference mode. Image mode follows the first frame’s ratio and ignores this field.

string[]

Image mode requires 1-2 images: first frame, then optional last frame. Reference mode supports up to 10 reference images. Each image must have sides of 300-65536 pixels and a width/height ratio of 0.40-2.5.

string[]

Image mode only: up to 8 middle frames in chronological order. The total number of first, middle, and last frames must not exceed min(10, duration + 1). Each image follows the same dimensions and ratio limits as image_urls.

string[]

Reference mode only: up to 5 reference videos, each 2-30 seconds. Together with videos in elements, there can be at most 5 input videos and 30 seconds of total input video duration.

boolean

default:"false"

Preserve the original reference video audio. Applies only when video_urls is provided; it does not toggle native audio generation. Native audio is generated when reference videos are absent.

object[]

Reference mode only: up to 7 named subjects, including at most 3 video subjects. Each subject requires a unique name and either 2-4 image_urls or one video_url. See Subject and voice parameters below.

object[]

Reference mode only: up to 3 named voices. Each object requires name and audio_url. Names must be unique across subjects and voices, ignoring case. See Subject and voice parameters below.

All media URLs must be publicly accessible HTTP(S) URLs and remain accessible while the task runs.

Choose a mode and provide materials

Text-to-video

Provide mode=text-to-video and a prompt. Reference materials are not used in this mode.

Image-to-video with keyframes

The first image_urls entry is the first frame; a second entry is the last frame. Add chronological middle frames through keyframe_urls.

{
  "request_type": "async",
  "input": {
    "mode": "image-to-video",
    "prompt": "The camera leaves @first_frame, passes through @keyframe_1, and arrives at @last_frame.",
    "duration": 8,
    "resolution": "1080p",
    "image_urls": ["https://example.com/first.jpg", "https://example.com/last.jpg"],
    "keyframe_urls": ["https://example.com/middle.jpg"]
  }
}

Reference-to-video

Provide at least one image, video, named subject, or voice. The four material arrays together cannot exceed 15 entries; one subject counts as one entry. This request uses only a video subject. It uses the with input video price even though video_urls is absent.

{
  "request_type": "async",
  "input": {
    "mode": "reference-to-video",
    "prompt": "@Hero walks through a sunlit park and smiles at the camera.",
    "duration": 5,
    "resolution": "720p",
    "elements": [
      {"name": "Hero", "video_url": "https://example.com/hero.mp4", "tag": "character"}
    ]
  }
}

Subject and voice parameters

Subject field	Rules
`name`	Required; 1-20 Chinese characters, letters, digits, or underscores
`image_urls`	2-4 subject views; the first is primary. Mutually exclusive with `video_url`. Each image follows the `image_urls` media limits
`video_url`	One continuous character shot lasting 3-8 seconds; shortest side at least 700 pixels. Mutually exclusive with `image_urls`
`tag`	Optional: `character`, `animal`, `prop`, `costume`, `scene`, `effect`, `others`. Video subjects only support `character`
`description`	Optional subject description, at most 100 characters
`voice_url`	Optional voice bound to a character subject; does not count toward the three standalone voices

Each standalone voice has a required name and a publicly accessible audio_url. Voice names follow the same 1-20 character rules as subject names. Subject and voice names must be unique across the request, ignoring case. They cannot use reserved names such as image_N, video_N, keyframe_N, object_N, audio_N, first_frame, or last_frame. If a character video has speech and no separate voice is bound, its speech may be used automatically.

Mention materials in the prompt

Material	Mention
Reference images	`@image_1`, `@image_2`, and so on
Reference videos	`@video_1`, `@video_2`, and so on
Named subject or voice	`@name`, using the declared name exactly
Keyframes	`@first_frame`, `@keyframe_1`, and optional `@last_frame`

Every mention must match a declared material. If an ASCII name is followed by another ASCII letter, digit, or underscore, they are treated as part of the name: use a space or punctuation to end the mention. When declared names share a prefix, the longest matching name is used.

Poll for result or receive a webhook

curl "https://api.apixo.ai/api/v1/statusTask/kling-4-0?taskId=task_12345678" \
  -H "Authorization: Bearer YOUR_API_KEY"

Continue polling until data.state is success or failed. A successful video is returned as a JSON string in data.resultJson:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "success",
    "resultJson": "{\"resultUrls\":[\"https://file.apixo.ai/video.mp4\"]}",
    "createTime": 1792713600000,
    "completeTime": 1792713780000,
    "costTime": 180000
  }
}

Parse data.resultJson with JSON.parse() and read resultUrls. Failed tasks return failCode and failMsg; HTTP 200 on a status query does not by itself indicate successful generation. Task timestamps use Unix milliseconds, and costTime is elapsed milliseconds. For webhook delivery, set request_type=callback and provide callback_url when creating the task. The final payload follows the same task status structure. See Webhooks.

Billing

Prices are USD per billable second, with the same rates across modes for the same resolution and input video condition.

Resolution	Without input video	With input video
`720p`	`$0.157`	`$0.094`
`1080p`	`$0.235`	`$0.141`

Let D be output seconds and V the combined measured duration of all reference videos and video subjects.

Without input video: billable seconds = D.
With input video: billable seconds = D + max(D, V).
A video supplied only through elements[].video_url uses the with-video rate and contributes to V.
Images and voice references do not add billable seconds.

For example, 720p with 10 output seconds and 5 input video seconds costs 20 × $0.094 = $1.88. Reference-video quotes are estimates; final charges use measured input video durations, including fractional seconds. Do not round the reference duration to whole seconds when estimating charges. See Pricing and current API prices.

Latency and polling

Generation time varies by prompt, media inputs, output duration, resolution, and current workload. Longer clips can take several minutes.

Workload	Typical generation time	Recommended first poll	Poll interval
Text, image, or reference generation	Varies with the request	60s after task creation	10s-15s

Use webhook delivery for applications that do not need frequent status updates. Back off when requests are rate limited.

Errors and troubleshooting

Supply a non-empty prompt and a supported mode in every request.
In image mode, provide 1-2 image_urls and keep the total frame count within the duration-dependent limit.
In reference mode, declare at least one material, respect the combined video and material limits, and use only declared prompt mentions.
If an input URL cannot be accessed, use a direct, publicly accessible media URL.
On failure, check failCode and failMsg before submitting another task. See Error Codes.

​Overview

​Endpoint and authentication

​Copy-paste async quickstart

​Parameters

​Choose a mode and provide materials

​Text-to-video

​Image-to-video with keyframes

​Reference-to-video

​Subject and voice parameters

​Mention materials in the prompt

​Poll for result or receive a webhook

​Billing

​Latency and polling

​Errors and troubleshooting

​Related links

Overview

Endpoint and authentication

Copy-paste async quickstart

Parameters

Choose a mode and provide materials

Text-to-video

Image-to-video with keyframes

Reference-to-video

Subject and voice parameters

Mention materials in the prompt

Poll for result or receive a webhook

Billing

Latency and polling

Errors and troubleshooting

Related links