VidMage

VidMage is an AI video and image creation platform for creators. Turn your ideas and images into videos and fresh visuals.

Open the creator tools
Explore APIs
AI Video APIsAI Image APIsAI Audio APIsAI 3D APIsAI Face Swap APIsAI Effects APIs
Build with VidMage
QuickstartAPI keysVidMage MCPError reference
Your account
Developer consoleAbout VidMagePlans and creditsAPI billingContact support
© 2026 VidMage. All rights reserved.
Privacy PolicyTerms of ServiceReport Abuse
Skip to content
VidMage/Developers
Overview
APIs
All APIsAI Video APIsAI Image APIsAI Audio APIsAI 3D APIsAI Face Swap APIsAI Effects APIs
DocumentationVidMage MCPOpen console
Developers/Kling API

Kling API

Add Kling video generation to your app with text or image inputs. Build single shots or multi-shot sequences, define starting and ending frames, and control duration and audio in your API requests.

Get API keyView API docs
Abstract illustration for Kling API
PlaygroundAPIPricingGuideFAQs

Kling API Playground

Use your existing API key and subscription. Submitting a generation uses credits; uploading and preparing a request does not start a generation.

API access is available to subscribers only. Your subscription credits are shared across the website and the API.

View plans

Parameter

12 parameters

Text prompt describing the video to generate (max 2500 chars).

Optional input image URL. When provided, the task runs in image-to-video mode. In that mode, output ratio is inferred from the input image.(Optional)

Optional public URL for the final frame in image-to-video mode.(Optional)

Video duration in seconds.(Optional)

Default: 5

Output aspect ratio for modes that expose a ratio parameter. Ignored when imageUrl selects a mode whose ratio is inferred from the input image.(Optional)

Default: 16:9

Generate synchronized audio along with the video. Enabling sound adds a per-second credit surcharge.(Optional)

Default: true

Describe unwanted video content or artifacts.(Optional)

Default: Flickering, blur, distorted limbs, watermark, low resolution.

Prompt guidance strength.(Optional)

Default: 0.5min 0max 1

Generate a video composed of multiple shots.(Optional)

Default: false

Use custom or automatically planned shot structure.(Optional)

Default: customize

Additional prompts for complex multi-shot compositions.(Optional)

Default: maxItems 6

Element references to preserve across the generated shot.(Optional)

Default: maxItems 3

Request code

#!/usr/bin/env bash
set -euo pipefail
# Set this once per intended task; preserve it and the body for transport retries.
: "${VIDMAGE_IDEMPOTENCY_KEY:?Set a unique key for this task}"

SUBMIT_RESPONSE="$(curl --fail-with-body --silent --show-error -X POST "https://vidmage.ai/api/v1/kling-ai-video-generator/submit" \
  -H "Authorization: Bearer ${VIDMAGE_API_KEY}" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "prompt": "A cinematic tracking shot follows a cyclist through a quiet forest as morning fog drifts between the trees",
  "duration": "5",
  "aspectRatio": "16:9",
  "sound": true,
  "negativePrompt": "Flickering, blur, distorted limbs, watermark, low resolution.",
  "cfgScale": 0.5,
  "multiShot": false,
  "shotType": "customize"
}')"
TASK_ID="$(printf '%s' "$SUBMIT_RESPONSE" | jq -er '.["taskId"]')"

while true; do
  QUERY_RESPONSE="$(curl --fail-with-body --silent --show-error -X POST "https://vidmage.ai/api/v1/kling-ai-video-generator/query" \
    -H "Authorization: Bearer ${VIDMAGE_API_KEY}" \
    -H "Content-Type: application/json" \
    --data-raw "{\"taskId\":\"${TASK_ID}\"}")"
  STATUS="$(printf '%s' "$QUERY_RESPONSE" | jq -r '(.status // .data.status // "") | ascii_downcase')"
  case "$STATUS" in
    success|succeeded|completed)
      RESULT="$(printf '%s' "$QUERY_RESPONSE" | jq -r '(.result // .["videoUrl"] // .data["videoUrl"] // empty)')"
      if [ -z "$RESULT" ]; then
        printf '%s' "Result missing; preserve task $TASK_ID and query the same task again. Do not resubmit." >&2
        exit 2
      fi
      printf '%s\n' "$RESULT"
      break
      ;;
    needs_input)
      printf '%s' "Face selection required; preserve task $TASK_ID" >&2
      exit 2
      ;;
    failed|error)
      printf '%s' "$QUERY_RESPONSE" | jq -r '(.message // .error // .data.error // "Task failed")' >&2
      exit 1
      ;;
  esac
  sleep 5
done

Response data

Submit the task to see the API response here.
PlaygroundCapabilities

API documentation

Submit a request, track the task, and retrieve your result.

EndpointKling AI Video Generator ↓
Required inputs
prompt
Output
Video·videoUrl
EndpointKling 3.0 AI Video Generator ↓
Required inputs
prompt
Output
Video·videoUrl
Request setup & limitsHeaders, input options and media limits

Request headers

Authorization
Bearer YOUR_API_KEY

Keep your API key on your server.

Content-Type
application/json
Idempotency-Key
YOUR_UNIQUE_KEY

Use a new key per task. Reuse it only when retrying the same submission.

Input options & limits

Request controls follow each task's parameter rules; they do not guarantee output properties.

Kling AI Video Generator

Modes: text-to-video, image-to-video

Additional inputs; requirements vary by mode

prompt imageUrl lastFrameUrl

Media limits by mode
  • Image To VideoImage: jpg, png
Request controls
  • duration: 13 accepted values; see parameter rules
  • aspectRatio: "16:9", "9:16", "1:1"
  • sound: default true
  • negativePrompt: default "Flickering, blur, distorted limbs, watermark, low resolution."
  • cfgScale: default 0.5
  • multiShot: default false
  • shotType: "customize", "intelligence"
  • multiPrompt: default []

Kling 3.0 AI Video Generator

Modes: text-to-video, image-to-video

Additional inputs; requirements vary by mode

prompt imageUrl lastFrameUrl

Media limits by mode
  • Image To VideoImage: jpg, png
Request controls
  • duration: 13 accepted values; see parameter rules
  • aspectRatio: "16:9", "9:16", "1:1"
  • sound: default true
  • negativePrompt: default "Flickering, blur, plastic skin texture, distorted fingers, watermark, low contrast."
  • cfgScale: default 0.5
  • multiShot: default false
  • shotType: "customize", "intelligence"
  • multiPrompt: default []

Input retention and output-link lifetime depend on the API contract. Confirm API-specific retention terms before making promises to your users. Upload guide ↗

Kling AI Video Generator

POST /api/v1/kling-ai-video-generator/submit

Full API documentation ↗

prompt is required.

Required inputs

promptstring
Text prompt describing the video to generate (max 2500 chars).

Edit the sample inputs for your own task before submitting.

Kling AI Video Generator request
# Set VIDMAGE_IDEMPOTENCY_KEY to a unique value for this task; preserve it for transport retries.
curl -X POST "https://vidmage.ai/api/v1/kling-ai-video-generator/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A cinematic tracking shot follows a cyclist through a quiet forest as morning fog drifts between the trees","duration":"5","aspectRatio":"16:9","sound":true,"negativePrompt":"Flickering, blur, distorted limbs, watermark, low resolution.","cfgScale":0.5,"multiShot":false,"shotType":"customize"}'
# -> { "success": true, "taskId": "...", "creditsConsumed": ... }
Parameters and input rules12 fields
FieldTypeRequiredDefaultMeaning and limits
promptstringYesNot specifiedText prompt describing the video to generate (max 2500 chars). Minimum length: 1 · Maximum length: 2500
imageUrlstringNoNot specifiedOptional input image URL. When provided, the task runs in image-to-video mode. In that mode, output ratio is inferred from the input image. No additional field constraint listed.
lastFrameUrlstringNoNot specifiedOptional public URL for the final frame in image-to-video mode. No additional field constraint listed.
durationstringNo"5"Video duration in seconds. Values: "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15" · Default: "5"
aspectRatiostringNo"16:9"Output aspect ratio for modes that expose a ratio parameter. Ignored when imageUrl selects a mode whose ratio is inferred from the input image. Values: "16:9", "9:16", "1:1" · Default: "16:9"
soundbooleanNotrueGenerate synchronized audio along with the video. Enabling sound adds a per-second credit surcharge. Default: true
negativePromptstringNo"Flickering, blur, distorted limbs, watermark, low resolution."Describe unwanted video content or artifacts. Default: "Flickering, blur, distorted limbs, watermark, low resolution." · Minimum length: 0 · Maximum length: 2500
cfgScalenumberNo0.5Prompt guidance strength. Default: 0.5 · Minimum: 0 · Maximum: 1 · Multiple of: 0.1
multiShotbooleanNofalseGenerate a video composed of multiple shots. Default: false
shotTypestringNo"customize"Use custom or automatically planned shot structure. Values: "customize", "intelligence" · Default: "customize"
multiPromptstring[]No[]Additional prompts for complex multi-shot compositions. Default: [] · Maximum items: 6
elementListstring[]No[]Element references to preserve across the generated shot. Default: [] · Maximum items: 3
Mode-specific fields & media limits
Text To Video rules
ControlMode-specific rule
promptRequired; minimum 1 characters; maximum 2500 characters
durationValues: "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15"; mode default: "5"
aspectRatioValues: "16:9", "9:16", "1:1"; mode default: "16:9"
soundBoolean control; default true
negativePromptMaximum characters: 2500; Default: "Flickering, blur, distorted limbs, watermark, low resolution."
cfgScaleRange: 0 to 1; Default: 0.5
multiShotDefault: false
shotTypeValues: "customize", "intelligence"; Default: "customize"
multiPromptMaximum items: 6; Default: []
Image To Video rules
ControlMode-specific rule
promptRequired; minimum 1 characters; maximum 2500 characters
durationValues: "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15"; mode default: "5"
soundBoolean control; default true
imageUrlImage input
lastFrameUrlOptional final-frame image input
negativePromptMaximum characters: 2500
cfgScaleRange: 0 to 1; Default: 0.8
multiShotDefault: false
shotTypeValues: "customize", "intelligence"; Default: "customize"
multiPromptMaximum items: 6; Default: []
elementListMaximum items: 3; Default: []

Retrieve the result

Save taskId from the accepted submission and send it to this endpoint:

POST /api/v1/kling-ai-video-generator/query

Use the same Bearer API key. On completion, read the videoUrl result field.

Task states and recovery ↗
Kling AI Video Generator query
curl -X POST "https://vidmage.ai/api/v1/kling-ai-video-generator/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "TASK_ID_FROM_SUBMIT" }'
# -> { "success": true, "data": { "status": "...", "videoUrl": "https://..." } }

Kling 3.0 AI Video Generator

POST /api/v1/kling-3-0-ai-video-generator/submit

Full API documentation ↗

prompt is required.

Required inputs

promptstring
Text prompt describing the video to generate (max 2500 chars).

Edit the sample inputs for your own task before submitting.

Kling 3.0 AI Video Generator request
# Set VIDMAGE_IDEMPOTENCY_KEY to a unique value for this task; preserve it for transport retries.
curl -X POST "https://vidmage.ai/api/v1/kling-3-0-ai-video-generator/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Close-up of a watchmaker assembling a mechanical movement, precise hand motion and cinematic lighting","duration":"5","aspectRatio":"16:9","sound":true,"negativePrompt":"Flickering, blur, plastic skin texture, distorted fingers, watermark, low contrast.","cfgScale":0.5,"multiShot":false,"shotType":"customize"}'
# -> { "success": true, "taskId": "...", "creditsConsumed": ... }
Parameters and input rules12 fields
FieldTypeRequiredDefaultMeaning and limits
promptstringYesNot specifiedText prompt describing the video to generate (max 2500 chars). Minimum length: 1 · Maximum length: 2500
imageUrlstringNoNot specifiedOptional input image URL. When provided, the task runs in image-to-video mode. In that mode, output ratio is inferred from the input image. No additional field constraint listed.
lastFrameUrlstringNoNot specifiedOptional public URL for the final frame in image-to-video mode. No additional field constraint listed.
durationstringNo"5"Video duration in seconds. Values: "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15" · Default: "5"
aspectRatiostringNo"16:9"Output aspect ratio for modes that expose a ratio parameter. Ignored when imageUrl selects a mode whose ratio is inferred from the input image. Values: "16:9", "9:16", "1:1" · Default: "16:9"
soundbooleanNotrueGenerate synchronized audio along with the video. Enabling sound adds a per-second credit surcharge. Default: true
negativePromptstringNo"Flickering, blur, plastic skin texture, distorted fingers, watermark, low contrast."Describe unwanted video content or artifacts. Default: "Flickering, blur, plastic skin texture, distorted fingers, watermark, low contrast." · Minimum length: 0 · Maximum length: 2500
cfgScalenumberNo0.5Prompt guidance strength. Default: 0.5 · Minimum: 0 · Maximum: 1 · Multiple of: 0.1
multiShotbooleanNofalseGenerate a video composed of multiple shots. Default: false
shotTypestringNo"customize"Use custom or automatically planned shot structure. Values: "customize", "intelligence" · Default: "customize"
multiPromptstring[]No[]Additional prompts for complex multi-shot compositions. Default: [] · Maximum items: 6
elementListstring[]No[]Element references to preserve across the generated shot. Default: [] · Maximum items: 3
Mode-specific fields & media limits
Text To Video rules
ControlMode-specific rule
promptRequired; minimum 1 characters; maximum 2500 characters
durationValues: "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15"; mode default: "5"
aspectRatioValues: "16:9", "9:16", "1:1"; mode default: "16:9"
soundBoolean control; default true
negativePromptMaximum characters: 2500; Default: "Flickering, blur, plastic skin texture, distorted fingers, watermark, low contrast."
cfgScaleRange: 0 to 1; Default: 0.5
multiShotDefault: false
shotTypeValues: "customize", "intelligence"; Default: "customize"
multiPromptMaximum items: 6; Default: []
Image To Video rules
ControlMode-specific rule
promptRequired; minimum 1 characters; maximum 2500 characters
durationValues: "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15"; mode default: "5"
soundBoolean control; default true
imageUrlImage input
lastFrameUrlOptional final-frame image input
negativePromptMaximum characters: 2500
cfgScaleRange: 0 to 1; Default: 0.5
multiShotDefault: false
shotTypeValues: "customize", "intelligence"; Default: "customize"
multiPromptMaximum items: 6; Default: []
elementListMaximum items: 3; Default: []

Retrieve the result

Save taskId from the accepted submission and send it to this endpoint:

POST /api/v1/kling-3-0-ai-video-generator/query

Use the same Bearer API key. On completion, read the videoUrl result field.

Task states and recovery ↗
Kling 3.0 AI Video Generator query
curl -X POST "https://vidmage.ai/api/v1/kling-3-0-ai-video-generator/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "TASK_ID_FROM_SUBMIT" }'
# -> { "success": true, "data": { "status": "...", "videoUrl": "https://..." } }

Pricing

See what one image, video, or generation costs in credits. Your API and website activity share the same credit balance.

API credit rates and calculated example request costs
API / workflowExample requestPrice (credits)
Kling AI Video Generatorvideo API5-second video: 125 creditssound: true
How this is calculated
  • Base rate: 20 credits / second

Base charge = duration × the selected resolution rate.

Sound adds 5 credits per second before option multipliers.

Estimate your own request ↗
20 credits / secondSee calculation details
Kling 3.0 AI Video Generatorvideo API5-second video: 150 creditssound: true
How this is calculated
  • Base rate: 20 credits / second

Base charge = duration × the selected resolution rate.

Sound adds 10 credits per second before option multipliers.

Estimate your own request ↗
20 credits / secondSee calculation details
Billed in credits. Shared with the website.Active subscription required. Unit rates and examples follow current API credit rules.Billing details⌄

Examples show the charge for the inputs listed above. Resolution, duration, audio, output count and reference media can change the total. Minimum charges and rounding follow the selected API.

Use the Playground to estimate your request before submitting it. Estimates do not start a generation. Subscription and credit-pack prices are listed on the plans page.

Your task’s recorded usage is the source of truth for the final charge.

View plans ↗Billing guide ↗

About Kling API

VidMage's Kling API brings text, image, and shot-sequence controls into a video generation interface. Separate Kling and Kling 3.0 capabilities offer ending-frame and audio options, with duration and framing tied to the chosen mode. For short drama production, ordered scene prompts can turn an entrance, reaction, and reveal into footage for an episode edit. To explore this model's browser workflow, open VidMage's Kling AI Video Generator.

Kling API capabilities

Start from a scene or image
Describe a new scene, or use imageUrl for its starting frame and lastFrameUrl for an optional ending frame. Describe the action between them.
Plan multiple shots
Use multiShot, shotType, and an ordered multiPrompt array to configure a sequence of requested shots.
Set duration and audio
Choose a listed clip duration and sound setting, with optional negative prompts and prompt guidance controls.

What you can build

Short drama shot planning

An entrance, a reaction, a reveal: a short confrontation already contains several shots. Map those beats to ordered prompts and use Kling's shot controls to explore the sequence. The resulting footage becomes material for your episode edit.

Product reveal ads

Start with a product still and decide how the reveal should unfold. A slow camera orbit draws attention to shape; an opening box builds anticipation. An optional ending frame gives the shot a visual destination.

Music video concept boards

Directors can sketch the visual rhythm of a song through scene prompts: a close-up for the verse, a wider setting for the chorus. Place the generated shots beside the song timeline to discuss locations, movement, and pacing.

How to use Kling API

  1. Get an API key

    Create a key in the Developer Console and store it on your server. Use it in the Authorization: Bearer header.

  2. Prepare and submit your inputs

    Set up your inputs in the Playground, then copy the matching API request. Send it from your server with a unique Idempotency-Key.

  3. Track the task

    Save the returned taskId and query the same operation until it completes. Keep that identifier if your app stops waiting.

  4. Retrieve the result

    Read videoUrl from the completed task. Preview the result in your app and save a copy to your own storage for later use.

Input tips
Keep settings with their capability
Kling and Kling 3.0 are separate capabilities. Keep the selected capability with your saved shot settings instead of treating the two names as interchangeable aliases.
Check framing by input mode
Text mode accepts aspectRatio, while image mode does not expose a separate ratio control. Use the starting and ending images to plan an image-led shot.

Input requirementsUpload local files

Task fields and results

Keep the task identifier with its original request and Idempotency-Key. Query the same capability until it completes, then read the documented result field.

Task identifier
taskId
Query route
POST /api/v1/kling-ai-video-generator/query
Completed result
videoUrl
Task states and response structure ↗
Errors, retries and limits

Retry transport failures with the same idempotency key only when the original submission may not have reached the server. For a confirmed task, keep querying the original task instead of submitting a duplicate.

Read error recovery guidance ↗

FAQs

Are failed or timed-out requests charged?

A client timeout is not a confirmed task failure. Confirmed failures are automatically refunded only when the refund outcome is certain. Unknown charges or refunds remain pending reconciliation.

Failure and refund handling ↗
How long should my app wait for a result?

The checked contract does not establish a fixed completion time. Choose a local wait budget for your app; it is not an API completion deadline.

Polling and wait budgets ↗
What are the rate and concurrency limits?

Request-rate limits control how often you can call the API; concurrency limits control simultaneous work. The documentation ties both to the stable API key but does not publish numeric limits for this operation. Confirm account limits before planning parallel jobs.

Rate-limit recovery ↗
Can I receive results through a webhook?

The checked request contract documents status queries and does not list a webhook or callback field for these routes. Check the current authenticated OpenAPI contract before making a callback part of your integration.

Query task results ↗Check the current contract ↗

Explore more APIs on VidMage

  • Seedance API↗
  • Runway API↗
  • Seedance 2.5 API↗
  • SkyReels API↗
  • Grok Video API↗
  • MiniMax H3 API↗
  • Vidu API↗
  • HappyHorse API↗