# Kling Video Effects

> Apply curated Kling visual effects to photos — single or dual-image scenes.

## Overview

- **Model ID**: `kling-video-effects`
- **Workflow**: `kling/v1/video-effects`
- **Provider**: Kling
- **Category**: Image → Video (video)
- **Output**: A video URL.
- **Tags**: new, image input, video effects
- **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/v1/video-effects/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-video-effects

## 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`.

| Rate |
| --- |
| $0.21 / generation |

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-video-effects', …)` 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

- **`templateId`** (`string`, _optional_): Effect
  - An id from the `kling/v1/catalog/templates` catalog, fetched at runtime via `ai.catalogs`
  - Default: `korean_baseball`
- **`imageUrls`** (`list<string>`, _required_): Effect Images
  - Accepts: image URLs (max 2)

### 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": [
    "imageUrls"
  ],
  "properties": {
    "templateId": {
      "type": "string",
      "description": "Effect — an id from the `kling/v1/catalog/templates` catalog",
      "default": "korean_baseball"
    },
    "imageUrls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri",
        "description": "image URL"
      },
      "maxItems": 2,
      "description": "Effect Images"
    }
  },
  "additionalProperties": false
}
```

### Required parameters example

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

```json
{
  "params": {
    "model": "kling-video-effects",
    "params": {
      "imageUrls": [
        "https://cdn.example.com/input.jpg"
      ]
    }
  }
}
```

### 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-video-effects"
    }
  }
}
```

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

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

### 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-video-effects', {
  imageUrls: [
    "https://cdn.example.com/input.jpg"
  ]
});

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-video-effects",
    "params": {
      "imageUrls": [
        "https://cdn.example.com/input.jpg"
      ]
    }
  }
}'
```

#### 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-video-effects",
    "params": {
      "imageUrls": [
        "https://cdn.example.com/input.jpg"
      ]
    }
  }
}'
# → { "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-video-effects  # this model's parameters
gen-ai pricing kling-video-effects  # quote before spending credits
gen-ai generate -m kling-video-effects \
  -i ./input.jpg
```

## Compatibility API (vendor parameters)

Alongside the unified API, the `kling/v1/video-effects` 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/v1/video-effects/execute` (sync) · `POST …/submit` + `GET …/{taskId}/result` (async)
- **SDK**: `ai.apis.run('kling/v1/video-effects', params, { mode })` — params forwarded verbatim

### Vendor parameters

| Parameter | Type | Required | Default | Details |
| --- | --- | --- | --- | --- |
| `image` | `string` | no | — | Image URL for single-image effects. Required when effect_scene is not one of the dual-image scenes (see dualImageEffectScenes). · uri |
| `images` | `string[]` | no | — | Array of exactly 2 image URLs for dual-image effects. Required when effect_scene is one of the dual-image scenes (see dualImageEffectScenes). |
| `effect_scene` | `string` | yes | — | The video effect to apply · Options: `korean_baseball`, `pet_skateboard`, `daily_ootd`, `tiny_beast_printer`, `landmark_reveal`, `winter_charm`, `flash_ride`, `maestro_of_magic`, `magic_carpet_ride`, `good_luck_spirit`, `shooting_star`, `sparkler_wand`, `sovereign_scepter`, `dirt_rush`, `return_of_the_king`, `dance_with_dragon`, `minimalist_light`, `martial_meow`, `sassy_shake`, `knock_at_a_door_revenge`, `palm_sized_figure_pro`, `prank_box`, `perler_beads`, `spring_bloom`, `toss_run`, `switch_to_silk`, `get_rich_quick`, `make_it_rain`, `twist_shake`, `the_hip_sway`, `send_my_love`, `funky_martian`, `wealth_drive`, `the_high_kick`, `the_exercise`, `lucky_veggie`, `studio_look`, `flash_drive`, `shush_my_dreams`, `french_elegance`, `finger_swipe`, `advent_of_flora`, `smooth_transition`, `kiss_pro`, `raid_check`, `snow_night_kiss`, `eternal_kiss`, `fortune_in_motion`, `chinese_trend`, `sedan_chair_dance`, `skyfall`, `good_luck_dance`, `laicai_dance`, `yangge_dance`, `color_mixing`, `lantern_festival_cuju`, `unique_firework`, `unique_spring_couplets`, `horse_mask`, `fortune_knocks_cartoon`, `tangyuan_to_animal`, `hot_feet_dance`, `swag_dance`, `pigeon_dance`, `bloodline_dance`, `chanel_dance`, `cute_dance`, `love_theme_song`, `pumpitup_dance`, `city_to_village`, `fortune_god_transform`, `new_year_feast`, `ring_in_new`, `horse_year_firework`, `crystal_horse`, `drunk_dance`, `drunk_dance_pet`, `daoma_dance`, `bouncy_dance`, `smooth_sailing_dance`, `new_year_greeting`, `lion_dance`, `prosperity`, `great_success`, `golden_horse_fortune`, `red_packet_box`, `lucky_horse_year`, `lucky_red_packet`, `lucky_money_come`, `lion_dance_pet`, `dumpling_making_pet`, `fish_making_pet`, `pet_red_packet`, `lantern_glow`, `expression_challenge`, `overdrive`, `heart_gesture_dance`, `poping`, `martial_arts`, `running`, `nezha`, `motorcycle_dance`, `subject_3_dance`, `ghost_step_dance`, `phantom_jewel`, `zoom_out`, `cheers_2026`, `fight_pro`, `hug_pro`, `heart_gesture_pro`, `dollar_rain_pro`, `pet_bee_pro`, `countdown_teleport`, `santa_random_surprise`, `magic_match_tree`, `bullet_time_360`, `happy_birthday`, `birthday_star`, `thumbs_up_pro`, `tiger_hug_pro`, `pet_lion_pro`, `surprise_bouquet`, `bouquet_drop`, `firework_2026`, `glamour_photo_shoot`, `box_of_joy`, `first_toast_of_the_year`, `my_santa_pic`, `santa_gift`, `steampunk_christmas`, `snowglobe`, `christmas_photo_shoot`, `ornament_crash`, `santa_express`, `instant_christmas`, `coronation_of_frost`, `building_sweater`, `spark_in_the_snow`, `scarlet_and_snow`, `bullet_time_lite`, `jumping_ginger_joy`, `pure_white_wings`, `black_wings`, `golden_wing`, `pink_pink_wings`, `venomous_spider`, `luminous_elf`, `woodland_elf`, `swish_swish`, `snowboarding`, `witch_transform`, `vampire_transform`, `pumpkin_head_transform`, `demon_transform`, `mummy_transform`, `zombie_transform`, `cute_pumpkin_transform`, `halloween_escape`, `tennis_trend`, `football_live`, `f1_live`, `whirling_beverage`, `spielberg_transition` |
| `options` | `object` | no | — | Options controlling 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": {
    "effect_scene": "korean_baseball"
  }
}
```

### 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/v1/video-effects' workflow directly — params are sent as-is.
const { result, usage } = await ai.apis.run('kling/v1/video-effects', {
  effect_scene: "korean_baseball"
}, {
  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/v1/video-effects/execute' \
  -H 'Authorization: Bearer $PICSART_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "params": {
    "effect_scene": "korean_baseball"
  }
}'
```

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

```bash
# 1. Submit the job
curl -X POST 'https://api.picsart.com/workflows/kling/v1/video-effects/submit' \
  -H 'Authorization: Bearer $PICSART_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "params": {
    "effect_scene": "korean_baseball"
  }
}'
# → { "status": "success", "response": { "id": "wf_abc123" } }

# 2. Poll until response.status is COMPLETED
curl 'https://api.picsart.com/workflows/kling/v1/video-effects/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-video-effects
- Try it: https://picsart.com/api-platform/models/kling-video-effects/playground
- SDK: https://picsart.com/api-platform/models/kling-video-effects/sdk
- REST API (unified): https://picsart.com/api-platform/models/kling-video-effects/api
- Compatibility API (vendor parameters): https://picsart.com/api-platform/models/kling-video-effects/advanced
- Pricing: https://picsart.com/api-platform/models/kling-video-effects/pricing
- This document: https://picsart.com/api-platform/models/kling-video-effects/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