imagesarray
Up to 10 reference images, referenced as @Image1, @Image2, ...
Kling V4 Reference to Video
kwaivgi/kling-video/v4/reference-to-videoKling V4 Reference to Video by Kuaishou generates a 3-30 second video that keeps characters, objects and motion from reference images and videos.
Try the model
Playground
Input
Text prompt. Refer to references as @Image1, @Video1, ...
Additional Settings More
Customize your input with more control.
PNG, JPEG, WebP, or GIF · 20 MiB maximum each · up to 10
Up to 10 reference images, referenced as @Image1, @Image2, ...
Up to 5 reference videos (3-30s each, 30s combined), referenced as @Video1, ... Video references switch to the input-plus-output price.
Up to 2 custom voice IDs so characters speak in that voice. Create one by uploading a 5-30s voice recording at https://www.sandbase.ai/model/kwaivgi/kling-video/create-voice (Kling Create Voice). Cannot be combined with reference videos.
Output frame shape. Leave empty to follow the references (adaptive). Allowed values: 21:9, 16:9, 9:16, 1:1.
Output resolution. Allowed values: 720p, 1080p.
330
Output length in seconds (3-30). Range: 3 to 30.
ResultExample
What would you like to do next?
Examples
Select an example to load its inputs and result into the playground.
- Open result ↗
Input
{ "aspect_ratio": "16:9", "images": [ "https://static.sandbase.ai/examples/d5022210-6b33-4763-915b-1bf6b20f4f81/input/454d9f12-340e-487a-8f25-e83ddd48a57b.png" ], "prompt": "The rabbit from @Image1 sits at a wooden table in a cozy cafe, sipping tea from a tiny cup. Warm afternoon light." } - Open result ↗
Input
{ "aspect_ratio": "16:9", "images": [ "https://static.sandbase.ai/examples/142b1021-7119-4f94-86c5-b7bba08fb8aa/input/60d4b6f5-2b0a-4718-a948-f25624d8589b.png" ], "prompt": "The tiger from @Image1 walks through a snowy pine forest at dusk, snowflakes falling, low-angle tracking shot." }
Kling V4 Reference to Video
Kling V4 reference-to-video keeps characters, objects and motion from reference images and videos in a new 3–30 second clip.
Fields
| Field | Type | Default | Notes |
|---|---|---|---|
prompt | string, required | — | Refer to inputs as @Image1, @Video1, … |
images | image URL[] | — | Up to 10 reference images. |
videos | video URL[] | — | Up to 5 reference videos, 3–30s each, 30s combined. |
voice_ids | string[] | — | Up to 2 custom voice IDs. Create one at Kling Create Voice. Not combinable with videos. |
aspect_ratio | 21:9 / 16:9 / 9:16 / 1:1 | — | Leave empty to follow the references. |
resolution | 720p / 1080p | 1080p | Output resolution. |
duration | 3–30 | 5 | Output length in seconds. |
Billing
Without reference videos: $0.157 per output second at 720p, $0.235 at 1080p. With reference videos: $0.094 (720p) or $0.141 (1080p) per second of output plus input, where the input side counts at least as long as the output. The quote before submission assumes 30 seconds of reference video when the length cannot be read.
| Request | Price |
|---|---|
| 5s, 1080p, images only (default) | $1.175 |
| 5s, 720p, images only | $0.785 |
| 5s, 1080p, 8s reference video | $1.833 |
| 10s, 720p, 4s reference video | $1.88 |
| Failed runs are not charged. |
Prompting
- Name each reference in the prompt, e.g. "@Image1 walks into the scene from @Video1".
- To make a character speak in a cloned voice, upload a 5–30 second recording at Kling Create Voice to get a
voice_id, pass its ID invoice_ids, and write the line in the prompt, e.g. "The man from @Image1 says: "Welcome back."". Every clip has a soundtrack; withoutvoice_idsthe voice is chosen by the model.
Limits
- Clips are 3–30 seconds; reference videos 3–30 seconds.
Also on SandBase
Other Kling V4 endpoints: kwaivgi/kling-video/v4/text-to-video, kwaivgi/kling-video/v4/image-to-video, kwaivgi/kling-video/v4/reference-to-video, kwaivgi/kling-video/v4/video-edit.
Start building
Send your first request
Submit this model through the SandBase Unified Run API.
# The quoted heredoc keeps Unicode and shell metacharacters unchanged.
result=$(curl --fail-with-body --silent \
-X POST "https://api.sandbase.ai/v1/run" \
-H "Authorization: Bearer $SANDBASE_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @- <<'SANDBASE_JSON'
{
"model": "kwaivgi/kling-video/v4/reference-to-video",
"prompt": "@Element1 and @Element2 are having dinner at the table in @Image1",
"duration": 5,
"resolution": "1080p"
}
SANDBASE_JSON
)
run_id=$(printf '%s' "$result" | jq -r .id)
for attempt in $(seq 1 120); do
status=$(printf '%s' "$result" | jq -r .status)
case "$status" in completed|failed|timeout) break ;; esac
sleep 2
result=$(curl --fail-with-body --silent \
-H "Authorization: Bearer $SANDBASE_API_KEY" \
"https://api.sandbase.ai/v1/run/$run_id")
done
status=$(printf '%s' "$result" | jq -r .status)
[ "$status" = completed ] || { echo "Generation ended: $status" >&2; exit 1; }
printf '%s\n' "$result"2. Authentication
Create a SandBase API key and set it in your server environment. All requests use Bearer authentication.
export SANDBASE_API_KEY="YOUR_API_KEY"Keep the key on your server. Do not expose it in browser code or commit it to a repository.
3. Queue
Submit a request
POST to /v1/run with this model ID and its inputs. The request example above includes submission and polling.
Fetch request status and result
Use the returned run ID to poll until the status is completed, failed or timeout. Read output only after completed.
curl "https://api.sandbase.ai/v1/run/$RUN_ID" \
-H "Authorization: Bearer $SANDBASE_API_KEY"4. Files
Hosted files
Pass a publicly accessible file URL in the model’s image, video or audio field. Supported formats and limits are shown beside each Playground input.
Uploading images
Use the upload or replace control on supported image fields in the Playground. Video URL fields accept a hosted driving video; they do not imply video-upload support.
5. Schema
Input
promptstringrequired
Text prompt. Refer to references as @Image1, @Video1, ...
videosarray
Up to 5 reference videos (3-30s each, 30s combined), referenced as @Video1, ... Video references switch to the input-plus-output price.
durationinteger
Output length in seconds (3-30).
Default: 5
Minimum: 3
Maximum: 30
voice_idsarray
Up to 2 custom voice IDs so characters speak in that voice. Create one by uploading a 5-30s voice recording at https://www.sandbase.ai/model/kwaivgi/kling-video/create-voice (Kling Create Voice). Cannot be combined with reference videos.
resolutionstring
Output resolution.
Default: "1080p"
Possible values: "720p", "1080p"
aspect_ratiostring
Output frame shape. Leave empty to follow the references (adaptive).
Possible values: "21:9", "16:9", "9:16", "1:1"
{
"model": "kwaivgi/kling-video/v4/reference-to-video",
"prompt": "@Element1 and @Element2 are having dinner at the table in @Image1",
"duration": 5,
"resolution": "1080p"
}Output
A completed run exposes its result in output. The following is the model’s saved example, not a new generation.
[
{
"url": "https://static.sandbase.ai/examples/d5022210-6b33-4763-915b-1bf6b20f4f81/output/83773596-daa8-443e-80b4-6a9e2284718b.mp4"
}
]