Skip to content
Sign Up Free
Kling

Kling video API: text, image and motion control

Connect to Kling with a BetterToken API Key and choose fields, media and generation methods by Model ID and operation.

Generate videos from text or images, or control motion with a character reference image and motion video. kling-v3 sets its output level through provider_options.kling.mode. Omni, Turbo and Motion Control use their own resolution fields.

Prepare your BetterToken API Key. The Base URL is https://bettertoken.ai/v1, with Authorization: Bearer YOUR_API_KEY for authentication. Copy the Model ID exactly, including capitalization.

Every request.json below follows the same workflow: quote, confirm creation, poll and download. A quote does not start generation; creating a task submits a paid request. See current costs in the model plaza.

Models and operations

The table below lists available values by operation. See each subsection for field defaults, media counts and combination constraints. Media sizes use 1 MB = 1048576 bytes.

Model IDOperationDuration (seconds)Output levelAspect ratioAudioMedia roles
kling-3.0-turbotext_to_video5–10, step 5720p, 1080p16:9, 9:16, 1:1onNone
kling-v3-motion-controlreference_to_videofollows the 3–10-second reference video720p, 1080pomitoff, onreference_image, reference_video
kling-v3-omnitext_to_video3–15, step 1720p, 1080p, 4k16:9, 9:16, 1:1off, onNone
kling-v3image_to_video3–15, step 1std, pro, 4komitoff, onfirst_frame, last_frame
kling-v3text_to_video3–15, step 1std, pro, 4k16:9, 9:16, 1:1off, onNone

kling-v3 does not accept output.resolution; its image-to-video operation also rejects output.aspect_ratio. kling-v3-motion-control does not accept provider_options. Turbo generates only 5- or 10-second videos, with audio fixed to on.

Sample media

The image-to-video and image-reference examples use a blue ceramic mug on a white table. Keep the sample image to try them, or first replace it with public HTTPS media that you have the right to use and that meets this page’s limits.

Video generation reference: a blue ceramic mug on a white table

The motion control example uses a boy reference image and a motion video of the same boy. Its prompt matches these character assets. The video is about 5.04 seconds, 1280 × 720, at 24 fps.

Text-to-video

kling-3.0-turbo

Use this operation when you have only a text description.

Set model to this subsection’s Model ID and operation to text_to_video. Use only the generation fields listed below. Put media in the media array.

FieldTypeRequiredAllowed values or rangeDefault
audio.modestringNoonon
duration.modestringNofixedfixed
duration.secondsintegerNo5–10, step 5 s; only for fixed duration5
output.aspect_ratiostringNo16:9, 9:16, 1:116:9
output.formatstringNomp4mp4
output.resolutionstringNo720p, 1080p720p
promptstringYesstringNone
watermarkbooleanNofalsefalse

Media requirements

This operation does not accept media.

Combination constraints

  • duration.mode="fixed" requires duration.seconds. Include the number of seconds whenever you explicitly set fixed.

Request example

Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.

{
"model": "kling-3.0-turbo",
"operation": "text_to_video",
"prompt": "A blue ceramic mug on a white table. Slowly move the camera closer in soft daylight.",
"duration": {
"mode": "fixed",
"seconds": 5
},
"output": {
"resolution": "720p",
"aspect_ratio": "16:9"
}
}

Common 422 errors

422 error codeAction
enum / range / stepAdjust values and increments to match this subsection’s field table.
unsupported_fieldRemove fields absent from this operation’s field table.
requiresAdd seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints.

kling-v3-omni

Use this operation when you have only a text description.

Set model to this subsection’s Model ID and operation to text_to_video. Use only the generation fields listed below. Put media in the media array.

FieldTypeRequiredAllowed values or rangeDefault
audio.modestringNooff, onoff
duration.modestringNofixedfixed
duration.secondsintegerNo3–15, step 1 s; only for fixed duration3
output.aspect_ratiostringNo16:9, 9:16, 1:116:9
output.formatstringNomp4mp4
output.resolutionstringNo720p, 1080p, 4k720p
promptstringYesstringNone
watermarkbooleanNofalsefalse

Media requirements

This operation does not accept media.

Combination constraints

  • duration.mode="fixed" requires duration.seconds. Include the number of seconds whenever you explicitly set fixed.
  • output.resolution="4k" requires audio.mode="off".

Request example

Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.

{
"model": "kling-v3-omni",
"operation": "text_to_video",
"prompt": "A blue ceramic mug on a white table. Slowly move the camera closer in soft daylight.",
"duration": {
"mode": "fixed",
"seconds": 5
},
"output": {
"resolution": "720p",
"aspect_ratio": "16:9"
}
}

Common 422 errors

422 error codeAction
enum / range / stepAdjust values and increments to match this subsection’s field table.
unsupported_fieldRemove fields absent from this operation’s field table.
requiresAdd seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints.

kling-v3

Use this operation when you have only a text description.

Set model to this subsection’s Model ID and operation to text_to_video. Use only the generation fields listed below. Put media in the media array.

FieldTypeRequiredAllowed values or rangeDefault
audio.modestringNooff, onoff
duration.modestringNofixedfixed
duration.secondsintegerNo3–15, step 1 s; only for fixed duration5
output.aspect_ratiostringNo16:9, 9:16, 1:116:9
output.formatstringNomp4mp4
promptstringNostringNone
provider_options.kling.camera_axisstringNohorizontal, vertical, pan, tilt, roll, zoomNone
provider_options.kling.camera_typestringNosimple, down_back, forward_up, right_turn_forward, left_turn_forwardNone
provider_options.kling.camera_valueintegerNo-10–10, step 1, must not be 0None
provider_options.kling.modestringNostd, pro, 4kstd
provider_options.kling.negative_promptstringNostringNone
watermarkbooleanNofalse, truefalse

Media requirements

This operation does not accept media.

Combination constraints

  • duration.mode="fixed" requires duration.seconds. Include the number of seconds whenever you explicitly set fixed.

Request example

Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.

{
"model": "kling-v3",
"operation": "text_to_video",
"prompt": "A blue ceramic mug on a white table. Slowly move the camera closer in soft daylight.",
"duration": {
"mode": "fixed",
"seconds": 5
},
"output": {
"aspect_ratio": "16:9"
},
"provider_options": {
"kling": {
"mode": "std"
}
}
}

Common 422 errors

422 error codeAction
enum / range / stepAdjust values and increments to match this subsection’s field table.
unsupported_fieldRemove fields absent from this operation’s field table.
requiresAdd seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints.

Image-to-video

kling-v3

Use this operation to set the opening frame or both the first and last frames with images.

Set model to this subsection’s Model ID and operation to image_to_video. Use only the generation fields listed below. Put media in the media array.

FieldTypeRequiredAllowed values or rangeDefault
audio.modestringNooff, onoff
duration.modestringNofixedfixed
duration.secondsintegerNo3–15, step 1 s; only for fixed duration5
output.formatstringNomp4mp4
promptstringNostringNone
provider_options.kling.camera_axisstringNohorizontal, vertical, pan, tilt, roll, zoomNone
provider_options.kling.camera_typestringNosimple, down_back, forward_up, right_turn_forward, left_turn_forwardNone
provider_options.kling.camera_valueintegerNo-10–10, step 1, must not be 0None
provider_options.kling.modestringNostd, pro, 4kstd
provider_options.kling.negative_promptstringNostringNone
watermarkbooleanNofalse, truefalse

Media requirements

Media roleType and countFormatsPer-file limits
first_frameimage, optional, at most 1jpg, jpeg, pngsize at most 10 MB; width 300–100000 px; height 300–100000 px
last_frameimage, optional, at most 1jpg, jpeg, pngsize at most 10 MB; width 300–100000 px; height 300–100000 px

Whether media is required also depends on the combination constraints below.

Combination constraints

  • duration.mode="fixed" requires duration.seconds. Include the number of seconds whenever you explicitly set fixed.
  • Provide at least one of these roles: first_frame, last_frame.
  • Do not set provider_options.kling.camera_type when providing a last_frame.

Request example

Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.

{
"model": "kling-v3",
"operation": "image_to_video",
"prompt": "Slowly move the camera closer to the blue ceramic mug. Preserve its shape and the white table.",
"duration": {
"mode": "fixed",
"seconds": 5
},
"provider_options": {
"kling": {
"mode": "std"
}
},
"media": [
{
"id": "first",
"type": "image",
"role": "first_frame",
"source": "https://docs.bettertoken.ai/images/nano-banana-guide/sample-07.png"
}
]
}

Common 422 errors

422 error codeAction
enum / range / stepAdjust values and increments to match this subsection’s field table.
unsupported_fieldRemove fields absent from this operation’s field table.
requiresAdd seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints.
excludesRemove fields that conflict with automatic duration or the last frame.
count / media_roleAdjust roles and counts to match this subsection’s media table.
video_input_unsupportedCheck the public HTTPS URL, Content-Type and file format, then quote again.

Reference generation

kling-v3-motion-control

Use this operation to preserve subject or motion characteristics from reference media.

Set model to this subsection’s Model ID and operation to reference_to_video. Use only the generation fields listed below. Put media in the media array.

FieldTypeRequiredAllowed values or rangeDefault
audio.modestringNooff, onoff
duration.modestringNoautoauto
duration.secondsintegerNoomit; duration follows the 3–10-second reference videoNone
output.formatstringNomp4mp4
output.resolutionstringNo720p, 1080p720p
promptstringYesstringNone
watermarkbooleanNofalsefalse

Media requirements

Media roleType and countFormatsPer-file limits
reference_imageimage, 1 (required)jpg, jpeg, pngsize at most 10 MB; width 300–16384 px; height 300–16384 px
reference_videovideo, 1 (required)mp4, movsize at most 100 MB; duration 3–10 s; total for this role at most 10 s

Whether media is required also depends on the combination constraints below.

Combination constraints

  • Use automatic duration so output duration follows the reference video. Do not set duration.seconds.

You must provide exactly 1 reference_image and 1 reference_video. Do not set an aspect ratio or additional provider_options.

Request example

Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.

{
"model": "kling-v3-motion-control",
"operation": "reference_to_video",
"prompt": "Animate the boy in the reference image following the motion in the reference video. Preserve his appearance.",
"duration": {
"mode": "auto"
},
"output": {
"resolution": "720p"
},
"media": [
{
"id": "person",
"type": "image",
"role": "reference_image",
"source": "https://bettertoken.ai/video-api/shared/kling-hero-3.0-poster.jpg"
},
{
"id": "motion",
"type": "video",
"role": "reference_video",
"source": "https://bettertoken.ai/video-api/shared/kling-hero-3.0.mp4"
}
]
}

Common 422 errors

422 error codeAction
enum / range / stepAdjust values and increments to match this subsection’s field table.
unsupported_fieldRemove fields absent from this operation’s field table.
excludesRemove fields that conflict with automatic duration or the last frame.
count / media_roleAdjust roles and counts to match this subsection’s media table.
video_input_unsupportedCheck the public HTTPS URL, Content-Type and file format, then quote again.

Official resources

When calling BetterToken, use this page’s fields and the corresponding operation in the live model catalog.