# Kling V3

> Long-form video up to 15s with native audio and start/end frame control.

## Overview

- **Model ID**: `kling-v3`
- **Workflow**: `kling-text-to-video`
- **Provider**: Kling
- **Category**: Text → Video (video)
- **Output**: A video URL.
- **Tags**: popular, premium, image input, start/end frame, audio, 1080p, 15 sec
- **Unified endpoint**: `POST https://api.picsart.com/workflows/v1/models/execute` (model id in the body)
- **Compatibility endpoint**: `POST https://api.picsart.com/workflows/kling-text-to-video/execute` (vendor's own parameters)
- **Execution**: long-running — use the async submit/poll pair or the SDK, which polls for you
- **Model page**: https://picsart.com/api-platform/models/kling-v3

## Pricing

Rates are in USD. Every row below is an exact rate for the settings it names — the columns are the settings that change the price for this model. Every response reports what was actually charged in `response.usage.credits`.

| Tier | Audio | Rate |
| --- | --- | --- |
| Standard | No | $0.084 / sec |
| Pro | No | $0.112 / sec |
| Standard | Yes | $0.126 / sec |
| Pro | Yes | $0.168 / sec |
| 4K | Any | $0.42 / sec |

Published rates. Volume pricing, invoicing and annual agreements: https://picsart.com/api-platform/contact-sales

## Authentication

The SDK and the REST API authenticate with a Picsart API key sent as a bearer token. Create a key in the console at https://picsart.com/api-platform/dashboard/api-keys, keep it in a server-side environment variable, and never ship it in browser code or commit it.

```bash
export PICSART_API_KEY="YOUR_KEY"
```

```http
Authorization: Bearer $PICSART_API_KEY
```

The CLI and the MCP server do not use an API key: `gen-ai login` signs in through the browser once per machine and stores a token locally.

## Interfaces

- **SDK** — `@picsart/ai-sdk` (TypeScript, Node 20+, ESM). Type-safe `ai.generate()` / `ai.generateText()` with per-model parameter types; polls long jobs for you.
- **REST** — the API gateway at `https://api.picsart.com`. Sync `/execute`, or async `/submit` + `/{taskId}/result`.
- **CLI** — `@picsart/gen-ai` (`gen-ai`). Generate from a terminal, quote cost before spending, emit JSON for pipelines.
- **MCP** — the same models inside Claude Code, Cursor, Windsurf and other MCP hosts. Setup: https://picsart.com/gen-ai-mcp/

```bash
npm install @picsart/ai-sdk      # SDK
npm install -g @picsart/gen-ai   # CLI (also drives the MCP server)
```

## Unified API (recommended)

One parameter set, used by the SDK and by REST alike: the names below are what `ai.generate('kling-v3', …)` takes, and what goes inside the inner `params` of a REST call. Over REST the model id travels in the body, not the path — one workflow, `v1/models`, fronts the whole catalogue.

### Execution modes

- **Sync** — `POST /workflows/v1/models/execute` returns the result in one call. Only for jobs that finish within ~20 seconds; otherwise it times out.
- **Async** — `POST /workflows/v1/models/submit` returns a task id; poll `GET /workflows/v1/models/{taskId}/result` until `response.status` is `COMPLETED` or `FAILED`. Task statuses: `ACCEPTED` · `IN_PROGRESS` · `COMPLETED` · `FAILED`.
- **SDK** — `ai.generate()` always awaits the finished result; polling is hidden.

Video jobs routinely outrun the sync limit: use async over REST, or the SDK, which polls for you.

### Input parameters

- **`prompt`** (`string`, _required_): Prompt
  - Max length: 2500 characters
- **`aspectRatio`** (`string`, _optional_)
  - Default: `"16:9"`
  - Options: `16:9`, `9:16`, `1:1`
- **`duration`** (`number`, _optional_)
  - Default: `5`
  - Range: 3–15 (step 1)
- **`startFrame`** (`string`, _optional_): Start Frame
  - Accepts: image URL
- **`endFrame`** (`string`, _optional_): End Frame
  - Accepts: image URL
- **`negativePrompt`** (`string`, _optional_): Negative Prompt
- **`generateAudio`** (`boolean`, _optional_)
  - Default: `true`
- **`multiShot`** (`boolean`, _optional_): Multi-Shot Mode
  - Default: `false`
- **`shotType`** (`string`, _optional_): Shot Segmentation
  - Default: `"customize"`
  - Options: `customize`, `intelligence`
- **`multiPrompt`** (`object`, _optional_): Multi-Shot Prompts
  - Fields: `index`, `prompt`, `duration`
- **`voiceList`** (`object`, _optional_): Voice References
  - Fields: `voice_id`
- **`elementList`** (`object`, _optional_): Element References
  - Fields: `element_id`
- **`renderingSpeed`** (`string`, _optional_)
  - Default: `"4k"`
  - Options: `std`, `pro`, `4k`

### Input JSON Schema

The inner `params` object. Over REST it is wrapped as `{ "params": { "model": "<id>", "params": <this> } }`; the SDK takes it directly.

```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "prompt": {
      "type": "string",
      "maxLength": 2500,
      "description": "Prompt"
    },
    "aspectRatio": {
      "type": "string",
      "enum": [
        "16:9",
        "9:16",
        "1:1"
      ],
      "default": "16:9"
    },
    "duration": {
      "type": "number",
      "minimum": 3,
      "maximum": 15,
      "multipleOf": 1,
      "default": 5
    },
    "startFrame": {
      "type": "string",
      "format": "uri",
      "description": "Start Frame"
    },
    "endFrame": {
      "type": "string",
      "format": "uri",
      "description": "End Frame"
    },
    "negativePrompt": {
      "type": "string",
      "description": "Negative Prompt"
    },
    "generateAudio": {
      "type": "boolean",
      "default": true
    },
    "multiShot": {
      "type": "boolean",
      "default": false,
      "description": "Multi-Shot Mode"
    },
    "shotType": {
      "type": "string",
      "enum": [
        "customize",
        "intelligence"
      ],
      "default": "customize",
      "description": "Shot Segmentation"
    },
    "multiPrompt": {
      "type": "object",
      "properties": {
        "index": {},
        "prompt": {},
        "duration": {}
      },
      "description": "Multi-Shot Prompts"
    },
    "voiceList": {
      "type": "object",
      "properties": {
        "voice_id": {}
      },
      "description": "Voice References"
    },
    "elementList": {
      "type": "object",
      "properties": {
        "element_id": {}
      },
      "description": "Element References"
    },
    "renderingSpeed": {
      "type": "string",
      "enum": [
        "std",
        "pro",
        "4k"
      ],
      "default": "4k"
    }
  },
  "additionalProperties": false
}
```

### Required parameters example

The required parameters plus the defaults that shape the output, as a REST body:

```json
{
  "params": {
    "model": "kling-v3",
    "params": {
      "prompt": "A serene mountain lake at golden hour, ultra detailed",
      "aspectRatio": "16:9",
      "duration": 5
    }
  }
}
```

### Response

The body is the gateway's status envelope: the output is at `response.result`, next to the task id, its status and the credits charged. Asset models return `url` plus an `items` array of results.

```json
{
  "status": "success",
  "response": {
    "id": "task_abc123",
    "status": "COMPLETED",
    "result": {
      "url": "https://cdn.picsart.com/…/result",
      "items": [
        {
          "url": "https://cdn.picsart.com/…/result"
        }
      ],
      "model": "kling-v3"
    }
  }
}
```

What `ai.generate()` / `ai.generateText()` resolve to (the envelope already unwrapped):

```json
{
  "items": [
    {
      "url": "https://cdn.picsart.com/…/result"
    }
  ],
  "model": "kling-v3"
}
```

### Usage examples

#### TypeScript (SDK)

```typescript
import { createClient } from '@picsart/ai-sdk';

const ai = createClient({
  apiKey: process.env.PICSART_API_KEY,
  apiUrl: 'https://api.picsart.com',
});

const result = await ai.generate('kling-v3', {
  prompt: "A serene mountain lake at golden hour, ultra detailed",
  aspectRatio: "16:9",
  duration: 5
});

console.log(result.url); // video URL
```

#### cURL (sync)

```bash
curl -X POST 'https://api.picsart.com/workflows/v1/models/execute' \
  -H 'Authorization: Bearer $PICSART_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "params": {
    "model": "kling-v3",
    "params": {
      "prompt": "A serene mountain lake at golden hour, ultra detailed",
      "aspectRatio": "16:9",
      "duration": 5
    }
  }
}'
```

#### cURL (async: submit, then poll)

```bash
# 1. Submit the job
curl -X POST 'https://api.picsart.com/workflows/v1/models/submit' \
  -H 'Authorization: Bearer $PICSART_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "params": {
    "model": "kling-v3",
    "params": {
      "prompt": "A serene mountain lake at golden hour, ultra detailed",
      "aspectRatio": "16:9",
      "duration": 5
    }
  }
}'
# → { "status": "success", "response": { "id": "task_abc123" } }

# 2. Poll until response.status is COMPLETED
curl 'https://api.picsart.com/workflows/v1/models/task_abc123/result' \
  -H 'Authorization: Bearer $PICSART_API_KEY'
```

#### CLI

```bash
gen-ai login  # once per machine
gen-ai models info kling-v3  # this model's parameters
gen-ai pricing kling-v3  # quote before spending credits
gen-ai generate -m kling-v3 \
  -p "A serene mountain lake at golden hour" \
  -d 5 \
  --ar 16:9
```

## Compatibility API (vendor parameters)

Alongside the unified API, the `kling-text-to-video` workflow takes Kling's own parameters exactly as the vendor defines them — nothing renamed or reshaped. It is the shortest path onto Picsart for request bodies already written against the vendor; the trade is that a request is written for one vendor, and the result comes back in the vendor's own shape. Same authentication.

- **Endpoint**: `POST https://api.picsart.com/workflows/kling-text-to-video/execute` (sync) · `POST …/submit` + `GET …/{taskId}/result` (async)
- **SDK**: `ai.apis.run('kling-text-to-video', params, { mode })` — params forwarded verbatim

### Vendor parameters

| Parameter | Type | Required | Default | Details |
| --- | --- | --- | --- | --- |
| `model_name` | `string` | no | `kling-v2-6` | Model name for video generation · Options: `kling-v2-5-turbo`, `kling-v2-6`, `kling-v3`, `kling-v3-turbo`, `kling-v4` |
| `prompt` | `string` | no | — | Prompt text for video generation (max 2500 characters; `kling-v4-flash` / `kling-v4`: English-only up to 26000, non-English-only up to 11000). Optional when multi_shot is enabled. |
| `negative_prompt` | `string` | no | — | Negative prompt text for video generation (max 2500 characters) |
| `cfg_scale` | `number` | no | `0.5` | Configuration scale factor (range 0-1) |
| `sound` | `string` | no | `off` | Generated sound simultaneously when generating videos · Options: `on`, `off` |
| `mode` | `string` | no | — | Mode for video generation. kling-v2-5-turbo only supports PRO mode. mode=4k is only supported by kling-v3. Other models does not support this parameter. · Options: `std`, `pro`, `4k` |
| `aspect_ratio` | `string` | no | `16:9` | Aspect ratio for the video. `21:9` is only supported by `kling-v4-flash` / `kling-v4`; `adaptive` is not supported here. · Options: `16:9`, `9:16`, `1:1`, `21:9`, `adaptive` |
| `resolution` | `string` | no | — | Output resolution of the generated video. Only supported by `kling-v3-turbo` / `kling-v4` (720p or 1080p) and `kling-v4-flash` (720p only); defaults to 720p when omitted. · Options: `720p`, `1080p` |
| `duration` | `string` | no | `5` | Duration of the video in seconds. v2 models: 5 or 10. v3 models: 3-15. kling-v4-flash: 3-20. kling-v4: 3-30. · Options: `5`, `10`, `3`, `4`, `6`, `7`, `8`, `9`, `11`, `12`, `13`, `14`, `15`, `16`, `17`, `18`, `19`, `20`, `21`, `22`, `23`, `24`, `25`, `26`, `27`, `28`, `29`, `30` |
| `multi_shot` | `boolean` | no | — | Enable multi-shot video generation (v3 only) |
| `shot_type` | `string` | no | — | Shot segmentation type for multi-shot generation · Options: `customize`, `intelligence` |
| `multi_prompt` | `MultiPromptItem[]` | no | — | List of prompts for each shot in multi-shot mode (max 6 items) |
| └ `index` | `number` | yes | — | Index of the shot (starting from 0) |
| └ `prompt` | `string` | yes | — | Prompt text for this shot (max 512 characters) |
| └ `duration` | `string` | yes | — | Duration of this shot in seconds |
| `voice_list` | `VoiceItem[]` | no | — | Voice references for video generation (max 2 items, requires sound=on) |
| └ `voice_id` | `string` | yes | — | Voice ID reference |
| `options` | `object` | no | — | Options controlling safety checks and drive integration |
| └ `safety_checks` | `object` | no | — | Safety check settings |
| └   `enabled` | `boolean` | no | — | Whether to run content moderation. Defaults to true. |
| └ `drive` | `object` | no | — | Save result to Picsart Drive |
| └   `name` | `string` | yes | — | File name in Picsart Drive |
| └   `attributes` | `object` | no | — | Custom attributes to attach to the file |
| └   `folder` | `object` | no | — | Target folder in Picsart Drive |
| └ `inputs_transformation` | `object` | no | — | Input transformation settings |
| └   `downscale_oversized_images` | `boolean` | no | — | Whether to downscale oversized input images. Defaults to false. |

### Example request body

```json
{
  "params": {
    "prompt": "A serene mountain lake at golden hour, ultra detailed"
  }
}
```

### Usage examples

#### TypeScript (`ai.apis.run`)

```typescript
import { createClient, ApiRunMode } from '@picsart/ai-sdk';

const ai = createClient({
  apiKey: process.env.PICSART_API_KEY,
  apiUrl: 'https://api.picsart.com',
});

// Calls the 'kling-text-to-video' workflow directly — params are sent as-is.
const { result, usage } = await ai.apis.run('kling-text-to-video', {
  prompt: "A serene mountain lake at golden hour, ultra detailed"
}, {
  mode: ApiRunMode.SYNC,
});

console.log(result); // workflow-specific output
console.log(usage?.credits); // amount charged, in $
```

#### cURL (sync)

```bash
curl -X POST 'https://api.picsart.com/workflows/kling-text-to-video/execute' \
  -H 'Authorization: Bearer $PICSART_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "params": {
    "prompt": "A serene mountain lake at golden hour, ultra detailed"
  }
}'
```

#### cURL (async: submit, then poll)

```bash
# 1. Submit the job
curl -X POST 'https://api.picsart.com/workflows/kling-text-to-video/submit' \
  -H 'Authorization: Bearer $PICSART_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "params": {
    "prompt": "A serene mountain lake at golden hour, ultra detailed"
  }
}'
# → { "status": "success", "response": { "id": "wf_abc123" } }

# 2. Poll until response.status is COMPLETED
curl 'https://api.picsart.com/workflows/kling-text-to-video/wf_abc123/result' \
  -H 'Authorization: Bearer $PICSART_API_KEY'
```

### Response

Over HTTP the vendor-shaped result arrives inside the gateway envelope at `response.result`:

```json
{
  "status": "success",
  "response": {
    "result": {
      "url": "https://cdn.picsart.com/…/result.mp4",
      "duration": "…",
      "mimeType": "video/mp4",
      "driveFile": {
        "id": "wf_abc123"
      }
    }
  }
}
```

`ai.apis.run()` unwraps that envelope and resolves to `{ result, usage }`:

```json
{
  "result": {
    "url": "https://cdn.picsart.com/…/result.mp4",
    "duration": "…",
    "mimeType": "video/mp4",
    "driveFile": {
      "id": "wf_abc123"
    }
  }
}
```

## Additional resources

- Model page: https://picsart.com/api-platform/models/kling-v3
- Try it: https://picsart.com/api-platform/models/kling-v3/playground
- SDK: https://picsart.com/api-platform/models/kling-v3/sdk
- REST API (unified): https://picsart.com/api-platform/models/kling-v3/api
- Compatibility API (vendor parameters): https://picsart.com/api-platform/models/kling-v3/advanced
- Pricing: https://picsart.com/api-platform/models/kling-v3/pricing
- This document: https://picsart.com/api-platform/models/kling-v3/llms.txt
- All models: https://picsart.com/api-platform/models
- Docs — quickstart https://picsart.com/api-platform/docs/quickstart, authentication https://picsart.com/api-platform/docs/authentication, SDK https://picsart.com/api-platform/docs/sdk, REST https://picsart.com/api-platform/docs/api-reference, CLI https://picsart.com/api-platform/docs/cli, MCP https://picsart.com/api-platform/docs/mcp
- CLI reference: https://picsart.github.io/picsart-mcp-cli-docs/guide/introduction