Kling video API

Use Kling’s text-to-video or image-to-video operation. Choose the generation version in model_name; the routing group binds the public billing model.

Operations and limits

Method	Path	Purpose
POST	`/kling/v1/videos/text2video`	Text to video
POST	`/kling/v1/videos/image2video`	Image to video
GET	`/kling/v1/videos/text2video/{task_id}`	Poll text-to-video tasks
GET	`/kling/v1/videos/image2video/{task_id}`	Poll image-to-video tasks
GET	`/v1/videos/{task_id}`	Compatible polling, when available
GET	`/v1/videos/{task_id}/content`	Download

Use only operations available in Model Square. Multi-image, Turbo, Omni, extension, motion-control, voice, avatar and asset APIs are separate, unreviewed contracts here.

Public model / group	`model_name`	Duration	Mode and sound
`kling-video` / `Kling-2`	`kling-v2-5-turbo`	5 or 10 seconds	`std` or `pro`, silent
`kling-video` / `Kling-2`	`kling-v2-6`	5 or 10 seconds	`std` or `pro`; sound only with `pro`
`kling-video` / `Kling-2`	`kling-v3`	3 to 15 seconds	`std` or `pro`, sound on or off
`kling-video-v4` / `Kling-3`	`kling-video-v4`	3 to 30 seconds	`std` or `pro`; no separate sound selection

Use a complete allowed configuration from the selected offering. Do not send the display model ID in a model field.

Field	Required	Limits
`model_name`, `prompt`, `duration`	Yes	Prompt at most 2,500 characters; duration is an integer or integer string
`mode`	No	`std` or `pro`; default `std`
`sound`	No	Version-dependent `on`/`off`; legacy `false` means off. Omit for v4 or use off.
`aspect_ratio`	No	`16:9`, `9:16`, `1:1`; v4 also `21:9`
`image`	Image-to-video only, required	First frame
`image_tail`	Image-to-video only, optional	Last frame
`video_list[].video_url`	v4 only, optional	One HTTPS MP4/MOV reference, at most 100 MiB

Frame images accept HTTPS URLs or raw base64 JPEG/PNG, at most 10 MiB per embedded image. Base64 data-URL prefixes and multipart uploads are unsupported. Text-to-video rejects frame images. Resolution is undocumented by this contract.

Submit

curl --fail-with-body https://api.floodgate.dev/kling/v1/videos/text2video \
  -H "Authorization: Bearer $FLOODGATE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"model_name":"kling-v3","prompt":"A quiet forest beside a lake","mode":"std","duration":"5","sound":"off"}'

For image-to-video, use /kling/v1/videos/image2video and add "image":"https://example.com/first-frame.png". Replace the URL with your accessible image.

{"code":0,"message":"success","data":{"task_id":"task_example","task_status":"submitted"}}

Poll and download

Check code: 0 and keep data.task_id as TASK_ID. Poll the same action used for submission:

curl --fail-with-body "https://api.floodgate.dev/kling/v1/videos/text2video/$TASK_ID" \
  -H "Authorization: Bearer $FLOODGATE_API_KEY"

For image-to-video tasks, use the corresponding /image2video/$TASK_ID path. Pending states are submitted and processing; terminal states are succeed and failed.

{"code":0,"message":"success","data":{"task_id":"task_example","task_status":"succeed","task_result":{"videos":[{"id":"asset_example","url":"/v1/videos/task_example/content","duration":"5"}]}}}

{"code":0,"message":"success","data":{"task_id":"task_example","task_status":"failed","task_status_msg":"Video generation failed"}}

Read results from data.task_result.videos. After succeed, download with authentication:

curl --fail-with-body "https://api.floodgate.dev/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $FLOODGATE_API_KEY" --output video.mp4

Errors and billing

Inspect code even after HTTP 200 and task_status_msg on failure. Invalid version/mode/duration/sound combinations return 400. Unfinished downloads return 400, expired results 410. Keep the original task after a timeout or submission_uncertain; see shared video errors. V2 uses the selected completed-request price. V3 uses verified output seconds. V4 bills requested output seconds plus the greater of rounded-up reference seconds and requested output seconds when a reference is present:

billed seconds = output seconds + max(ceil(reference seconds), output seconds)

Without a reference, v4 bills requested output seconds alone. A three-second output with a 3.041-second reference bills seven seconds. Total billed seconds must not exceed 3,600. Codec padding does not increase the output charge. Follow-ups retain the original group and price; confirmed failures release reservations, while missing final usage can leave settlement pending.

Getting started

Coding tools

API reference

Operations and limits

Submit

Poll and download

Errors and billing

​Operations and limits

​Submit

​Poll and download

​Errors and billing

Operations and limits

Submit

Poll and download

Errors and billing