Kling 3.0

Kling 3.0 is Kuaishou's latest video generation model, supporting text-to-video and image-to-video, native audio, and 3-15 second outputs.

Model

Model Name	Modes
`kling-3.0`	std (720P), pro (1080P)

Pricing

Billed per second × mode × audio:

Mode	Audio	Resolution	Credits/sec
std	off	720P	28
std	on	720P	40
pro	off	1080P	36
pro	on	1080P	54

Credits are pre-charged as duration × rate when the task is created. Failed tasks are automatically refunded.

Create Task

POST https://api.aivideoapi.ai/v1/videos/generations

Request Body

Field	Type	Required	Description
`model`	string	Yes	Must be `kling-3.0`
`input`	object	Yes	Generation parameters, see below
`callback_url`	string	No	URL to receive task completion/failure notifications

Input Object

Field	Type	Required	Description
`prompt`	string	No*	Single-shot text prompt, up to 2500 characters. Supports `@element_name` references (see Element References)
`image_urls`	string[]	No*	Single-shot: 1-2 frames (start/end); Multi-shot: 1 URL only
`mode`	string	No	`std` (default, 720P) or `pro` (1080P)
`aspect_ratio`	string	No	`16:9` (default), `9:16`, or `1:1`. Auto-adapts to image dimensions when `image_urls` provided.
`duration`	integer	No	Total video duration in seconds, 3-15, default 5
`sound`	boolean	No	Generate native audio. Default `false` in single-shot, `true` in multi-shot
`multi_shots`	boolean	No	Enable multi-shot mode, default `false`
`multi_prompt`	object[]	No*	Shot list, max 5. Required when `multi_shots: true`
`kling_elements`	object[]	No	Element references (max 3 per task) for use via `@name` in prompts

*At least one of prompt, image_urls, or multi_prompt is required.

`multi_prompt[]` fields

Field	Type	Required	Description
`prompt`	string	Yes	Shot description, up to 500 characters
`duration`	integer	Yes	Individual shot duration, 1-12 seconds

The sum of all shot durations should be ≤ top-level duration (≤ 15 seconds).

`kling_elements[]` fields

Field	Type	Required	Description
`name`	string	Yes	Element identifier, referenced as `@name` in prompts
`description`	string	Yes	Element description
`element_input_urls`	string[]	Yes	2-4 reference images (JPG/PNG, ≤10MB each)

📌 Element reference notes

The @name in your prompt must exactly match kling_elements[].name (without the @ prefix)

A single task can reference at most 3 elements

Each @element reference counts as 37 characters toward the prompt length limit (2500 single-shot / 500 per shot) — leave room accordingly

Example: Text-to-Video (Standard)

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "A drone shot flying over mountains at sunset, cinematic lighting",
      "mode": "std",
      "aspect_ratio": "16:9",
      "duration": 5,
      "sound": true
    }
  }'

Example: Image-to-Video (Pro)

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0",
    "input": {
      "prompt": "Butterfly takes off in slow motion, macro lens",
      "image_urls": ["https://example.com/butterfly.jpg"],
      "mode": "pro",
      "duration": 10
    }
  }'

Example: Multi-Shot Mode

Chain multiple shots into a narrative video. Each shot has its own prompt and duration.

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0",
    "input": {
      "mode": "pro",
      "duration": 12,
      "multi_shots": true,
      "multi_prompt": [
        { "prompt": "Drone shot of mountain peaks above the clouds at sunrise", "duration": 4 },
        { "prompt": "Camera descends through clouds revealing a forest cabin", "duration": 4 },
        { "prompt": "Inside the cabin, a cat curled up sleeping by the fireplace", "duration": 4 }
      ]
    }
  }'

Example: Element References

Define reusable characters or objects via kling_elements, then reference them in prompts using @name.

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0",
    "input": {
      "prompt": "@shiba_dog chasing a butterfly under a cherry blossom tree, slow motion",
      "mode": "pro",
      "duration": 5,
      "kling_elements": [
        {
          "name": "shiba_dog",
          "description": "A brown Shiba Inu dog",
          "element_input_urls": [
            "https://example.com/dog1.jpg",
            "https://example.com/dog2.jpg"
          ]
        }
      ]
    }
  }'

⚠️ Each element requires 2-4 reference images; up to 3 elements per task.

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "cbf6b69d-4f03-4817-8ed7-94c0292184a8"
  }
}

Query Task

curl https://api.aivideoapi.ai/v1/tasks/{taskId} \
  -H "Authorization: Bearer sk-your-api-key"

Status transitions: pending -> processing -> completed or failed.

Processing

{
  "id": "e717a5ee-2ed4-47f4-8cc3-53394f1abb35",
  "status": "processing",
  "model": "kling-3.0",
  "created_at": 1774706165,
  "progress": null
}

Completed

{
  "id": "7d89c51e-9430-410e-909e-df347131ebaa",
  "status": "completed",
  "model": "kling-3.0",
  "created_at": 1774790227,
  "completed_at": 1774796529,
  "output": {
    "urls": [
      "/videos/2026/04/04/abc123.mp4"
    ],
    "metadata": {
      "model": "kling-3.0/video"
    }
  }
}

Video URLs are permanent.

Failed

{
  "id": "57c8772c-f834-46f3-9b7d-81f92e104050",
  "status": "failed",
  "model": "kling-3.0",
  "created_at": 1774793758,
  "error": {
    "code": "upstream_error",
    "message": "Video generation failed"
  }
}

When a task fails, pre-charged credits are automatically refunded.

Callback

Pass callback_url when creating the task. The system will automatically send a POST request to your URL when the task completes or fails. The format matches the query task response.

Error Codes

When a request fails, the API returns a JSON error response:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low. Please top up.",
    "type": "billing_error"
  }
}

Error Reference

HTTP Status	Code	Type	Description
400	`invalid_request`	invalid_request_error	Missing or invalid parameters
401	`invalid_api_key`	authentication_error	API key is invalid, disabled, or deleted
402	`insufficient_credits`	billing_error	Credit balance too low, please top up
403	`ip_not_allowed`	permission_error	Request IP not in the key's allowlist
404	`model_not_found`	invalid_request_error	Model does not exist or is inactive
404	`task_not_found`	invalid_request_error	Task ID does not exist
429	`rate_limit_exceeded`	rate_limit_error	Too many requests, please slow down
429	`spend_limit_exceeded`	billing_error	Key spend limit reached (hourly/daily/total)
500	`internal_error`	api_error	Unexpected server error
503	`upstream_error`	upstream_error	Upstream AI provider returned an error

Common Scenarios

invalid_request (400)

Returned when required fields are missing or invalid.

{
  "error": {
    "code": "invalid_request",
    "message": "'model' is required.",
    "type": "invalid_request_error"
  }
}

insufficient_credits (402)

Your balance is too low. Check your balance with GET /v1/credits and top up in Dashboard > Billing.

invalid_api_key (401)

Possible causes:

The key does not start with sk-
The key has been disabled or deleted
The user account has been banned

upstream_error (503)

The upstream AI provider returned an error. This may happen when:

The input contains sensitive or prohibited content
The provider is temporarily unavailable
The request parameters are not supported by the provider

Credits are automatically refunded when a task fails due to upstream errors.