Kwaivgi Kling V4.0 Video Edit API Documentation

Kwaivgi Kling V4.0 Video Edit API Documentation

Playground

Kling V4.0 Video Edit rewrites a 3 to 30 second video from a text instruction: it keeps the scene, subject and motion and changes what you describe, with optional reference images and audios, 720p and 1080p output and new synchronized audio generated by default (the original sound can be kept instead). Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Kling V4.0 Video Edit transforms an existing video using natural-language instructions. Change a character, environment, weather, visual style, or other scene elements while using the source footage as the foundation for motion and composition.

Generate edited videos from 3 to 30 seconds at 720p or 1080p, with optional reference images, reference audios, and audio control.

Why Choose This?

• Instruction-based video editing — Describe what you want to change using natural language.
• Source-guided motion — Preserve the overall action and motion of the original footage while transforming selected elements.
• Reference image support — Add up to 10 images to guide characters, objects, clothing, or visual style.
• Reference audio support — Add up to 3 audios to guide the voice and sound of the edited video.
• 720p and 1080p output — Choose the resolution that fits your workflow.
• Original audio support — Generate new synchronized audio, or keep the source soundtrack.
• Flexible output — Adjust duration and aspect ratio when needed.

Parameters

How to Use

1. Upload a video — Provide the footage you want to edit.
2. Describe the change — Explain what should be replaced, transformed, or restyled.
3. Add reference images or audios optional — Use references when a specific character, object, outfit, style, voice, or sound is needed.
4. Choose output settings — Set resolution, duration, or aspect ratio if needed.
5. Configure audio — Generate new synchronized audio, or keep the original soundtrack.
6. Submit — Generate and retrieve the edited video.

Pricing

Charged based on the requested duration and source video length.

Billed seconds = requested duration + the longer of the requested and source durations.

Source duration is rounded up to whole seconds, capped at 30 seconds, and used when duration is omitted.

Reference images, reference audios, aspect ratio, and audio settings add no extra charge.

Best Use Cases

• Character replacement — Replace a person or character while keeping the original scene and motion.
• Environment changes — Move existing action into a different location or setting.
• Weather and atmosphere edits — Change lighting, weather, season, or overall mood.
• Style transformation — Restyle footage while retaining its underlying movement.
• Product and clothing replacement — Introduce specific objects, products, or outfits using reference images.
• Creative video variations — Produce alternate versions of existing footage without rebuilding the scene from scratch.

Pro Tips

• Describe the changes clearly instead of rewriting the entire source scene.
• Mention important elements that should remain consistent when necessary.
• Refer to the source video as @Video1.
• Refer to reference images as @Image1, @Image2, and so on according to their order.
• Refer to reference audios as @Audio1, @Audio2, and so on according to their order.
• Explain what each reference image or audio should contribute to the edit.
• Use clear footage with visible subjects for more predictable transformations.

Notes

• video and prompt are required.
• Source videos support up to 30 seconds.
• Up to 10 reference images and up to 3 reference audios can be supplied.
• resolution defaults to 720p.
• keep_original_sound defaults to false: the soundtrack is generated with the edit, so describe the sound you want in the prompt. Set it to true to keep the source audio exactly.
• When duration is omitted, the output follows the source video duration.
• When aspect_ratio is omitted, the output follows the source video’s framing.
• Reference audios guide a speaker’s voice; they do not reproduce the original recording, music, or timing.
• Reference voices shape the newly generated audio. Set keep_original_sound to true to keep the source video’s original audio instead.

Related Models

• Kling V4.0 Text-to-Video — Generate videos directly from text prompts with Kling V4.0.
• Kling V4.0 Image-to-Video — Animate a reference image into a video with Kling V4.0.

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",
  "video": "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4",
  "keep_original_sound": false,
  "resolution": "720p",
  "duration": 3,
  "aspect_ratio": "16:9"
}
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-v4.0/video-edit" \
  -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