# kwaivgi/kling-effects

> Kling Effects is a fast AI image-to-video effects model that creates 5-second videos from a single image in styles ranging from futuristic to realistic for social media, product demos, and creative visual content. Ready-to-use REST inference API for image animation, visual effects, product showcases, advertising creatives, social media clips, and professional image-to-video workflows with simple integration, no coldstarts, and affordable pricing.

## Overview

- **Endpoint**: `https://api.wavespeed.ai/api/v3/kwaivgi/kling-effects`
- **Polling/result URL**: `https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result`
- **Model ID**: `kwaivgi/kling-effects`
- **Category**: video-effects

## API Information

This model can be used via our HTTP API or more conveniently via our client libraries.
The API is asynchronous: submit a prediction, then poll its result URL until it completes.

### Input Schema

The API accepts the following input parameters:

- **`image`** (`string`, _required_):
  Image URL or Base64 encoding, in the format of data:image/png;base64,... 

- **`effect_scene`** (`string`, _required_):
  Effect scene. Select one of the curated official Kling video effect templates.
  - Options: "glamour_photo_shoot", "box_of_joy", "first_toast_of_the_year", "my_santa_pic", "santa_gift", "steampunk_christmas", "snowglobe", "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", "throne_of_king", "luminous_elf", "woodland_elf", "guardian_spirit", "swish_swish", "snowboarding", "witch_transform", "vampire_transform", "pumpkin_head_transform", "demon_transform", "mummy_transform", "zombie_transform", "cute_pumpkin_transform", "halloween_escape", "running_man", "3d_cartoon_2", "surfsurf", "skateskate", "pet_dance", "pet_moto_rider", "swing_swing", "day_to_night", "palm_sized_figure_pro", "korean_baseball", "f1_live", "football_live", "tennis_trend", "red_card_sent_off", "air_dunk", "martial_meow", "magic_world_vlog", "spielberg_transition", "landmark_reveal", "bullet_time_360", "flash_ride", "magic_carpet_ride", "return_of_the_king", "dance_with_dragon", "bloodline_dance", "sassy_shake", "twist_shake", "get_rich_quick", "make_it_rain", "skyfall", "surprise_bouquet", "happy_birthday"



**Required Parameters Example**:

```json
{
  "image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
  "effect_scene": "glamour_photo_shoot"
}
```

**Full Example**:

```json
{
  "image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
  "effect_scene": "glamour_photo_shoot"
}
```

### Result Data Schema

The `data` object returned by the API has the following fields:

- **`created_at`** (`string (date-time)`, _optional_):
  ISO timestamp of when the request was created (e.g., "2023-04-01T12:34:56.789Z").

- **`id`** (`string`, _optional_):
  Unique identifier for the prediction, the ID of the prediction to get.

- **`model`** (`string`, _optional_):
  Model ID used for the prediction.

- **`outputs`** (`array of string | object`, _optional_):
  Array of generated outputs (empty when status is not completed). Items are usually URL strings, but may be text strings or structured result objects, depending on the model.

- **`status`** (`string`, _optional_):
  Status of the task: created, processing, completed, or failed.

- **`urls`** (`object`, _optional_):
  Object containing related API endpoints.



**Example `data` Object**:

```json
{
  "created_at": "example",
  "id": "example",
  "model": "example",
  "outputs": [],
  "status": "example",
  "urls": {}
}
```

## Usage Examples

The examples use `jq` to read JSON. Set your API key first:

```bash
set -euo pipefail
export WAVESPEED_API_KEY="your-api-key"
```

### 1. Submit a prediction

```bash
REQUEST_BODY=$(cat <<'JSON'
{
  "image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
  "effect_scene": "glamour_photo_shoot"
}
JSON
)

SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url https://api.wavespeed.ai/api/v3/kwaivgi/kling-effects \
  --header "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  --header "Content-Type: application/json" \
  --data "${REQUEST_BODY}")

printf '%s\n' "${SUBMIT_RESPONSE}" | jq .
```

The response contains the prediction ID in `data.id`.

### 2. Poll until complete and read `outputs`

```bash
PREDICTION_ID=$(printf '%s' "${SUBMIT_RESPONSE}" | jq -r '.data.id')
if [ -z "${PREDICTION_ID}" ] || [ "${PREDICTION_ID}" = "null" ]; then
  printf 'Submission response did not contain data.id\n' >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    --request GET \
    --url "${RESULT_URL}" \
    --header "Authorization: Bearer ${WAVESPEED_API_KEY}")

  RESULT=$(printf '%s' "${RESPONSE}" | jq -e '.data')
  STATUS=$(printf '%s' "${RESULT}" | jq -er '.status')
  case "${STATUS}" in
    completed)
      # Generated files are returned in the outputs array.
      printf '%s\n' "${RESULT}" | jq '.outputs'
      break
      ;;
    failed|cancelled|timeout|deleted)
      printf '%s\n' "${RESULT}" | jq '{status, error, code}'
      exit 1
      ;;
    *)
      sleep 2
      ;;
  esac
done
```

## Additional Resources

### Documentation

- [Model Playground](https://wavespeed.ai/models/kwaivgi/kling-effects)
- [API Documentation](https://wavespeed.ai/docs/docs-api/kwaivgi/kwaivgi-kling-effects)