Kling 3 Series

Use Kling 3.0, Turbo, Omni, and motion control through POST /v1/videos/generations. Creation returns a platform taskId; query the unified task endpoint or receive a completion callback.

This page's parameters, prices, and examples apply to these six model IDs. All default to 720p. Except for motion control, output duration defaults to 5 seconds and accepts integers from 3 to 15 seconds.

Billing

• Text, image, Turbo, and Omni generation charge for the duration specified in input.settings.duration, or 5 seconds when omitted. Small differences in the encoded video's actual duration do not change billable seconds.
• Only Omni feature_video and base_video select the reference-video rate. Image and video-character subjects do not select that rate by themselves. Reference-video duration is not added to billable seconds.
• Motion control charges for actual output duration, including fractional seconds. character_orientation=image reserves up to 10 seconds; video reserves up to 30 seconds. Unused credits are refunded after success.
• Final credits are round2(round2(rate × billable seconds) × account multiplier). Rates, charges, and refunds use at most two decimal places. The price and account multiplier are fixed when the task is created.

At account multiplier 1, silent 3.0 at 720p for the default 5 seconds costs 117.20 credits. Native-audio 3.0 at 1080p for 10 requested seconds costs 468.70 credits, even if the encoded result is 10.041 seconds. Motion control at 1080p with video orientation reserves 1406.10 credits; a 7.5-second result costs 351.53 credits, returning 1054.57 credits.

Confirmed failures refund the reservation. Successful generations with missing required usage remain under reconciliation and are not fully refunded as failures. Use credits_consumed on a completed task as the final charge.

Endpoint and authentication

POST https://api.aivideoapi.ai/v1/videos/generations
Authorization: Bearer YOUR_PLATFORM_API_KEY
Content-Type: application/json

Place callback_url at the top level, alongside model and input. Do not send input.options.callback_url or external_task_id; associate business records with the returned taskId. Replace example media URLs and subject IDs with accessible materials and valid IDs.

Text-to-video

3.0 text-to-video requires a non-empty input.prompt, up to 3072 characters.

curl -X POST 'https://api.aivideoapi.ai/v1/videos/generations' \
  -H 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "kling-3.0-text-to-video",
    "input": {
      "prompt": "Morning mist clears over a lake as the camera moves forward, with gentle birdsong.",
      "settings": { "resolution": "1080p", "duration": 10, "aspect_ratio": "16:9", "audio": "native", "multi_shot": false },
      "options": { "watermark_info": { "enabled": true } }
    },
    "callback_url": "https://app.example.com/webhooks/video"
  }'

Turbo text-to-video always generates audio and does not accept audio or multi_shot settings:

{
  "model": "kling-3.0-turbo-text-to-video",
  "input": {
    "prompt": "镜头 1, 2, Waves break on the beach; 镜头 2, 3, The camera tilts up as seabirds cross the sky;",
    "settings": { "resolution": "720p", "duration": 5, "aspect_ratio": "16:9" }
  }
}

Image-to-video

Use input.contents with exactly one first_frame and an optional prompt item. 3.0 also accepts one last_frame and up to 3 subjects; Turbo accepts only a first frame and a prompt. Do not send settings.aspect_ratio for image-to-video: the image determines the output ratio.

{
  "model": "kling-3.0-image-to-video",
  "input": {
    "contents": [
      { "type": "prompt", "text": "@hero walks into the frame, smiles at the camera and reaches the pose in the last frame." },
      { "type": "first_frame", "url": "https://media.example.com/start.jpg" },
      { "type": "last_frame", "url": "https://media.example.com/end.jpg" },
      { "type": "element", "element_id": "REPLACE_WITH_ELEMENT_ID", "id": "hero" }
    ],
    "settings": { "resolution": "1080p", "duration": 5, "audio": "off", "multi_shot": false }
  }
}

{
  "model": "kling-3.0-turbo-image-to-video",
  "input": {
    "contents": [
      { "type": "first_frame", "url": "https://media.example.com/start.jpg" },
      { "type": "prompt", "text": "The person turns toward the camera and says: Welcome to the beach. Waves sound in the background." }
    ],
    "settings": { "resolution": "1080p", "duration": 5 }
  }
}

3.0 image prompts allow up to 3072 characters; Turbo image prompts allow 2500. First and last frames use type and url. Subjects require both element_id and the local id used for @id references.

Omni references and editing

input.contents must be non-empty. It may contain a prompt alone or a combination of supported materials. At most one prompt is allowed, with up to 3072 characters.

Omni image and video IDs are optional and enable @id references in the prompt. Subject IDs are required, and all material IDs must be unique. At most one video is allowed across feature_video and base_video. audio=original is available only with a base video.

{
  "model": "kling-3.0-omni-video",
  "input": {
    "contents": [
      { "type": "prompt", "text": "Change the coat in @clip to the color in @reference. Preserve the motion, background and original audio." },
      { "type": "base_video", "url": "https://media.example.com/clip.mp4", "id": "clip" },
      { "type": "refer_image", "url": "https://media.example.com/reference.jpg", "id": "reference" }
    ],
    "settings": { "resolution": "1080p", "duration": 5, "audio": "original", "multi_shot": false }
  }
}

Subject limits depend on their actual types, which the service looks up. Clients do not declare subject types:

• With a first frame, at most 3 subjects are allowed.
• Without a reference video, images plus image subjects are limited to 7. When video-character subjects are present, that combined limit is 4, with at most 3 video-character subjects.
• With a reference video, use up to 4 images plus image subjects, or at most 1 video-character subject. A video-character subject cannot also be combined with images or image subjects.
• If an unknown subject type could make the combination invalid, the request returns a retryable error before charging. Retry later.

The generation endpoint references existing subjects; it does not provide subject or voice management.

Motion control

Supply one video for motion and an image or element for appearance, with at most one image and one subject. character_orientation is required: image follows the image's orientation and accepts 3–10 seconds of reference video; video follows the video's orientation and accepts 3–30 seconds. Subjects require video orientation.

{
  "model": "kling-3.0-motion-control",
  "input": {
    "contents": [
      { "type": "prompt", "text": "Keep the character's face and clothing consistent while performing the dance." },
      { "type": "image", "url": "https://media.example.com/character.jpg" },
      { "type": "video", "url": "https://media.example.com/dance.mp4" }
    ],
    "settings": { "character_orientation": "video", "resolution": "1080p", "audio": "original" }
  }
}

The prompt is optional and allows up to 2500 characters. audio is original by default, preserving reference audio, or off. Do not send duration, aspect_ratio, or multi_shot. Generation extracts usable continuous motion, so the result can be shorter than the reference video; billing uses actual output duration.

Settings and media requirements

All models accept boolean input.options.watermark_info.enabled, default false. true requests an additional watermarked result. Unlisted settings are rejected.

For explicit shots, use 镜头 n, m, words; with ASCII commas and semicolons, consecutive indexes starting at 1, and at most 6 shots. Each shot must last at least 1 second, all durations must add up to settings.duration, and each description is limited to 512 characters. For 3.0 and Omni, multi_shot=false disables shot generation.

• Images: JPG/JPEG/PNG over HTTP(S) or Base64, up to 50 MB each; both dimensions at least 300 px, aspect ratio 0.4–2.5.
• Omni videos: HTTP(S) URLs, MP4/MOV, 3–15.5 seconds, up to 200 MB; each dimension 700–4553 px, at most 8,294,400 pixels, aspect ratio 0.4–2, and 24–60 fps.
• Motion-control videos: HTTP(S) URLs, MP4/MOV, up to 100 MB; each dimension 340–3850 px, with duration limits determined by orientation.
• Media URLs must be directly downloadable and must not contain a username or password. Dimensions, duration, and content are also checked during generation. Prefer URLs for larger images.

Creation response, task queries, and callbacks

A successful creation response means the task was accepted:

{ "code": 200, "msg": "success", "data": { "taskId": "29bd04f8-3c15-4374-a364-4b484782d235" } }

Query GET /v1/tasks/{taskId} with an API key belonging to the same account:

curl 'https://api.aivideoapi.ai/v1/tasks/29bd04f8-3c15-4374-a364-4b484782d235' \
  -H 'Authorization: Bearer YOUR_PLATFORM_API_KEY'

Task statuses are pending, processing, completed, and failed. Queries return the task object directly. This example is silent 3.0 text-to-video at 720p for 5 requested seconds, at account multiplier 1:

{
  "id": "29bd04f8-3c15-4374-a364-4b484782d235",
  "status": "completed",
  "model": "kling-3.0-text-to-video",
  "credits_consumed": 117.20,
  "output": {
    "urls": ["https://media.example.com/result.mp4?signature=example"],
    "metadata": { "watermark_urls": ["https://media.example.com/result-watermarked.mp4?signature=example"] }
  },
  "usage": { "output_seconds": 5.041 }
}

usage.output_seconds preserves actual output duration. Video URLs are returned directly from the provider by default. Main videos appear in output.urls; watermarked versions, when requested and generated, appear in output.metadata.watermark_urls. Preserve signatures and query parameters, and download results to your storage promptly because URLs may expire.

Set top-level callback_url during creation to receive a JSON POST after completion or confirmed failure. Successful callbacks use the same result structure as task queries. Failure notifications contain status=failed and error. Intermediate processing states are not sent to user callbacks.

Process events idempotently using their event ID or task ID and terminal status, and return HTTP 2xx within 10 seconds. Failed delivery may be retried. These headers are not signatures; query the task with your platform API key when verification is needed. The platform receives generation callbacks and polls for missed updates; you only provide your application's callback URL. Continue polling the original task if a notification is missed.

These models do not support cancellation. Continue querying the original taskId after a query timeout or while processing; another creation request can produce a separate task and charge. Failed user-callback delivery does not regenerate a video or change a successful task's charge.