Kwaivgi Kling Video O3 4k Video Reference API Documentation

Kwaivgi Kling Video O3 4k Video Reference API Documentation

Playground

Kling O3 Omni 4K Video Reference generates 4K AI videos guided by an input video, text prompt, and optional reference images, supporting video-to-video creation with visual reference guidance, motion consistency, camera control, and high-quality cinematic output. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Kling O3 Omni 4K Video Reference generates a new 4K video using an input video as a motion, appearance, or scene reference. Provide a reference video and a text prompt, then optionally add image references or element IDs for stronger visual guidance.

Why Choose This?

• Video-reference generation
  Use an input video as a reference for motion, appearance, subject behavior, or scene guidance.

• 4K video output
  Generate high-resolution 4K video for higher-quality delivery workflows.

• Prompt-guided control
  Describe the new scene, subject behavior, camera movement, and visual treatment with text instructions.

• Image reference support
  Add optional image references when extra subject, object, or style guidance is needed.

• Element reference support
  Use element_list to reference reusable Kling elements by element_id.

• Original sound preservation
  Keep the original audio from the reference video with keep_original_sound.

Parameters

How to Use

1. Write your prompt — Describe the target scene, subject behavior, camera movement, motion, and visual style.
2. Upload a reference video — Provide the video used for motion, appearance, or scene guidance.
3. Add image references optional — Use images when extra subject, object, or style reference is needed.
4. Add element references optional — Use element_list when you want to guide generation with existing Kling element IDs.
5. Choose aspect ratio — Select 16:9, 9:16, or 1:1.
6. Set duration — Choose a generated video duration from 3 to 15 seconds.
7. Configure sound optional — Keep keep_original_sound enabled when the reference video’s audio should be preserved.
8. Submit — Generate the final 4K video-reference output.

Pricing

Pricing is based on generated video duration.

Example Costs

Best Use Cases

• Motion reference generation — Use a video to guide movement, pacing, gestures, or camera behavior.
• Character and action reference — Preserve useful action cues while generating a new scene from the prompt.
• Element-guided videos — Use existing Kling element IDs for stronger subject or object guidance.
• Product and commercial clips — Create high-resolution video variations guided by existing footage and references.
• Style and scene reference — Use reference video and images to guide visual traits, shot structure, or scene context.
• 4K creative delivery — Generate higher-resolution outputs for polished social, marketing, or presentation use.

Pro Tips

• Use a clear reference video with the motion, appearance, or scene cues you want to preserve.
• Keep the prompt focused on the new scene and how the reference video should guide it.
• Use image references when subject, object, or style consistency matters.
• Use element_list when you already have reusable Kling element IDs.
• Keep element_list focused; too many unrelated elements can reduce control.
• Enable keep_original_sound only when the input video’s audio should be carried into the result.
• Choose 9:16 for vertical content, 16:9 for widescreen output, and 1:1 for square formats.

Notes

• prompt and video are required.
• images supports up to 4 reference images.
• element_list supports up to 3 element references.
• Each element_list item must include an element_id.
• element_id should come from kwaivgi/kling-elements or kwaivgi/kling-elements-advanced.
• duration must be between 3 and 15 seconds.
• keep_original_sound defaults to true.

Related Models

Related Models

• Kling O3 Omni 4K Video Reference — Generate 4K videos using an input video as a reference.
• Kling O3 Omni 4K Video Edit — Edit an existing 4K video with prompt instructions.
• Kling Elements Advanced — Generate reusable Kling elements that can be used as element_id references.

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": true,
  "aspect_ratio": "16:9",
  "duration": 5
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/kwaivgi/kling-video-o3-4k/video-reference" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}")

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
' >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction finishes.
while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}")
  RESULT=$(printf '%s' "${RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

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

Parameters

Task Submission Parameters

Request Parameters

Response Parameters

Result Request Parameters

Result Response Parameters