Skip to main content
POST
cURL

Usage notes

  • Materials: provide at least one of image_urls (up to 10, @image_N), video_urls (up to 5 clips of 2-30 seconds, @video_N), kling_elements (up to 7, @name) and voices (up to 3, @name). All four types together are limited to 15; reference videos plus video elements are limited to 5 clips and 30 seconds combined.
  • Elements: each element is either 2-4 images (the first is the primary view) or exactly one 3-8 second single-shot character video, with an optional tag (character, animal, prop, costume, scene, effect, others; video subjects are always character) and description (up to 100 characters). Character elements can bind one voice in element_input_audio_urls. Clip windows (start_time / end_time) are not supported.
  • Names: element and voice names are 1-20 Chinese characters, letters, digits or underscores, unique across both lists (case-insensitive), and cannot use reserved names such as image_N, video_N, keyframe_N, object_N, audio_N, first_frame or last_frame.
  • Mentions: every @ mention in the prompt must match a material in the request, using longest match; a name ending with a letter, digit or underscore cannot be directly followed by another letter, digit or underscore. Unmatched mentions return a 400 error before a task is created.
  • Audio: native audio is always generated, so there is no generate_audio parameter — sending it is rejected. With video_urls, set keep_original_sound to true to keep the reference videos’ sound.
  • Not supported: keyframe_urls (use Kling 4.0 Image to Video), audio_urls (use voices), video_url (use video_urls), negative_prompt, multi_shot / multi_prompt, and 4K output.

Billing

Billed per second at a rate that depends on the resolution and on whether video input is present.
  • No video input (text, images, image elements or voices only): rate × output seconds.
  • With video input (video_urls or video elements): input video durations are merged and billed too, at a lower per-second video-input rate. If the total input is no longer than the output, you pay for output × 2; if it is longer, you pay for input + output. For example, a 10-second output with 5 seconds of input bills 20 seconds; with 15 seconds of input it bills 25 seconds.
Input videos are probed when the task is submitted; if a duration cannot be read, the request is rejected with a 400 error and nothing is charged. Current prices are shown on the model page.

Task flow

The create call returns data.task_id. Poll Query video task until status is completed (outputs in data.result) or failed, or pass callback_url to be notified when the task reaches a terminal state. Upstream checks such as reference video length or voice detection happen during generation; such failures are refunded.

Authorizations

Authorization
string
header
required

Use your APIPod API key as a Bearer token in the Authorization header.

Body

application/json
model
string
required

Public APIPod model ID.

Allowed value: "kling-4.0-r2v"
prompt
string
required

Required, up to 8,000 characters. Mention materials as @image_1..@image_N and @video_1..@video_N (1-based, in array order), and elements / voices by @name. Every @ mention must match a material in this request; mentions use longest-match, and a name ending with a letter, digit or underscore cannot be followed by another letter, digit or underscore.

Required string length: 1 - 8000
image_urls
string[]

Reference images, up to 10 publicly accessible URLs, mentioned as @image_1..@image_N in array order. Each side must be 300-65536 pixels; aspect ratio 0.40-2.5.

Maximum array length: 10
video_urls
string[]

Reference videos, up to 5 clips of 2-30 seconds each, mentioned as @video_1..@video_N. Reference videos plus video elements cannot exceed 5 clips or 30 seconds combined. Input video time is billed too, at the lower video-input rate: output + max(output, total input) seconds (10 s output + 5 s input bills 20 s; + 15 s input bills 25 s).

Maximum array length: 5
kling_elements
Elements · object[]

Subjects used only for this task, up to 7 (at most 3 video subjects), mentioned as @name. Each element is either 2-4 images (the first is the primary view) or exactly one 3-8 second single-shot character video. image_urls, video_urls, kling_elements and voices together cannot exceed 15 items.

Maximum array length: 7
voices
Voices · object[]

Standalone voice references used only for this task, up to 3, mentioned as @name. The task fails if no usable voice can be detected in the audio.

Maximum array length: 3
keep_original_sound
boolean
default:false

Keep the original audio of the reference videos. Only applies when video_urls is provided; defaults to false (audio is regenerated).

duration
integer
default:5

Output duration in seconds (3-30). Defaults to 5.

Required range: 3 <= x <= 30
resolution
enum<string>
default:720p

Output resolution. Defaults to 720p. The per-second rate depends on the resolution and on whether video input is present.

Available options:
720p,
1080p
aspect_ratio
enum<string>
default:auto

Output aspect ratio. Defaults to auto, which adapts to the reference materials.

Available options:
auto,
16:9,
9:16,
1:1,
21:9
callback_url
string
default:""

HTTPS URL that receives the task's terminal state.

Response

200 - application/json

Task accepted

Standard response for task submission

code
integer
required
data
Task Submit Data · object
required

Data content for task submission

message
string
required