Kling 4.0 Reference to Video

curl --request POST \
  --url https://api.vidgo.ai/api/generate/submit \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "kwaivgi/kling-v4.0/reference-to-video",
  "input": {
    "reference_image_urls": [
      "https://example.com/character.png",
      "https://example.com/cafe.png"
    ],
    "prompt": "@Image1 sits at a window table in the cafe from @Image2, sips coffee and waves at the camera, warm afternoon light",
    "duration": 8,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }
}
'

{
  "code": 200,
  "data": {
    "task_id": "task-unified-1762160000-abc123",
    "status": "not_started",
    "created_time": "2026-11-03T10:30:00"
  }
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

Request timeout

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

POST

api

generate

submit

curl --request POST \
  --url https://api.vidgo.ai/api/generate/submit \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "kwaivgi/kling-v4.0/reference-to-video",
  "input": {
    "reference_image_urls": [
      "https://example.com/character.png",
      "https://example.com/cafe.png"
    ],
    "prompt": "@Image1 sits at a window table in the cafe from @Image2, sips coffee and waves at the camera, warm afternoon light",
    "duration": 8,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }
}
'

{
  "code": 200,
  "data": {
    "task_id": "task-unified-1762160000-abc123",
    "status": "not_started",
    "created_time": "2026-11-03T10:30:00"
  }
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

Request timeout

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

After submission, a task_id will be returned. If you provided a callback_url, when the task status becomes finished or failed, a POST request will be sent to the callback_url.
Regardless of whether callback_url is provided, you can retrieve the result through the unified Query Task Status endpoint.

Kling 4.0 Reference to Video generates a 3–30 second video guided by reference images, reference videos and reusable subjects (elements), so characters, products and settings stay consistent. Cite each reference in the prompt by its position, such as @Image1, @Video1 or @Element1. Kling 4.0 is Kuaishou’s Kling AI video model. Vidgo exposes it as four model IDs: Text to Video, Image to Video, Reference to Video and Video Edit.

Models

kwaivgi/kling-v4.0/reference-to-video — Reference-to-video with Kling 4.0 from images, videos and elements, 3–30 seconds, 720p or 1080p.

Features

Up to 10 reference images, 5 reference videos and 7 elements, 15 assets in total.
Elements built from 2–4 images or one video of the same subject.
Optional start frame via image_urls.
Single or multi-shot prompts; 3–30 seconds at 720p or 1080p.
Five aspect ratios: auto, 16:9, 9:16, 1:1, 21:9.

Input modes

Send at least one reference input; you can combine them:

Reference images (reference_image_urls): cite as @Image1, @Image2, ….
Reference videos (reference_video_urls): cite as @Video1, @Video2, …. Billed as input video.
Elements (kling_elements): cite as @Element1, @Element2, …. Video-based elements are billed as input video.

Add image_urls with one image to fix the opening frame. Then choose a single prompt or a multi_prompt shot list:

Single prompt: send prompt and, optionally, duration.
Multi-shot: send multi_prompt with one entry per shot. The clip length is the sum of the shot durations; leave duration out or set it to that sum.

Required parameters

At least one of reference_image_urls, reference_video_urls or kling_elements.
prompt (string) or multi_prompt (object[]): send exactly one.
- prompt: 1–26,000 characters after trimming.
- multi_prompt: a non-empty list of shots {prompt, duration?}. Each shot prompt is 1–512 characters; each shot duration is an integer 1–30 (default 5). The shot durations must total 3–30 seconds.

Optional parameters

reference_image_urls (string[]): Up to 10 public HTTP(S) image URLs.
reference_video_urls (string[]): Up to 5 public HTTP(S) video URLs, each 3–30 seconds.
kling_elements (object[]): Up to 7 elements, at most 3 video-based. Each element has exactly one of:
- element_input_urls (string[]): 2–4 image URLs of the subject.
- element_input_video_urls (string[]): exactly 1 video URL of the subject (3–30 seconds).
image_urls (string[]): One start-frame image URL.
duration (integer): Output length, 3–30 seconds. Default 5; with multi_prompt the default is the shot total, and an explicit value must equal it.
resolution (string): 720p or 1080p. Default 720p.
aspect_ratio (string): auto, 16:9, 9:16, 1:1 or 21:9. Default auto.

Output

The finished task returns one MP4 video, with an audio track, in the files array of Query Task Status and the callback payload.

Examples

Reference images: a character and a cafe image, cited as @Image1 and @Image2, 8 seconds at 720p.
Elements plus a reference video, with callback: one robot element from two images and a dance clip cited as @Video1, 10 seconds at 1080p, 9:16.

Notes

Limits: start frame plus reference images ≤ 10; all assets (start frame, reference images, reference videos, elements) ≤ 15; video-based elements ≤ 3.
Input videos are downloaded and measured server-side (up to 100 MB each). Each must run 3–30 seconds, and all input videos together must not exceed 30 seconds.
voice_id and other extra fields inside an element return 400.
Fields not listed above return 400. model and callback_url belong at the request root, not inside input.
Credits are reserved at submission and depend on resolution and duration. When an input video is present, a separate input-video rate applies to billed seconds = output duration + the larger of the output duration and the total input video length (summed, then rounded up to whole seconds). A failed task is refunded in full. See the pricing page for current rates. Requests with reference images or image elements only use the standard rate on the output duration.
Output is 720p or 1080p only; there is no 4K or HDR tier, no audio on/off switch and no seed on this model.

Authorizations

Authorization

string

header

required

All API endpoints require Bearer Token authentication

Get your API Key:

Go to Dashboard → API Key (API Key Management Page) to get your API Key

Add it to the request header:

Authorization: Bearer VIDGO_API_KEY

Body

application/json

model

string

required

Model ID. Use kwaivgi/kling-v4.0/reference-to-video.

Example:

"kwaivgi/kling-v4.0/reference-to-video"

input

object

required

Generation parameters.

Show child attributes

callback_url

string<uri> | null

Optional public HTTP(S) endpoint that receives a POST when the task becomes finished or failed. HTTPS is recommended. Omit it, or send null or an empty string, to disable callbacks.

Example:

"https://your-domain.com/callback"

Response

Task submitted

code

enum<integer>

required

HTTP status code.

Available options:

200

data

object

required

Show child attributes

​Models

​Features

​Input modes

​Required parameters

​Optional parameters

​Output

​Examples

​Notes

Authorizations

Body

Response

Models

Features

Input modes

Required parameters

Optional parameters

Output

Examples

Notes