Kwaivgi Kling V2.1 I2V Pro API Documentation

Kwaivgi Kling V2.1 I2V Pro API Documentation

Playground

Kling 2.1 Pro converts images to professional cinematic videos with enhanced fidelity, precise camera moves and dynamic motion control. Ready-to-use REST inference API, top performance, no coldstarts, affordable pricing.

Features

Kling v2.1 I2V Pro turns a single reference image into a short, cinematic video clip guided by your prompt. Upload an image, describe the motion (subject + camera + environment), and the model animates the scene while keeping the input image as the visual anchor. Built for stable production use with a ready-to-use REST API, no cold starts, and predictable pricing.

Key capabilities

• Image-to-video generation anchored to your input image
• Prompt-controlled motion: facial micro-expressions, hair/clothing movement, environment effects
• Cinematic camera moves: push-in, orbit, pan, tilt, handheld feel
• Supports negative_prompt to reduce artifacts and unwanted styles

Pricing

Inputs

• image (required): the reference image used as the visual anchor
• prompt (required): describe what moves and how the camera behaves
• negative_prompt (optional): describe what to avoid (blur, distortions, artifacts)

Parameters

• prompt: motion + scene direction for the clip
• negative_prompt: optional “avoid list”
• image: input image (upload or URL)
• guidance_scale: how strongly motion follows your prompt (lower = more natural, higher = more literal)
• duration: video length in seconds

Prompting guide (I2V)

Write prompts like a director’s brief, focusing on motion:

• Subject motion: expression change, breathing, walking, turning, hair swaying
• Environment motion: wind, rain, fog, particles, light rays
• Camera motion: slow push-in, orbit, dolly, handheld micro-shake
• Continuity: keep identity, outfit, and scene layout consistent with the input image

Example prompts

• A cinematic close-up of a woman laughing on a sunny city street. Her hair sways in the wind, coat fabric subtly moves, warm natural light, shallow depth of field, camera slow push-in, smooth motion, 5 seconds.
• Portrait in golden hour. Gentle breeze, subtle facial motion, soft lens flare, handheld micro-sway, realistic skin texture, 5 seconds.
• Moody night street scene. Light rain, drifting mist, neon reflections, camera slow orbit around the subject, 5 seconds.

Negative prompt examples

• blur, distort, low quality
• jitter, warping, melted details, extra limbs
• watermark, logo, subtitles, text artifacts

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

REQUEST_BODY=$(cat <<'JSON'
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
  "guidance_scale": 0.5,
  "duration": 5
}
JSON
)

# 1. Submit the prediction once. Never retry this request automatically:
# a retry after an unclear failure can create a second, billed task.
CHECK='The task may already exist. Check History or the predictions list before submitting again.'
if ! SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --connect-timeout 10 --max-time 60 \
  -X POST "https://api.wavespeed.ai/api/v3/kwaivgi/kling-v2.1-i2v-pro" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}"); then
  printf 'Submit failed. %s\n' "${CHECK}" >&2
  exit 1
fi

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id. %s\n' "${CHECK}" >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction reaches a final status.
BODY_FILE=$(mktemp)
trap 'rm -f "${BODY_FILE}"' EXIT
while true; do
  # Transient errors (429, 5xx) are retried, honoring Retry-After.
  HTTP_CODE=$(curl --silent --show-error --fail-with-body \
    --connect-timeout 10 --max-time 60 --retry 5 --retry-delay 2 \
    --output "${BODY_FILE}" --write-out '%{http_code}' \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}" || true)
  case "${HTTP_CODE}" in
    2??) ;;
    000|429|5??)  # dropped connection or temporary error: keep polling
      printf 'Task %s: HTTP %s, polling again in 10s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      sleep 10; continue ;;
    *) printf 'Task %s: HTTP %s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      cat "${BODY_FILE}" >&2; exit 1 ;;
  esac
  RESULT=$(jq 'if type == "object" and has("data") then .data else . end' "${BODY_FILE}")
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted)
      printf 'Task %s ended with status %s\n' "${PREDICTION_ID}" "${STATUS}" >&2
      printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Every model also accepts the global request options enable_sync_mode and enable_base64_output; see their pages for details.

Response Parameters

Result Request Parameters

Result Response Parameters