Kling Video

Kling Video uses an asynchronous video task API. Create a task first, then poll the task endpoint for status and the final video URL.

Recommended integration: Unified Video API

For new integrations, use /v1/video/generations to create tasks and /v1/video/generations/{task_id} to retrieve results.

Endpoints

Unified Video API

Capability	Method	Path
Create video task	POST	/v1/video/generations
Retrieve video task	GET	/v1/video/generations/{task_id}

Every request requires an API key:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Models

Model
kling-v3
kling-v3-omni

Actual availability depends on your account permissions.

Supported Modes

Mode	How to call
Text to video	Use prompt with kling-v3 or kling-v3-omni
Image to video	Use image for the first frame
First and last frame	Use image for the first frame and metadata.image_tail for the last frame
Omni video	Use kling-v3-omni with Omni fields in metadata
Camera control	Use metadata.camera_control when supported by the selected model

Unified API Request Parameters

Field	Type	Required	Description
model	string	Yes	Kling model name
prompt	string	Yes	Video generation prompt
image	string	No	First-frame image URL. When provided, the request is handled as image-to-video
mode	string	No	Quality/generation tier, such as std, pro, or 4k. Defaults to std. Actual availability depends on the model and account permissions
duration	number	No	Video duration in seconds. Defaults to 5. kling-v3 / kling-v3-omni generally support 3 to 15 seconds; for multi-shot generation, the total duration must not exceed 15 seconds
size	string	No	Used to infer aspect ratio, not forwarded as an output resolution directly; for example, 1920x1080 => 16:9, 1080x1920 => 9:16, 1024x1024 => 1:1
metadata	object	No	Kling-specific options

Use mode to control the quality tier. size only lets the unified API infer aspect_ratio; do not use size as the parameter for 720P, 1080P, or 4K output.

metadata Fields

Supported metadata fields are merged into the request body sent to Kling. The public fields currently supported are listed below; fields not listed here are not guaranteed to be forwarded.

Field	Type	Description
negative_prompt	string	Negative prompt
aspect_ratio	string	Aspect ratio, such as 16:9, 9:16, 1:1
image_tail	string	Last-frame image URL
cfg_scale	number	Prompt relevance
camera_control	object	Camera control
static_mask	string	Static mask
dynamic_masks	object[]	Dynamic masks
callback_url	string	Callback URL
external_task_id	string	Client-defined task ID
sound	boolean/object	Omni audio switch or audio configuration
image_list	object[]	Omni image inputs, such as first frame, end frame, or reference images
video_list	object[]	Omni video inputs
element_list	object[]	Omni character, subject, or asset inputs
multi_shot	boolean	Whether to enable Omni multi-shot generation
shot_type	string	Omni multi-shot type
multi_prompt	string/object[]	Omni multi-shot prompts
voice_list	object[]	Omni voice or dialogue inputs
watermark_info	object	Watermark configuration

Examples

Text to Video

curl -X POST https://cubicspaces.cloud/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kling-v3",
    "prompt": "A cinematic shot of a futuristic cubic city at sunrise, slow camera movement, realistic lighting",
    "mode": "std",
    "duration": 5,
    "size": "1920x1080",
    "metadata": {
      "aspect_ratio": "16:9",
      "negative_prompt": "blur, distortion, low quality"
    }
  }'

Image to Video

curl -X POST https://cubicspaces.cloud/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kling-v3",
    "prompt": "Animate the product from the first frame with a slow clockwise rotation, keep the product shape stable",
    "image": "https://example.com/first-frame.png",
    "mode": "std",
    "duration": 5,
    "metadata": {
      "aspect_ratio": "16:9",
      "negative_prompt": "deformation, flicker"
    }
  }'

First and Last Frame

curl -X POST https://cubicspaces.cloud/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kling-v3",
    "prompt": "Create a smooth transition from the first frame to the last frame",
    "image": "https://example.com/first-frame.png",
    "duration": 5,
    "metadata": {
      "image_tail": "https://example.com/last-frame.png",
      "aspect_ratio": "16:9"
    }
  }'

Omni Video

kling-v3-omni uses the Omni video capability. It supports text-to-video, first/end frames, reference images, reference videos, multi-shot inputs, and audio-related inputs. The simplest text-to-video request can use the unified video API:

curl -X POST https://cubicspaces.cloud/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kling-v3-omni",
    "prompt": "A cinematic shot of a futuristic city at sunset, smooth camera movement, high detail, realistic lighting",
    "mode": "std",
    "duration": 5,
    "size": "1920x1080",
    "metadata": {
      "aspect_ratio": "16:9"
    }
  }'

For first/end-frame Omni generation, you can also use image and metadata.image_tail:

curl -X POST https://cubicspaces.cloud/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kling-v3-omni",
    "prompt": "Create a smooth transition from the first frame to the last frame, keep the subject identity consistent",
    "image": "https://example.com/first-frame.png",
    "duration": 8,
    "metadata": {
      "image_tail": "https://example.com/last-frame.png",
      "aspect_ratio": "16:9",
      "mode": "std"
    }
  }'

For richer Omni inputs, pass image_list, video_list, element_list, multi_shot, and related fields in metadata:

{
  "model": "kling-v3-omni",
  "prompt": "A product showcase with a close-up opening shot and a final wide studio shot",
  "duration": 10,
  "metadata": {
    "mode": "pro",
    "aspect_ratio": "16:9",
    "image_list": [
      {
        "image_url": "https://example.com/first-frame.png",
        "type": "first_frame"
      },
      {
        "image_url": "https://example.com/end-frame.png",
        "type": "end_frame"
      }
    ],
    "multi_shot": true,
    "multi_prompt": [
      "Close-up of the product with soft studio lighting",
      "Wide shot showing the product in a clean futuristic showroom"
    ]
  }
}

Camera Control Example

{
  "model": "kling-v3",
  "prompt": "A slow push-in shot toward the product on a clean studio table",
  "image": "https://example.com/product.png",
  "duration": 5,
  "metadata": {
    "aspect_ratio": "16:9",
    "camera_control": {
      "type": "simple",
      "config": {
        "zoom": 1.2,
        "horizontal": 0,
        "vertical": 0
      }
    }
  }
}

Response and Retrieval

A successful unified create request returns a video task object:

{
  "id": "video_xxx",
  "task_id": "video_xxx",
  "object": "video",
  "model": "kling-v3",
  "status": "queued",
  "progress": 0,
  "created_at": 1770000000
}

Use either id or task_id to retrieve the task.

Retrieve the task:

curl https://cubicspaces.cloud/v1/video/generations/video_xxx \
  -H "Authorization: Bearer YOUR_API_KEY"

Completed task response:

{
  "id": "video_xxx",
  "task_id": "video_xxx",
  "object": "video",
  "model": "kling-v3",
  "status": "completed",
  "progress": 100,
  "seconds": "5",
  "created_at": 1770000000,
  "completed_at": 1770000120,
  "metadata": {
    "url": "https://example.com/output.mp4"
  }
}

Status Values

status	Description
queued	The task is queued
in_progress	The task is running
completed	The task has completed
failed	The task failed

When the task is completed, read the video URL from metadata.url.