Kling V4

Use kling-v4 to create asynchronous videos through APIMaster. This guide covers the native workflow and its complete request fields. Create an API key in the console. The API base is https://apimaster.ai/v1.

Capabilities and model differences

Capability	kling-v4	kling-v4-flash
Text to video	Yes	Yes
Image to video	First, middle and last frames; up to 10 images	One first frame
Omni image references	First/middle/last frames and reference images	First frame and reference images
Feature video references and editing a base video	Yes	Yes
Custom and preset elements	Yes	Yes
Voice references and voice management	Yes	Unsupported
Output resolution	720p, 1080p; default 1080p	720p only
Output duration	3–30 integer seconds	3–20 integer seconds
Video reference duration	Each and combined input: 3–30 seconds	Each and combined input: 3–20 seconds
Output frame rate	24 fps	24 fps

The native workflow uses settings and, for image or Omni requests, contents. Existing flat convenience requests to /videos/generations retain their existing documented contract. Do not mix the two parameter formats or assume their defaults are identical.

Authentication and endpoints

Send Authorization: Bearer YOUR_APIMASTER_KEY and Content-Type: application/json. Use an Idempotency-Key header to recover a submission after a timeout without creating another paid task.

Method	Path below https://apimaster.ai/v1	Purpose
POST	/kling/kling-v4/text-to-video	Generate from text
POST	/kling/kling-v4/image-to-video	Generate from keyframe images
POST	/kling/kling-v4/omni-video	Combine references or edit a base video
GET	/videos/{task_id}	Query an owned video or resource task
GET	/videos/{task_id}/content	Download a completed video; requires authentication
POST	/kling/kling-v4/create-element	Create an image or video character element
GET	/kling/kling-v4/elements	List your element creation tasks
GET	/kling/kling-v4/elements/{resource_id}	Query your element
GET	/kling/kling-v4/elements/presets	List preset elements
DELETE	/kling/kling-v4/elements/{resource_id}	Delete your completed custom element
POST	/kling/kling-v4/create-voice	Create a custom voice (V4 only)
GET	/kling/kling-v4/voices	List your voice tasks
GET	/kling/kling-v4/voices/{resource_id}	Query your voice
GET	/kling/kling-v4/voices/presets	List preset voices
DELETE	/kling/kling-v4/voices/{resource_id}	Delete your custom voice

A resource ID returned by APIMaster is an owned task_… handle; use that handle when referencing or deleting the resource. Preset IDs carry a preset: prefix. Private resources from another account cannot be queried, listed, deleted or referenced. Resources remain bound to their creation route; unavailable routes return an error instead of silently substituting a different resource.

Generation request parameters

Field	Type	Required	Description
model	string	No on native route	If provided, must equal kling-v4 from the URL
prompt	string	Text-to-video	Positive and negative scene descriptions; use this only for text-to-video
contents	object[]	Image-to-video / Omni	Ordered input list; must contain exactly one prompt item
settings	object	No	Output controls; individual fields are described below
options	object	No	Callback, external reference and watermark controls
notifications	object	No	APIMaster's verified task webhook configuration; see webhooks
client_reference_id	string	No	Optional reference for APIMaster task notifications; up to 128 bytes

A prompt supports up to 26,000 English characters or 11,000 non-English characters. Mixed text must satisfy English / 26000 + non-English / 11000 <= 1. Include reference IDs as @id in your prompt and explain which appearance, motion, background or audio to preserve. Describe multi-scene sequences in chronological order.

contents[] fields

Field	Type	Required	Description
type	string	Yes	One of the content types below
text	string	For prompt	Prompt content
url	string	For image/video types	Publicly reachable media URL; image types also accept Base64
id	string	Conditional	Unique task-local reference ID for @id; required for elements and voices, and when V4 uses multiple middle frames or reference images
element_id	string	For element	Your APIMaster element resource handle or a returned preset: ID
voice_id	string	For voice	Your APIMaster voice handle, a bound element voice handle, or a returned preset: ID; V4 only

Content type	Meaning	Image-to-video	Omni
prompt	Instructions for the output	Required	Required
first_frame	Fix the initial frame	Both models	Both models
middle_frame	Intermediate keyframes in chronological order	V4 only	V4 only
last_frame	Fix the final frame	V4 only	V4 only
refer_image	Appearance, object, scene or style reference; does not lock a frame	Unsupported	Both models
feature_video	Reference motion, camera movement or pacing	Unsupported	Both models
base_video	The video to edit	Unsupported	Both models; at most one
element	Persistent character, object or scene element	Unsupported	Both models
voice	Voice identity reference	Unsupported	V4 only

Keep the first-frame image before all other images and the last-frame image after all other images. Order middle frames as they should occur. Referencing a media ID in text alone does not upload the media.

settings fields

Field	Type	Required	Values and defaults
resolution	string	No	720p or 1080p; default 1080p
duration	integer	No	3–30 seconds. An explicit value takes precedence over a duration in the prompt
aspect_ratio	string	No; text/Omni only	21:9, 16:9, 9:16, 1:1, 4:3, 3:4; Omni also accepts adaptive. Text default: 16:9; Omni default: adaptive. Image-to-video follows its image inputs
audio	string	No; Omni only	native (default) or original. native generates matching audio; original preserves audio from base_video, or from the first feature_video if no base video is supplied

original audio requires a base or feature video and cannot be combined with voice references. These native APIs do not offer a silent audio=false switch.

When duration is omitted, a duration explicitly identified in the prompt is used. If neither specifies a duration, an Omni request with base_video uses its duration rounded to the nearest whole second; otherwise the default is 10 seconds. The final billed output duration is taken from the completed task's usage, rather than guessed from the downloaded container.

For Omni adaptive aspect ratio: an explicit ratio in the prompt comes first. Otherwise the order is base video, keyframes (first frame preferred), then a single feature video. Multiple feature videos fall back to 16:9; with no applicable reference the default is 16:9. An explicit non-adaptive aspect_ratio overrides a ratio mentioned in the prompt.

options fields

Field	Type	Required	Description
callback_url	string	No	Native task-state callback URL. For verified APIMaster callbacks with public IDs and delivery records, use notifications instead
external_task_id	string	No	Client reference. Use the returned task ID for status queries and Idempotency-Key for safe retries
watermark_info	object	No	Optional parallel watermarked result configuration
watermark_info.enabled	boolean	No	false by default. Explicit false is preserved; true requests a watermarked result as well. Custom watermark artwork is unsupported

Media and reference limits

Input	Limits
Generation images	JPG/JPEG/PNG, at most 30 MB each, width and height at least 300 px, width:height between 2:5 and 5:2; at most 10 images
Input videos	MP4/MOV, at most 300 MB each, each dimension 700–4553 px, total pixel area at most 8,294,400; 24–60 fps; aspect ratio 2:5–5:2
V4 video duration	Each video and combined normalized video input: 3–30 seconds
Flash video duration	Each video and combined normalized video input: 3–20 seconds
Video count	Up to 5 feature/base videos and video character elements combined; at most 1 base video
Element count	Up to 7 elements, including at most 3 video character elements
Voice count	Up to 3 voices; V4 only
Total materials	At most 15 images, videos, elements and voices combined; prompt items are excluded

A video character element contributes its video duration and occupies a video-reference slot. Image elements have their own creation limits, described below. Media files must remain accessible while the task runs; signed URLs must not expire before ingestion.

Examples

Text-to-video

curl "https://apimaster.ai/v1/kling/kling-v4/text-to-video" \
  -H "Authorization: Bearer $APIMASTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -d '{"prompt":"A paper boat floats on a quiet pond, static camera, gentle water sounds.","settings":{"duration":3,"resolution":"720p","aspect_ratio":"16:9"},"options":{"watermark_info":{"enabled":false}}}'

Image-to-video

{
  "contents": [
    {"type":"prompt","text":"Start at @first. Slowly move the camera toward the subject."},
    {"type":"first_frame","url":"https://YOUR_PUBLIC_HOST/first.jpg","id":"first"}
  ],
  "settings": {"duration":5,"resolution":"720p"}
}

Send this body to POST https://apimaster.ai/v1/kling/kling-v4/image-to-video. V4 can append middle and last frames; Flash accepts only one first frame.

Omni references and editing

{
  "contents": [
    {"type":"prompt","text":"Edit @source: replace the main object with @object, preserve camera movement and background."},
    {"type":"base_video","url":"https://YOUR_PUBLIC_HOST/source.mp4","id":"source"},
    {"type":"refer_image","url":"https://YOUR_PUBLIC_HOST/object.png","id":"object"}
  ],
  "settings": {"duration":5,"resolution":"720p","aspect_ratio":"adaptive","audio":"original"}
}

Send this to POST https://apimaster.ai/v1/kling/kling-v4/omni-video. For motion reference without editing an existing shot, replace base_video with feature_video and describe the intended motion in the prompt. For an element reference, use {"type":"element","element_id":"task_YOUR_ELEMENT","id":"character"} and mention @character in the prompt.

Element management

Use POST https://apimaster.ai/v1/kling/kling-v4/create-element. Element creation is asynchronous. Query the returned task until it completes, then use the returned resource.element_id in an Omni request. Preset elements are available from the presets endpoint and do not require creation.

Field	Type	Required	Description
element_name	string	Yes	1–20 characters
element_description	string	Yes	1–100 characters
reference_type	string	Yes	image_refer or video_refer
element_image_list	object	For image_refer	Front image and 1–3 other images
element_image_list.frontal_image	string	For image element	Front-view public URL or Base64
element_image_list.refer_images	object[]	For image element	1–3 reference views that differ from the front
element_image_list.refer_images[].image_url	string	Yes in each view	Public image URL or Base64
element_video_list	object	For video_refer	Video character source; do not combine with image source fields
element_video_list.refer_videos	object[]	For video element	Exactly one video
element_video_list.refer_videos[].video_url	string	Yes in the video	Publicly reachable MP4/MOV
element_voice_id	string	No	Bind an existing owned/preset voice. Image voice binding requires a character or humanoid element
tag_list	object[]	No	Element classification tags
tag_list[].tag_id	string	Yes in each tag	o_101 hottest, o_102 character, o_103 animal, o_104 item, o_105 costume, o_106 scene, o_107 effect, o_108 other
callback_url	string	No	Native task callback
external_task_id	string	No	Client reference; use APIMaster task ID for polling

Element image files support JPG/JPEG/PNG, at most 10 MB, dimensions at least 300 px, and aspect ratio 1:2.5–2.5:1. Video character sources must be realistic humanoid subjects: 3–8 seconds, 1080p, 16:9 or 9:16, MP4/MOV, at most 200 MB. A source video containing speech can create and bind a voice automatically. A returned bound voice is referenced through its APIMaster handle ending in .voice.

{
  "element_name":"Blue mascot",
  "element_description":"A blue fictional mascot seen from multiple angles",
  "reference_type":"image_refer",
  "element_image_list":{
    "frontal_image":"https://YOUR_PUBLIC_HOST/front.png",
    "refer_images":[{"image_url":"https://YOUR_PUBLIC_HOST/side.png"}]
  },
  "tag_list":[{"tag_id":"o_104"}]
}

Use GET …/elements?pageNum=1&pageSize=30 for your element tasks; pageNum 1–1000, pageSize 1–500. Use GET …/elements/presets for the preset library. Delete a completed custom element using DELETE …/elements/task_YOUR_ELEMENT; preset elements cannot be deleted. Deletion does not delete historical videos or consumption records.

Voice management — V4 only

Flash does not support custom voice creation, voice library endpoints or voice reference inputs. For V4, use POST https://apimaster.ai/v1/kling/kling-v4/create-voice.

Field	Type	Required	Description
voice_name	string	Yes	1–20 characters
voice_url	string	Source	MP3/WAV audio or MP4/MOV video; clean speech from one speaker, 5–30 seconds
video_id	string	Alternative source	A qualifying owned legacy video generated with sound on V2.6, Avatar or Lip-Sync. An unrelated raw provider ID is not accepted; use voice_url when no eligible owned legacy video exists
callback_url	string	No	Native task callback
external_task_id	string	No	Client reference

Exactly one source is required. This integration accepts voice_url; qualifying legacy video_id references must be owned and available through the supported legacy workflow. A V4 video does not automatically qualify as a legacy video_id source.

{"voice_name":"Narrator","voice_url":"https://YOUR_PUBLIC_HOST/voice.wav"}

Poll the returned task. Use resource.voice_id in a V4 Omni content item such as {"type":"voice","voice_id":"task_YOUR_VOICE","id":"speaker"} and mention @speaker in the prompt. Use audio: "native"; audio: "original" cannot be combined with voice references.

List your voices at GET …/voices?pageNum=1&pageSize=30, list preset voices at GET …/voices/presets, query your voice at GET …/voices/{resource_id}, and remove it with DELETE …/voices/{resource_id}. Pagination uses pageNum 1–1000 and pageSize 1–1000. Deleting a custom voice does not delete historical generation logs. Preset voices cannot be deleted.

Task lifecycle, downloads and errors

Submission returns immediately after acceptance with an APIMaster task ID:

{"id":"task_EXAMPLE","task_id":"task_EXAMPLE","object":"video","model":"kling-v4","status":"queued"}

Poll GET https://apimaster.ai/v1/videos/task_EXAMPLE with the same account's API key. States are queued, in_progress, completed and failed. Completed videos return an authenticated url under /videos/task_EXAMPLE/content. Resource tasks instead return an element/voice object with an owned resource handle. Resource lists include pending and failed creation tasks as well as completed ones.

curl "https://apimaster.ai/v1/videos/task_EXAMPLE" -H "Authorization: Bearer $APIMASTER_API_KEY"
curl -L "https://apimaster.ai/v1/videos/task_EXAMPLE/content" \
  -H "Authorization: Bearer $APIMASTER_API_KEY" -o output.mp4

Poll every 3–5 seconds with backoff. Do not create a replacement task just because generation is still running. After a submission timeout, recover using the same Idempotency-Key; changing the body while reusing a key is rejected. Download and store completed media promptly: remote result links are temporary and generated results have a limited retention period.

Situation	Handling
Unsupported parameter, conflicting model or invalid field type	HTTP 400; fix the request before retrying
Invalid API key or unavailable model permissions	Check credentials and account model access
Missing/wrong-owner resource	Rejected; never substitute another user's resource
Missing public media or expired source URL	Correct accessibility and submit a new request when appropriate
Rate limit or concurrency limit	Back off; poll accepted tasks rather than resubmitting
Accepted task fails	Task becomes failed; the normal task refund path applies
Video completed before usage/receipt is ready	Keep polling; final billing waits for authoritative usage

Billing

Always check the live model card for your current price. Video generation is billed by duration and resolution. Image references, image elements and voices do not automatically count as input video; video character elements do.

without input video:
  billable_seconds = output_duration
with input video:
  billable_seconds = output_duration + max(input_duration, output_duration)

Input-video tasks use a separate per-second tariff. The input duration is the normalized combined duration of feature videos, base video and video character elements. A short input video can therefore be billed for twice the output duration; do not estimate the charge from output length alone.

The gateway reserves a bounded amount before submission and settles against completed task usage. An omitted duration can be resolved from the prompt by the model, so the reservation can exceed the eventual charge; the excess is returned after completion. Resource creation is a separate operation: element creation and custom voice creation must not be priced as video seconds. Custom voice creation has its own per-call charge; the video-generation discount does not establish a voice-creation discount.

Check the console consumption log for the actual charged amount and generated video preview. Account groups and discounts can affect your final price. A successful HTTP response or a playable video establishes functional delivery, not independent model fingerprint verification.

---

When a watermarked result was requested, use GET /v1/videos/{task_id}/content?watermark=true to download that version. The normal content endpoint returns the original version. Both require authentication.

Existing convenience endpoint

Use kling-v4 for text-to-video, image-to-video, reference generation, video editing and video extension. Output is 720p or 1080p, 3–30 seconds per generated segment, with a stereo audio track.

Base URL: https://apimaster.ai/v1. Provide a nonempty prompt in every mode. Prompt-free image generation is rejected on this route; describe the desired motion or camera movement. Authenticate every request with Authorization: Bearer YOUR_API_KEY. Media URLs must be publicly accessible without cookies or login.

Submit and retrieve

POST https://apimaster.ai/v1/videos/generations with Content-Type: application/json.

curl "https://apimaster.ai/v1/videos/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"kling-v4","prompt":"A paper boat drifts on a quiet pond, gentle ripples and water sounds.","duration":3,"resolution":"720p","aspect_ratio":"16:9"}'

{"id":"task_example","task_id":"task_example","object":"video","model":"kling-v4","status":"queued","created_at":1792756800}

A task ID confirms acceptance. Poll GET https://apimaster.ai/v1/videos/{task_id} every 10–20 seconds until status is completed or failed. A successful result contains an authenticated APIMaster video URL. Download promptly using the same API key:

curl "https://apimaster.ai/v1/videos/task_example" -H "Authorization: Bearer YOUR_API_KEY"
curl -L "https://apimaster.ai/v1/videos/task_example/content" \
  -H "Authorization: Bearer YOUR_API_KEY" -o kling-v4.mp4

Other states include queued and in_progress. On failure, read error.code and error.message; correct the request before submitting again. Successful videos can also be previewed and downloaded in console usage logs.

All request parameters

Field	Type	Required / default	Description
model	string	required	kling-v4
prompt	string	required, including image-to-video	Desired scene, action, camera and sound. Use @Image1, @Video1, @Audio1 to refer to each media array in order. In editing, the input video is @Video1.
duration	integer	5	Generated seconds, 3–30. For editing, omission follows input duration, rounded up and capped at 30. For extension, this is the new segment length.
resolution	string	720p	720p or 1080p. There is no mode parameter.
aspect_ratio	string	mode-dependent	16:9, 9:16, 1:1, 21:9; reference generation also accepts auto. Text defaults to 16:9; image/edit follow their input; reference defaults to auto. Omit for extension.
image_urls	string[]	optional	Image mode: first frame then optional last frame, maximum 2. Reference/edit: at most 10 reference images. Explicitly set omni_reference_task_type: "reference" for reference-image-only generation.
image_with_roles	object[]	optional	Each object has url and role. See roles below. Do not mix image_urls and explicit frame fields in image mode.
image_with_roles[].url	string	required per item	Public HTTP(S) image URL.
image_with_roles[].role	string	required per item	first_frame, last_frame, keyframe (alias middle_frame), or reference_image.
first_frame_image	string	optional	First-frame URL; alternative to the first image_urls item or a first_frame role.
last_frame_image	string	optional	Last-frame URL for image generation, or target last frame for extension.
video_urls	string[]	optional	Reference generation: up to 5 videos, up to 30 input seconds total. Edit/extend: exactly 1 video, with the corresponding explicit task type.
video_url	string	required for edit/extend unless video_urls supplied	Input video. Requires explicit edit or extend. Do not send both singular and plural fields. Edit inputs must be at least 3 seconds; inputs longer than 30 seconds use the first 30 seconds.
audio_urls	string[]	optional, reference only	Up to 3 reference audio clips, each 5–30 seconds.
omni_reference_task_type	string	auto	auto, reference, edit, extend. Auto selects text/image/reference from the supplied inputs.
audio_setting	string	mode-dependent	origin preserves source sound; auto generates new sound. Only edit or reference generation with video. Edit defaults to original sound; reference defaults to new sound. Not supported for extension.

Image roles: exactly 1 first frame, at most 1 last frame and 8 middle frames, at most 10 total. Reference generation supports at most 10 images, 5 videos, 3 audios, and 15 files combined. Use reference_image roles for reference generation. For editing, reference images use image_urls. Extension accepts only an optional target last frame in addition to its input video.

Compatibility aliases: seconds maps to duration, size maps to the resolution value (720p/1080p), and ratio maps to aspect_ratio. Conflicting aliases return HTTP 400. Prefer canonical fields above.

Examples for each mode

Image-to-video:

{"model":"kling-v4","prompt":"Slow camera movement, gentle motion.","image_urls":["https://example.com/start.png","https://example.com/end.png"],"duration":5}

Middle frames follow array order:

{"model":"kling-v4","prompt":"Animate smoothly through the supplied frames.","image_with_roles":[{"url":"https://example.com/start.png","role":"first_frame"},{"url":"https://example.com/middle.png","role":"keyframe"},{"url":"https://example.com/end.png","role":"last_frame"}],"duration":10}

Reference generation:

{"model":"kling-v4","prompt":"Animate @Image1 using the camera motion of @Video1 and the music of @Audio1.","image_with_roles":[{"url":"https://example.com/character.png","role":"reference_image"}],"video_urls":["https://example.com/camera.mp4"],"audio_urls":["https://example.com/music.mp3"],"omni_reference_task_type":"reference","aspect_ratio":"auto","duration":5}

Editing, following input duration and aspect ratio:

{"model":"kling-v4","prompt":"Change the scene to a snowy evening.","omni_reference_task_type":"edit","video_url":"https://example.com/input.mp4","image_urls":["https://example.com/style.png"],"audio_setting":"origin"}

Extension, returning the original video plus the new segment:

{"model":"kling-v4","prompt":"Continue the camera movement as evening falls.","omni_reference_task_type":"extend","video_url":"https://example.com/input.mp4","duration":5,"last_frame_image":"https://example.com/target.png"}

Example URLs are placeholders; replace them with real media.

Billing and refunds

Official base tariff (checked 2026-10-23)

The Kling developer pricing page, in its Balance display, publishes these preview rates. They are the model's base reference prices; use the live model card for your effective channel/account price. The official page marks direct API access as Coming Soon; APIMaster availability is shown on its own model card.

Variant	Base USD / billable second
720p, no video input	$0.157
1080p, no video input	$0.235
720p, video input	$0.094
1080p, video input	$0.141

Prices are in USD per billable second; 720p and 1080p have separate rates. Editing and reference generation with video use the video-input tier. Check the live Kling V4 model card for current prices and available routes. Channel and account coefficients affect the final charge; usage logs show the actual amount.

Mode	Billable seconds
Text, image, reference with only images/audio	Generated output seconds
Extension	New segment seconds, excluding the original video
Editing / reference with video	Output seconds + max(output seconds, input video seconds)

Sum input video durations before rounding up, capped at 30 seconds. For example, editing a 3.04-second video without specifying duration yields a 4-second output and 8 billable seconds at the video-input rate. A 5-second extension of a 20-second video is billed for 5 seconds, even though the returned file contains 25 seconds.

The server measures input video duration before submission for editing/reference billing. If measurement fails, the request is rejected before generation is charged. Generation failures refund the reserved generation charge. Invalid requests are not charged. Refreshing or polling a completed task does not charge for generation again.

Unsupported parameters and troubleshooting

V4 always includes stereo audio. Omit mode, negative_prompt, multi_shot, multi_prompt, element_list, video_list, camera_control, voice_list, and other undocumented fields. audio: false and watermark: true are unsupported. audio: true and watermark: false are accepted compatibility values. Use audio_setting only where allowed.

Error	Action
HTTP 400 / invalid parameter	Check JSON types, media limits, task type and parameter combinations. duration is a JSON integer.
Input video duration cannot be measured	Supply a public, downloadable MP4/MOV URL without authentication or anti-hotlink restrictions.
Input video supplied without edit/extend	Use video_urls for reference mode, or explicitly select edit/extend for video_url.
HTTP 503 / pricing unavailable	The selected variant is unavailable; check the model card.
Asynchronous generation failed	Inspect task error, verify source media and retry with corrected inputs. The generation reservation is refunded.

Get an API key after registering, then use https://apimaster.ai/v1 with model kling-v4.