Runnable examples for Kuaishou Kling 4.0 through PoYo's async video API: 3–30 second videos at 720p or 1080p from text, first and last frames, multi-shot prompts, or image, video, and subject references, plus prompt-based editing of an existing video.
Answer: To use the Kling 4.0 API, send a server-side request to POST https://api.poyo.ai/api/generate/submit with model kling-4.0 and a PoYo API key, then poll GET https://api.poyo.ai/api/generate/status/{task_id}. The examples in this repository run with Python 3.9+, Node.js 22+, or cURL.
Last verified against the live PoYo schema and pricing on November 19, 2026.
- Model ID:
kling-4.0onPOST https://api.poyo.ai/api/generate/submit - Output: 720p (default) or 1080p, 3–30 seconds; ordinary generation defaults to 5 seconds
- Modes: text-to-video, image-to-video (first frame, optional last frame), reference-to-video, multi-shot, and video editing
- References: up to 10 images, 5 videos, and 7 subjects, at most 15 materials in total
- Aspect ratios: auto, 16:9, 9:16, 1:1, 21:9 (text and reference modes)
- Audio: native stereo audio is generated with every video; there is no on/off field
- Price: from 28.5 credits ($0.1425) per second at 720p and 42.5 credits ($0.2125) per second at 1080p
- Create a key in the PoYo dashboard.
- Copy
.env.exampleto.envand replace the placeholder. - Run one of the examples. Each submits the task and polls until
finishedorfailed.
POYO_API_KEY=YOUR_POYO_API_KEY_HERE
POYO_BASE_URL=https://api.poyo.aipython python/generate.py
python python/generate.py payloads/kling-4.0-multi-shot.jsonpython/generate.py uses only the Python standard library.
node node/index.mjs
node node/index.mjs payloads/kling-4.0-image-to-video.jsoncurl -X POST "https://api.poyo.ai/api/generate/submit" \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d @payloads/kling-4.0-text-to-video.jsonStatus polling and the other modes are in curl/generate.md.
Every file in payloads/ is a complete request body with public input media, so it runs as-is.
| File | Mode | Settings | Credits |
|---|---|---|---|
kling-4.0-text-to-video.json |
Text-to-video | 720p, 5 s, 16:9 | 142.5 ($0.7125) |
kling-4.0-image-to-video.json |
First frame | 720p, 5 s, no aspect_ratio |
142.5 ($0.7125) |
kling-4.0-reference-image.json |
@Image1 reference |
720p, 5 s, 16:9 | 142.5 ($0.7125) |
kling-4.0-multi-shot.json |
multi_prompt, 4 s + 6 s |
720p, 10 s total | 285 ($1.425) |
kling-4.0-video-edit.json |
Video editing, 10.05 s source | 720p, 10 s output | 357 ($1.785) |
The edit is billed as 10 output seconds plus max(ceil(10.05) = 11, 10) = 21 billed seconds at 17 credits.
The supplied media selects the mode automatically.
| Mode | Selected when |
|---|---|
| Video editing | video_url is provided |
| Reference-to-video | reference_image_urls, reference_video_urls, or kling_elements is non-empty |
| Image-to-video | image_urls is non-empty without reference materials |
| Text-to-video | No media is provided |
- Image mode: put the starting frame first in
image_urlsand an optional ending frame second, and omitaspect_ratio. - Reference mode:
image_urlsmay hold one optional starting frame. Refer to inputs as@Image1,@Video1, and@Element1in array order; the older@image_1and@video_1forms remain supported. - Editing: send
video_urlandprompt. Editing accepts reference images and image-based subjects, but notimage_urls, reference videos, video subjects,multi_prompt, oraspect_ratio. Omitdurationto keep the source duration. - Multi-shot: send
multi_promptinstead ofprompt. Each shot has a prompt of up to 512 characters and a duration of 1–30 seconds (default 5); shots must total 3–30 seconds, and a top-leveldurationmust equal that total.
| Field | Requirement | Meaning |
|---|---|---|
| prompt | one of prompt / multi_prompt |
Video instructions, up to 26,000 characters. Required for editing. |
| multi_prompt | one of prompt / multi_prompt |
Array of shots: { "prompt", "duration" }. Generation modes only. |
| duration | optional | Integer from 3 to 30 seconds. Default 5; multi-shot uses the shot total; editing keeps the source duration. |
| resolution | optional | 720p or 1080p. Default 720p. |
| aspect_ratio | optional | auto, 16:9, 9:16, 1:1, or 21:9, for text and reference modes. Without materials, defaults to 16:9. |
| image_urls | optional | Starting frame, plus an optional ending frame in image mode. |
| reference_image_urls | optional | Up to 10 images; with a starting frame, at most 10 images in total. |
| reference_video_urls | optional | Up to 5 videos, 3–30 seconds each. Not allowed in editing. |
| video_url | optional | Source video for editing, 3–30 seconds. |
| kling_elements | optional | Up to 7 subjects, each with 2–4 images (element_input_urls, frontal view first) or exactly one 3–30 second video (element_input_video_urls); at most 3 video subjects. |
Starting frames, reference images, reference videos, and subjects together cannot exceed 15 materials; the images inside one subject count as one. Reference videos and video subjects together can last at most 30 seconds.
1 credit = $0.005.
| Resolution | No video input | With video input |
|---|---|---|
| 720p | 28.5 credits ($0.1425) per second | 17 credits ($0.085) per billed second |
| 1080p | 42.5 credits ($0.2125) per second | 25.5 credits ($0.1275) per billed second |
With a source, reference, or subject video, billed seconds = output duration + max(ceil(total input video duration), output duration). Confirm current prices on the model page before a production rollout.
Without video input:
| Clip length | 720p | 1080p |
|---|---|---|
| 5 seconds | 142.5 credits ($0.7125) | 212.5 credits ($1.0625) |
| 10 seconds | 285 credits ($1.425) | 425 credits ($2.125) |
| 30 seconds | 855 credits ($4.275) | 1,275 credits ($6.375) |
- Direct the camera: name the move (push-in, orbit, tracking shot) and tie it to the action.
- Write the sound: put spoken lines in quotes and describe ambience and effects; audio is always generated.
- Anchor references: give every
@Image,@Video, and@Elementone job, for example "@Element1 walks through the square in @Image1". - Split long stories: use
multi_promptwith one beat per shot instead of one very long prompt. - Draft, then render: iterate at 720p and switch
resolutionto1080pfor the final cut.
submit -> persist data.task_id -> poll during development -> receive callback_url webhook in production
Treat finished and failed as terminal states. Accept a webhook only for task IDs your system created, process it idempotently, and reconcile the final state through the status endpoint. Copy output videos to your own storage after the task finishes.
Always read code in the response body as well as the HTTP status.
code |
Meaning and fix |
|---|---|
| 400 | A field is invalid, for example duration outside 3–30, both prompt and multi_prompt, or aspect_ratio in image or editing mode. Correct the request and resubmit. |
| 401 | Missing or invalid key: send Authorization: Bearer <POYO_API_KEY>. |
| 402 | Insufficient credits: top up in the dashboard. |
| 429 | Back off and retry. |
A task that fails after submission returns status: "failed" with error_message. See error codes.
How long can a Kling 4.0 video be? 3 to 30 seconds, in whole seconds, at 720p or 1080p.
How much does Kling 4.0 cost per second? 28.5 credits ($0.1425) at 720p and 42.5 credits ($0.2125) at 1080p without video input. With video input, the rates are 17 and 25.5 credits per billed second.
Can I turn the audio off? No. Kling 4.0 on PoYo returns native stereo audio with every video, and the request has no audio switch.
Can Kling 4.0 edit an existing video? Yes. Send video_url with a 3–30 second source video and a prompt that describes the change.
How many references can one request use? Up to 10 images (including an optional starting frame), 5 videos, and 7 subjects, with at most 15 materials in total.
How is Kling 4.0 different from Kling 3.0? Kling 4.0 adds 30-second clips, reference videos and subjects, and video editing. Kling 3.0 tops out at 15 seconds but offers native 4K. See Kling-3.0-API.
payloads/— complete request bodies for each modepython/generate.py— standard-library Python examplenode/index.mjs— dependency-free Node.js examplecurl/generate.md— copy-paste cURL requestsdocs/production-notes.md— limits and rollout checklist
- Kling-Image-4.0-API — Kling Image 4.0: native 8K images, image sets, and long webpage or ecommerce page designs from the Kling 4.0 family
- Kling-3.0-API — Kling 3.0 with native 4K
- Seedance-2.5-API — Seedance 2.5 multimodal-reference video
- awesome-poyo-api — every PoYo model repository in one list
- poyo-devtools — PoYo CLI, MCP bridge, and Agent Skill
MIT