Kling 4.0 Reference To Video

Endpoint

POST /videos/generations

Full URL: https://modelfold.ai/v1/videos/generations

Authentication: every request must include the Authorization: Bearer <API_KEY> header.

Send model parameters directly in the JSON body. Do not wrap them in input. This request waits for generation to finish and returns data[].url; supported media models also offer async jobs, polling and callbacks. Replace example media URLs with your own publicly accessible files. See API gateway for billing and errors.

Input parameters for the generation task.

Request Parameters

Body (application/json)

Parameter	Type	Required	Description
model	string	Yes	The name of the model used to generate the task. This field is required. - This endpoint requires the kling-4.0/reference-to-video model Default："kling-4.0/reference-to-video"。 Allowed values：kling-4.0/reference-to-video。 Example：kling-4.0/reference-to-video。
prompt	string	Yes	Prompt required by the ModelFold gateway; at most 2000 characters. Video description. Required. Maximum 8000 characters. Use @ to mention assets uploaded in this request: - @image_1, @image_2, … map to image_urls in order (1-based) - @video_1, @video_2, … map to video_urls - @name maps to the name of an item in elements or voices Every @ mention must match an asset included in this request, otherwise the request is rejected. Mentions use longest-match against declared names. If the matched name ends with a letter, digit, or underscore, the next character cannot be a letter, digit, or underscore. minLength: 1. maxLength: 2000. Example：@Hero sits at the desk in @video_1, picks up the doll from @image_1, and greets using @Narrator。
duration	integer	No	Output video duration in seconds. Integer from 3 to 30. Default: 5. Default：5。 minimum: 3. maximum: 30. Example：5。
resolution	string	No	Output resolution. 720p or 1080p. Default: 720p. Default："720p"。 Allowed values：720p / 1080p。 Example：720p。
aspect_ratio	string	No	Output aspect ratio. Optional. - If omitted and any reference asset is provided, the model uses auto - If omitted and no reference asset is provided, the model uses 16:9 Allowed values：auto / 16:9 / 9:16 / 1:1 / 21:9。 Example：auto。
image_urls	array<string>	No	Reference images, up to 10 publicly accessible URLs. Mention them in the prompt as @image_1, @image_2, … in array order. Each side must be 300–65536 pixels; aspect ratio 0.40–2.5. Default：[]。 maxItems: 10.
video_urls	array<string>	No	Reference videos, up to 5 clips, each 2–30 seconds. Mention them in the prompt as @video_1, @video_2, …. Reference videos plus video subjects in elements cannot exceed 5 in total. Default：[]。 maxItems: 5.
keep_original_sound	boolean	No	Whether to keep the original audio of the reference videos. Only takes effect when video_urls is provided. Default: false. If no reference video is provided, native audio is always generated. Default：false。 Example：false。
elements	array<object>	No	Subjects used only for this task. Up to 7 items, of which at most 3 can be video subjects. Mention them in the prompt as @name. image_urls, video_urls, elements, and voices together cannot exceed 15 items. Default：[]。 maxItems: 7.
elements[].name	string	Yes	The name used in the prompt as @Hero. 1–20 characters; Chinese, letters, digits, and underscore only. Must be unique across elements and voices (case-insensitive). Reserved names (case-insensitive, N is a number) cannot be used: image_N, video_N, keyframe_N, object_N, audio_N, first_frame, last_frame. pattern: ^[一-龥A-Za-z0-9_]{1,20}$. Example：Hero。
elements[].image_urls	array<string>	No	2–4 publicly accessible image URLs for an image subject. Cannot be used together with video_url. The first image is the primary view (front face or main angle); the rest are supporting views. minItems: 2. maxItems: 4.
elements[].video_url	string	No	Character video URL for a video subject. Cannot be used together with image_urls. One video, 3–8 seconds, a single continuous shot (no cuts), shortest side at least 700 pixels. pattern: ^https?://.
elements[].tag	string	No	Subject category. Optional for image subjects — if omitted, it is inferred from the primary image. Video subjects are always character; any other value is rejected. Allowed values：character / animal / prop / costume / scene / effect / others。 Example：character。
elements[].description	string	No	Optional subject description. Maximum 100 characters. maxLength: 100.
elements[].voice_url	string	No	Optional reference audio bound to this subject. It cannot be mentioned with @ on its own and does not count toward the voices quota. Only character subjects can bind audio: for image subjects tag must be character or omitted; for video subjects, if omitted and the video contains speech, that speech is used automatically. pattern: ^https?://.
voices	array<object>	No	Standalone voice references used only for this task. Up to 3 items. Mention them in the prompt as @name. Audio bound on a subject via voice_url is separate and does not count toward this quota. Default：[]。 maxItems: 3.
voices[].name	string	Yes	The name used in the prompt as @Narrator. 1–20 characters; Chinese, letters, digits, and underscore only. Must be unique across elements and voices (case-insensitive). Reserved names (case-insensitive, N is a number) cannot be used: image_N, video_N, keyframe_N, object_N, audio_N, first_frame, last_frame. pattern: ^[一-龥A-Za-z0-9_]{1,20}$. Example：Narrator。
voices[].audio_url	string	Yes	Publicly accessible reference audio URL. Required. The task fails if no usable voice can be detected. pattern: ^https?://.

Request Example

curl -X POST "https://modelfold.ai/v1/videos/generations" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "kling-4.0/reference-to-video",
  "prompt": "@Hero sits at the desk in @video_1, picks up the doll from @image_1, and greets using @Narrator",
  "duration": 5,
  "resolution": "720p",
  "image_urls": [
    "https://example.com/reference.png"
  ],
  "video_urls": [
    "https://example.com/reference.mp4"
  ],
  "keep_original_sound": false,
  "elements": [
    {
      "name": "Hero"
    }
  ],
  "voices": [
    {
      "name": "Narrator",
      "audio_url": "https://example.com/reference.mp3"
    }
  ]
}'

{
  "model": "kling-4.0/reference-to-video",
  "prompt": "@Hero sits at the desk in @video_1, picks up the doll from @image_1, and greets using @Narrator",
  "duration": 5,
  "resolution": "720p",
  "image_urls": [
    "https://example.com/reference.png"
  ],
  "video_urls": [
    "https://example.com/reference.mp4"
  ],
  "keep_original_sound": false,
  "elements": [
    {
      "name": "Hero"
    }
  ],
  "voices": [
    {
      "name": "Narrator",
      "audio_url": "https://example.com/reference.mp3"
    }
  ]
}

Response

200 — Generation completed. usage contains actual billing details; result URLs are illustrative.

{
  "ok": true,
  "created": 1792134000,
  "data": [
    {
      "url": "https://modelfold.ai/uploads/outputs/result.mp4"
    }
  ],
  "usage": {}
}