# Kling V3 (kling-v3)

Vendor: KlingAI
Model ID: `kling-v3`
Base URL: `https://api.mulerouter.ai`
Type: Inference API (async task-based)

## Description
Latest Kling video generation model with multi-shot, audio generation, element reference, and 3-15s duration support

## Variant: Text to Video Generation

Endpoint: `POST /vendors/klingai/v1/kling-v3/text-to-video/generation`

### Input Schema
The API accepts the following input parameters:

- **`mode`** (`string`, _optional_):
  Video generation mode.  `std`: Standard Mode (720P), cost-effective. `pro`: Professional Mode (1080P), higher quality video output. 
  - Options: `"std"`, `"pro"`
  - Default: `"std"`

- **`sound`** (`string`, _optional_):
  Generate audio simultaneously when generating videos. - `on`: Enable audio generation - `off`: Disable audio generation (silent video) 
  - Options: `"on"`, `"off"`
  - Default: `"off"`

- **`prompt`** (`string | null`, _optional_):
  Positive text prompt. Cannot exceed 2500 characters.  Required when `multi_shot` is `false` or when `shot_type` is `intelligence`. 
  - Max length: 2500

- **`duration`** (`integer`, _optional_):
  Video length in seconds.
  - Options: `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15`
  - Default: `5`

- **`shot_type`** (`string | null`, _optional_):
  Shot segmentation method. Required when `multi_shot` is `true`. - `customize`: Custom shots, requires `multi_prompt`. - `intelligence`: AI-generated shots, requires `prompt`. 
  - Options: `"customize"`, `"intelligence"`

- **`multi_shot`** (`boolean`, _optional_):
  Whether to generate a multi-shot video. - `true`: Enable multi-shot mode. `prompt` is ignored; use `shot_type` and `multi_prompt` instead. - `false`: Single-shot mode (default). 
  - Default: `false`

- **`aspect_ratio`** (`string`, _optional_):
  The aspect ratio of the generated video frame (width:height).
  - Options: `"16:9"`, `"9:16"`, `"1:1"`
  - Default: `"16:9"`

- **`multi_prompt`** (`list<any>`, _optional_):
  Shot prompt list for multi-shot videos. - Max 6 shots, min 1 shot. - Each shot prompt max 512 characters. - Each shot duration must not exceed total duration and must be >= 1. - Sum of all shot durations must equal total task duration.  Required when `multi_shot` is `true` and `shot_type` is `customize`. 
  - Items: min: 1, max: 6

  - **`prompt`** (`string`, _required_):
    Text prompt for this shot. Max 512 characters.
    - Max length: 512

  - **`duration`** (`integer`, _required_):
    Duration of this shot in seconds. Must be >= 1 and <= total task duration.

- **`negative_prompt`** (`string | null`, _optional_):
  Negative text prompt. Cannot exceed 2500 characters.
  - Max length: 2500

**Full Example**:

```json
{
  "mode": "std",
  "sound": "off",
  "prompt": null,
  "duration": 5,
  "shot_type": "customize",
  "multi_shot": false,
  "aspect_ratio": "16:9",
  "multi_prompt": [],
  "negative_prompt": null
}
```

## Variant: Image to Video Generation

Endpoint: `POST /vendors/klingai/v1/kling-v3/image-to-video/generation`

### Input Schema
The API accepts the following input parameters:

- **`mode`** (`string`, _optional_):
  Video generation mode.  `std`: Standard Mode (720P), cost-effective. `pro`: Professional Mode (1080P), higher quality video output. 
  - Options: `"std"`, `"pro"`
  - Default: `"std"`

- **`sound`** (`string`, _optional_):
  Generate audio simultaneously when generating videos. - `on`: Enable audio generation - `off`: Disable audio generation (silent video) 
  - Options: `"on"`, `"off"`
  - Default: `"off"`

- **`prompt`** (`string | null`, _optional_):
  Positive text prompt. Cannot exceed 2500 characters.  Required when `multi_shot` is `false` or when `shot_type` is `intelligence`. 
  - Max length: 2500

- **`duration`** (`integer`, _optional_):
  Video length in seconds.
  - Options: `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15`
  - Default: `5`

- **`elements`** (`list<any>`, _optional_):
  Element definitions. Max 3 elements. Provide frontal and reference images. Use `<<<element_1>>>` in prompt to reference elements. 
  - Items: min: 1, max: 3

  - **`type`** (`string`, _required_):
    Element type.
    - Options: `"image"`, `"video"`

  - **`frontal_image`** (`string | null`, _optional_):
    Frontal reference image of the subject (URL or Base64). Constraints: jpg/jpeg/png, <=10MB, >=300px, aspect ratio 1:2.5~2.5:1.

  - **`reference_images`** (`list<string>`, _optional_):
    Additional reference images from other angles (URL or Base64), up to 3 images.
    - Items: min: 1, max: 3

  - **`reference_videos`** (`list<string>`, _optional_):
    Reference video URLs.
    - Items: min: 1

- **`shot_type`** (`string | null`, _optional_):
  Shot segmentation method. Required when `multi_shot` is `true`. - `customize`: Custom shots, requires `multi_prompt`. - `intelligence`: AI-generated shots, requires `prompt`. 
  - Options: `"customize"`, `"intelligence"`

- **`last_frame`** (`string | null`, _optional_):
  Last frame image (URL or Base64). Sets the closing frame of the generated video.  - At least one of `first_frame` and `last_frame` must be provided. - `last_frame`, `dynamic_masks`/`static_mask`, and `camera_control` are mutually exclusive. 

- **`multi_shot`** (`boolean`, _optional_):
  Whether to generate a multi-shot video. - `true`: Enable multi-shot mode. `prompt` is ignored; use `shot_type` and `multi_prompt` instead. - `false`: Single-shot mode (default). 
  - Default: `false`

- **`first_frame`** (`string | null`, _optional_):
  First frame image (URL or Base64). Sets the opening frame of the generated video.  **Important**: When using Base64 encoding, do not add any prefixes such as `data:image/png;base64,`. Provide only the Base64-encoded string itself.  - Supported image formats: .jpg, .jpeg, .png - Image file size cannot exceed 10MB - Width and height dimensions must not be less than 300px - Aspect ratio should be between 1:2.5 ~ 2.5:1 - At least one of `first_frame` and `last_frame` must be provided. 

- **`multi_prompt`** (`list<any>`, _optional_):
  Shot prompt list for multi-shot videos. - Max 6 shots, min 1 shot. - Each shot prompt max 512 characters. - Each shot duration must not exceed total duration and must be >= 1. - Sum of all shot durations must equal total task duration.  Required when `multi_shot` is `true` and `shot_type` is `customize`. 
  - Items: min: 1, max: 6

  - **`prompt`** (`string`, _required_):
    Text prompt for this shot. Max 512 characters.
    - Max length: 512

  - **`duration`** (`integer`, _required_):
    Duration of this shot in seconds. Must be >= 1 and <= total task duration.

- **`negative_prompt`** (`string | null`, _optional_):
  Negative text prompt. Cannot exceed 2500 characters.
  - Max length: 2500

**Full Example**:

```json
{
  "mode": "std",
  "sound": "off",
  "prompt": null,
  "duration": 5,
  "elements": [],
  "shot_type": "customize",
  "last_frame": null,
  "multi_shot": false,
  "first_frame": null,
  "multi_prompt": [],
  "negative_prompt": null
}
```

## Variant: /vendors/klingai/v1/kling-v3/text-to-video/generation/{task_id}

Endpoint: `POST /vendors/klingai/v1/kling-v3/text-to-video/generation/{task_id}`

## Variant: /vendors/klingai/v1/kling-v3/image-to-video/generation/{task_id}

Endpoint: `POST /vendors/klingai/v1/kling-v3/image-to-video/generation/{task_id}`

## Usage (Async Task API)
This model uses an async task-based workflow with two API calls:
1. **Submit a task** — `POST /v1/inference/kling-v3` to create a generation task
2. **Poll for result** — `GET /v1/inference/kling-v3/{task_id}` to check status and retrieve the result

### Step 1: Submit a Task

#### cURL
```bash
curl -X POST https://api.mulerouter.ai/vendors/klingai/v1/kling-v3/text-to-video/generation \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_MULEROUTER_API_KEY>" \
  -d '{
    "prompt": "Your prompt here"
  }'
```

#### Python
```python
import requests

API_KEY = "<YOUR_MULEROUTER_API_KEY>"
ENDPOINT = "https://api.mulerouter.ai/vendors/klingai/v1/kling-v3/text-to-video/generation"

response = requests.post(
    ENDPOINT,
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {API_KEY}"
    },
    json={
        "prompt": "Your prompt here"
    }
)

result = response.json()
task_id = result["task_info"]["id"]
print(f"Task created: {task_id}")
```

#### Node.js / TypeScript
```typescript
const API_KEY = "<YOUR_MULEROUTER_API_KEY>";
const ENDPOINT = "https://api.mulerouter.ai/vendors/klingai/v1/kling-v3/text-to-video/generation";

const response = await fetch(ENDPOINT, {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
        prompt: "Your prompt here"
    })
});

const result = await response.json();
const taskId = result.task_info.id;
console.log("Task created:", taskId);
```

#### Submit Response (202)
```json
{
  "task_info": {
    "id": "8e1e315e-b50d-4334-a231-be7d19a372f4",
    "status": "processing",
    "created_at": "2026-01-01T00:00:00.000Z"
  }
}
```

### Step 2: Poll for Result

Use the task ID from Step 1 to poll the status endpoint until the task is completed.

Endpoint: `GET /v1/inference/kling-v3/{task_id}`

#### cURL
```bash
curl -X GET https://api.mulerouter.ai/vendors/klingai/v1/kling-v3/text-to-video/generation/<TASK_ID> \
  -H "Authorization: Bearer <YOUR_MULEROUTER_API_KEY>"
```

#### Python
```python
import time

status_url = f"https://api.mulerouter.ai/vendors/klingai/v1/kling-v3/text-to-video/generation/{task_id}"

while True:
    status = requests.get(status_url, headers={
        "Authorization": f"Bearer {API_KEY}"
    }).json()
    task_status = status["task_info"]["status"]
    if task_status in ("completed", "succeeded"):
        print("Result:", status)
        break
    elif task_status == "failed":
        print("Task failed:", status)
        break
    time.sleep(5)
```

#### Node.js / TypeScript
```typescript
const statusUrl = `https://api.mulerouter.ai/vendors/klingai/v1/kling-v3/text-to-video/generation/${taskId}`;

while (true) {
    const statusRes = await fetch(statusUrl, {
        headers: { "Authorization": `Bearer ${API_KEY}` }
    });
    const status = await statusRes.json();
    const taskStatus = status.task_info.status;
    if (taskStatus === "completed" || taskStatus === "succeeded") {
        console.log("Result:", status);
        break;
    } else if (taskStatus === "failed") {
        console.log("Task failed:", status);
        break;
    }
    await new Promise(r => setTimeout(r, 5000));
}
```

## Additional Resources

### Documentation

- [Model Playground](https://www.mulerouter.ai/models/kling-v3)
- [API Documentation](https://mulerouter.ai/docs/api-reference/endpoint/klingai/kling-v3)

### MuleRouter Platform

- [Platform Documentation](https://www.mulerouter.ai/docs)
- [API Keys Management](https://www.mulerouter.ai/app/api-keys)