Kling 3.0 Omni Text 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 parameter configuration for the generation task. Rules: (1) customize_multi_shots and prefer_multi_shots cannot both be true; (2) customize_multi_shots = true requires 1–6 multi_prompt shots (each 1–12 s, total ≤ 15 s); (3) otherwise omit multi_prompt.

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-3.0-omni/text-to-video model Default："kling-3.0-omni/text-to-video"。 Allowed values：kling-3.0-omni/text-to-video。 Example：kling-3.0-omni/text-to-video。
prompt	string	Yes	Prompt required by the ModelFold gateway; at most 2000 characters. Text description of the video. It must not be empty after leading and trailing whitespace is removed, and must not exceed 3,072 characters. minLength: 1. maxLength: 2000.
customize_multi_shots	boolean	No	Optional, default false. Set true for custom multi-shot (multi_prompt required). Default：false。 Example：true。
prefer_multi_shots	boolean	No	Whether to enable intelligent shot planning. This field is mutually exclusive with customize_multi_shots. Both fields may be false, but they cannot both be true. Example：true。
multi_prompt	array<object>	No	List of custom shots. When customize_multi_shots is true, this field is required, must not be empty, and supports up to 6 shots. When customize_multi_shots is false, it must be an empty array or omitted. Default：[]。 maxItems: 6.
multi_prompt[].prompt	string	Yes	Video description for the current shot. Maximum length: 512 characters. minLength: 1. maxLength: 512. Example：A wide shot of the fox entering the snowy forest.。
multi_prompt[].duration	integer	Yes	Duration of this shot in seconds, 1–12. The sum of all shots must not exceed 15. minimum: 1. maximum: 12. Example：2。
elements	array<object>	No	List of one-time subject assets. The default is an empty array. When using only multi-image subjects, up to 7 subjects can be uploaded. When using only video character subjects, the number of video character subjects must not exceed 3. When using both video character and multi-image subjects, the number of video character subjects must not exceed 3, and the number of multi-image subjects must not exceed 4. Default：[]。
elements[].name	string	Yes	Subject name. It must be unique within the same request and can be referenced in the prompt field using @name. minLength: 1. Example：element_dog。
elements[].description	string	Yes	Text description of the subject asset. minLength: 1. Example：A happy golden retriever。
elements[].element_input_urls	array<string>	Yes	List of image URLs for a multi-image subject (provide 2 to 4 images), or a video URL for a video character subject (provide exactly 1 video). Images and videos cannot be mixed. HTTP, HTTPS, and OSS URLs are supported. minItems: 1. maxItems: 4.
elements[].element_input_audio_urls	array<string>	No	Optional list of subject audio asset URLs. HTTP, HTTPS, and OSS URLs are supported. Default：[]。
audio	boolean	No	Whether to add audio to the generated video. true enables audio; false disables audio. Default：false。 Example：false。
resolution	string	No	Resolution of the generated video. Available values are 720p (outputs a 720p video), 1080p (outputs a 1080p video), and 4k (outputs a 4K video). Default："720p"。 Allowed values：720p / 1080p / 4k。 Example：720p。
aspect_ratio	string	No	Aspect ratio of the generated video. Supported values are 16:9, 9:16, and 1:1. Default："16:9"。 Allowed values：16:9 / 9:16 / 1:1。 Example：16:9。
duration	integer	No	Total video duration in seconds. The supported range is 3 to 15 seconds, and the default is 5 seconds. Default：5。 Allowed values：3 / 4 / 5 / 6 / 7 / 8 / 9 / 10 / 11 / 12 / 13 / 14 / 15。 minimum: 3. maximum: 15. Example：5。

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-3.0-omni/text-to-video",
  "prompt": "A paper boat drifting down a rainy street.",
  "elements": [
    {
      "name": "element_dog",
      "description": "A happy golden retriever",
      "element_input_urls": [
        "https://example.com/reference.png"
      ]
    }
  ],
  "audio": false,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "duration": 5
}'

{
  "model": "kling-3.0-omni/text-to-video",
  "prompt": "A paper boat drifting down a rainy street.",
  "elements": [
    {
      "name": "element_dog",
      "description": "A happy golden retriever",
      "element_input_urls": [
        "https://example.com/reference.png"
      ]
    }
  ],
  "audio": false,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "duration": 5
}

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": {}
}