Kling 4.0

Kling 4.0 supports text-to-video, multiple keyframes, mixed references, and video editing at 720p or 1080p, with 3–30 second output. Create an asynchronous task through the unified API, then poll its ID or receive a completion callback.

Pricing and reservations

Output billing duration O is the requested input.settings.duration when explicitly supplied, or the actual output duration when omitted. I is always the actual combined input-video duration, including video subjects:

• Without input video, billable seconds are O.
• With input video, billable seconds are O + max(I, O): 2 × O when I ≤ O, or I + O when I > O.
• Final credits are round2(round2(rate × billable seconds) × account multiplier). Actual duration can be fractional; credit amounts have at most two decimal places.

Examples for a 720p output with billing duration O = 10 seconds and an account multiplier of 1:

For example, a request with duration: 10, 1080p, no input video, and an account multiplier of 1 costs 585.90 credits, even if the actual video is 10.041 seconds long. The actual duration remains available in usage.output_seconds.

Creation reserves credits first: explicit duration reserves the requested output seconds; automatic duration reserves up to 30 output seconds. Video or subject inputs also reserve up to 30 input seconds, covering subjects whose type is not yet confirmed. Successful generation is settled using the duration rules above and the confirmed input category; the unused reservation is returned once.

For automatic duration at an account multiplier of 1, requests without videos or subjects reserve 1171.80 credits at 720p or 1757.70 at 1080p. Requests with videos or subjects reserve 1406.40 or 2109.60, respectively. Image subjects are ultimately billed at the no-video rate, so their reservation can exceed the final charge.

Prices and the account multiplier are fixed at creation. Confirmed failures return the reservation. Successful generation with usage still under review remains pending finalization and does not receive a full failure refund. Use credits_consumed on the completed task as the final charge.

Endpoint and authentication

Use POST https://api.aivideoapi.ai/v1/videos/generations for all three models, with your platform API key:

Authorization: Bearer YOUR_PLATFORM_API_KEY
Content-Type: application/json

Place callback_url at the top level, beside model and input, not inside input.options. This endpoint does not accept external_task_id. Save the returned taskId and associate it with your own application record.

Every JSON example below is a complete request body for the same generation endpoint. Replace example material and callback URLs with accessible real URLs.

Text-to-video

input.prompt is required and must be nonempty. This model does not accept input.contents. This example creates a 10-second, 1080p landscape video and requests an additional watermarked version:

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-4.0-text-to-video",
    "input": {
      "prompt": "A lake at sunrise, the camera slowly moves forward as mist clears, with gentle water sounds.",
      "settings": { "resolution": "1080p", "duration": 10, "aspect_ratio": "16:9" },
      "options": { "watermark_info": { "enabled": true } }
    },
    "callback_url": "https://app.example.com/webhooks/video"
  }'

For automatic duration, omit settings.duration:

{
  "model": "kling-4.0-text-to-video",
  "input": {
    "prompt": "Create a 15-second video of a sailboat slowly crossing a bay at sunset.",
    "settings": { "resolution": "720p" }
  }
}

Multiple keyframes

input.contents must include at least one image and may include one prompt item. Supported image types are first_frame, middle_frame, and last_frame, with at most 10 images total and one first and one last frame. Image-to-video follows the images' aspect ratio; do not send settings.aspect_ratio.

{
  "model": "kling-4.0-image-to-video",
  "input": {
    "contents": [
      { "type": "prompt", "text": "Move smoothly from @start through @middle to @end, preserving the character's appearance." },
      { "type": "first_frame", "url": "https://media.example.com/start.jpg", "id": "start" },
      { "type": "middle_frame", "url": "https://media.example.com/middle.jpg", "id": "middle" },
      { "type": "last_frame", "url": "https://media.example.com/end.jpg", "id": "end" }
    ],
    "settings": { "resolution": "720p", "duration": 10 }
  }
}

A single first_frame without a prompt is also valid. Image-to-video does not accept input.prompt, refer_image, videos, subjects, or voices; use Omni for those reference types.

Omni references and video editing

input.contents is a nonempty array with at most one prompt item. A material's id lets you refer to it as @id in the prompt. Material IDs must be unique within a request.

Image and video id fields are normally optional. In Omni, multiple middle_frame or multiple refer_image items require an id on every image of that type. Subjects and voices always require id; it is a reference name for this request, distinct from the existing element_id or voice_id.

Videos and video subjects share a limit of five. Images, videos, subjects, and voices together cannot exceed 15 materials, excluding the prompt. A video subject counts toward both the subject and video limits, but only once toward the 15-material total. The generation endpoint references existing available subjects and voices; it does not create or manage them.

Edit a video

This example leaves output duration automatic and combines a video to edit with an image reference. Describe both the requested change and what should remain unchanged:

{
  "model": "kling-4.0-omni",
  "input": {
    "contents": [
      { "type": "prompt", "text": "Change the jacket in @clip to the color in @reference. Preserve the character's motion, background, and camera movement." },
      { "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", "aspect_ratio": "adaptive" }
  },
  "callback_url": "https://app.example.com/webhooks/video"
}

Reference a subject and voice

Replace the subject and voice IDs with available real IDs. Both image subjects and video subjects use element; you do not declare their type in the request.

{
  "model": "kling-4.0-omni",
  "input": {
    "contents": [
      { "type": "prompt", "text": "@hero stands by the sea and says: A new journey begins, using @narrator's voice. Follow the camera movement in @motion." },
      { "type": "element", "element_id": "REPLACE_WITH_ELEMENT_ID", "id": "hero" },
      { "type": "voice", "voice_id": "REPLACE_WITH_VOICE_ID", "id": "narrator" },
      { "type": "feature_video", "url": "https://media.example.com/motion.mp4", "id": "motion" }
    ],
    "settings": { "resolution": "720p", "duration": 10, "aspect_ratio": "16:9" }
  }
}

Shared settings and material requirements

Explicit duration overrides the prompt. Omitting it preserves automatic duration: the model first follows a duration described in the prompt. Otherwise text/image generation defaults to 10 seconds; Omni follows base_video when present, or defaults to 10 seconds. Automatic requests still reserve up to 30 output seconds; the 10-second default is not the reservation limit.

Prompts must be nonempty. Pure ASCII text supports up to 26,000 characters, and non-ASCII text up to 11,000 Unicode characters. Mixed text must satisfy ASCII characters / 26000 + non-ASCII characters / 11000 ≤ 1. For image and Omni requests, put the prompt in a contents item's text, not in input.prompt.

• Images support JPG/JPEG/PNG via HTTP(S) URLs or Base64, optionally with an image data URL prefix. Each image must be at most 30 MB, at least 300 px in each dimension, and have an aspect ratio from 2:5 to 5:2. Use URLs for large images to avoid exceeding the total request body limit with Base64.
• Videos require HTTP(S) URLs, MP4/MOV format, and at most 300 MB per file. Each video and the combined input-video duration must be 3–30 seconds; the combined duration includes video subjects.
• Input-video dimensions must each be 700–4553 px, with at most 8,294,400 pixels total, an aspect ratio from 2:5 to 5:2, and 24–60 fps.
• Material URLs must be downloadable without signing in and cannot contain a username or password. Media format, dimensions, and content are also checked during generation; a valid URL alone does not guarantee a valid material.

Unsupported generation fields are rejected. Follow this page's structure instead of using other models' image_urls, video_urls, negative_prompt, or audio switches.

Creation response and task query

Successful creation means the task has been accepted, and returns its platform ID:

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

Query with a platform API key from the same account:

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

Example success for a 10-second 720p output without input video, at an account multiplier of 1:

{
  "id": "29bd04f8-3c15-4374-a364-4b484782d235",
  "status": "completed",
  "model": "kling-4.0-text-to-video",
  "credits_consumed": 390.60,
  "created_at": 1793404800,
  "completed_at": 1793404920,
  "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": 10 }
}

The query returns the task object directly, without the creation response's code, msg, or data wrapper. Timestamps are Unix seconds. credits_consumed is the finalized charge; a value of 0 while processing does not mean that no credits were reserved. usage.output_seconds always preserves the actual output duration, which may differ from an explicitly requested billing duration. Tasks with video input may also return usage.input_seconds, including video subjects.

Video URLs

By default, the API returns the provider's original video URLs without copying the files to platform storage. The main video is in output.urls. If requested and generated, the watermarked version is in output.metadata.watermark_urls; otherwise that field may be absent. Queries and successful callbacks use the same result structure.

Preserve the complete URL, including its signature and query parameters. Download and save files to your own storage promptly. URLs may expire and files may be removed; task-record retention is not a guarantee of downloadable media or a fixed URL lifetime.

These three models do not support cancellation. Once you have a taskId, continue querying that task instead of creating another request because it is still processing or a query timed out. A new creation request may create a separate task and charge.

Completion callbacks

Set top-level callback_url when creating a task to receive a JSON POST after completion or confirmed failure. Successful callback bodies use the success-task structure above. Failure callbacks contain status="failed" and error. Intermediate pending and processing states are not sent.

The platform receives model-service status callbacks and uses task queries to recover missed notifications or missing usage. Provide only your application's notification URL in top-level callback_url; you do not need to configure the model service's callback address or include one in input.options. A successful generation is settled before its completion notification is sent. Tasks with missing required usage remain pending reconciliation.

Process callbacks idempotently using X-Event-ID or the task ID and terminal status, and return HTTP 2xx within 10 seconds. Failed delivery is retried at most twice, after 3 minutes and then 10 minutes, subject to scheduling. These headers are not a signature; to confirm authenticity, query the task using your platform API key before updating application state.

Callback delivery failures do not regenerate videos or change a completed task's charge. Keep task polling available as a fallback for missed notifications.