Kling 3.0 Omni Image To Video

Input mode 1: Single First Frame

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. 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; (4) for image-to-video single-shot, aspect_ratio must be "auto".

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/image-to-video model Default："kling-3.0-omni/image-to-video"。 Allowed values：kling-3.0-omni/image-to-video。 Example：kling-3.0-omni/image-to-video。
prompt	string	Yes	Prompt required by the ModelFold gateway; at most 2000 characters. Video description. It must not be empty after leading and trailing whitespace is removed. Maximum length: 3,072 characters. maxLength: 2000. pattern: ^.*\S.*$. Example：A happy golden retriever running across a grassy field。
image_urls	array<string>	Yes	Array of first-frame image URLs. Exactly 1 image is required. HTTP, HTTPS, and OSS URLs are supported. Images must be in JPG, JPEG, or PNG format; each file must not exceed 50 MB; both width and height must be at least 300 px; and the aspect ratio must be between 0.4 and 2.5. minItems: 1. maxItems: 1.
duration	integer	No	Total video duration in seconds. Optional; the default is 5 seconds. Supports integer values from 3 to 15. Default：5。 Allowed values：3 / 4 / 5 / 6 / 7 / 8 / 9 / 10 / 11 / 12 / 13 / 14 / 15。 minimum: 3. maximum: 15. Example：5。
resolution	string	No	Video resolution. 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	Video aspect ratio. 16:9, 9:16, and 1:1 can be selected only when custom multi-shot mode is enabled through customize_multi_shots; otherwise, use auto. Default："auto"。 Allowed values：16:9 / 9:16 / 1:1 / auto。 Example：auto。
audio	boolean	No	Whether to enable audio. Passing this value explicitly is recommended. true enables audio; false disables audio. Example：false。
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. Example：true。
multi_prompt	array<object>	No	List of custom shots. When customize_multi_shots=true, this field is required and may contain up to 6 shots. When customize_multi_shots=false, it must be an empty array or omitted. minItems: 1. maxItems: 6.
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。
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.。
elements	array<object>	No	List of one-time subject assets. The default is an empty array, with up to 3 subjects. The subject is automatically identified as a multi-image subject or video character subject based on element_input_urls. Default：[]。 maxItems: 3.
elements[].name	string	Yes	Subject name. It must be unique within the same request and can be referenced in the prompt using @name. Example：element_dog。
elements[].description	string	Yes	Subject description. Example：A happy golden retriever。
elements[].element_input_urls	array<string>	Yes	For a multi-image subject, provide 2 to 4 images. 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 reference audio URLs. It may be omitted or passed as an empty array. If the audio duration can be determined, it must be between 5 and 30 seconds. Default：[]。
elements[].start_time	integer	No	Start time for trimming the video character subject, in milliseconds. The default is 0. This applies only when a video is provided in element_input_urls. Default：0。 minimum: 0. Example：0。
elements[].end_time	integer	No	End time for trimming the video character subject, in milliseconds. The default is 8,000. It must be greater than start_time, and the trimmed duration must be between 3,000 and 8,000 milliseconds. Default：8000。 minimum: 3000. Example：8000。

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/image-to-video",
  "prompt": "A happy golden retriever running across a grassy field",
  "image_urls": [
    "https://example.com/first-frame.jpg"
  ],
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "auto",
  "elements": [
    {
      "name": "element_dog",
      "description": "A happy golden retriever",
      "element_input_urls": [
        "https://example.com/reference.png"
      ]
    }
  ]
}'

{
  "model": "kling-3.0-omni/image-to-video",
  "prompt": "A happy golden retriever running across a grassy field",
  "image_urls": [
    "https://example.com/first-frame.jpg"
  ],
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "auto",
  "elements": [
    {
      "name": "element_dog",
      "description": "A happy golden retriever",
      "element_input_urls": [
        "https://example.com/reference.png"
      ]
    }
  ]
}

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

Input mode 2: First and Last Frames

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. 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; (4) for image-to-video single-shot, aspect_ratio must be "auto".

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/image-to-video model Default："kling-3.0-omni/image-to-video"。 Allowed values：kling-3.0-omni/image-to-video。 Example：kling-3.0-omni/image-to-video。
prompt	string	Yes	Prompt required by the ModelFold gateway; at most 2000 characters. Video description. It must not be empty after leading and trailing whitespace is removed. Maximum length: 3,072 characters. maxLength: 2000. pattern: ^.*\S.*$. Example：A happy golden retriever running across a grassy field。
image_urls	array<string>	Yes	Array of first-frame and last-frame image URLs. Exactly 2 images are required: index 0 is the first frame and index 1 is the last frame. HTTP, HTTPS, and OSS URLs are supported. Images must be in JPG, JPEG, or PNG format; each file must not exceed 50 MB; both width and height must be at least 300 px; and the aspect ratio must be between 0.4 and 2.5. minItems: 2. maxItems: 2.
duration	integer	No	Total video duration in seconds. Optional; the default is 5 seconds. Supports integer values from 3 to 15. Default：5。 Allowed values：3 / 4 / 5 / 6 / 7 / 8 / 9 / 10 / 11 / 12 / 13 / 14 / 15。 minimum: 3. maximum: 15. Example：5。
resolution	string	No	Video resolution. 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	Video aspect ratio. 16:9, 9:16, and 1:1 can be selected only when custom multi-shot mode is enabled through customize_multi_shots; otherwise, use auto. Default："auto"。 Allowed values：16:9 / 9:16 / 1:1 / auto。 Example：auto。
audio	boolean	No	Whether to enable audio. true enables audio; false disables audio. Example：false。
customize_multi_shots	boolean	No	Optional, default false. Set true for custom multi-shot (multi_prompt required). Default：false。 Example：false。
prefer_multi_shots	boolean	No	Whether to enable intelligent shot planning. This field is mutually exclusive with customize_multi_shots. Example：true。
multi_prompt	array<object>	No	List of custom shots. When customize_multi_shots=true, this field is required and may contain up to 6 shots. When customize_multi_shots=false, it must be an empty array or omitted. minItems: 1. maxItems: 6.
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。
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.。
elements	array<object>	No	List of one-time subject assets. The default is an empty array, with up to 3 subjects. Default：[]。 maxItems: 3.
elements[].name	string	Yes	Subject name. Example：element_dog。
elements[].description	string	Yes	Subject description. Example：A happy golden retriever。
elements[].element_input_urls	array<string>	Yes	For a multi-image subject, provide 2 to 4 images. 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 reference audio URLs. Default：[]。
elements[].start_time	integer	No	Start time for trimming the video character subject, in milliseconds. The default is 0. Default：0。 Example：0。
elements[].end_time	integer	No	End time for trimming the video character subject, in milliseconds. The default is 8,000. Default：8000。 Example：8000。

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/image-to-video",
  "prompt": "A happy golden retriever running across a grassy field",
  "image_urls": [
    "https://example.com/reference.png",
    "https://example.com/reference.png"
  ],
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "auto",
  "elements": [
    {
      "name": "element_dog",
      "description": "A happy golden retriever",
      "element_input_urls": [
        "https://example.com/reference.png"
      ]
    }
  ]
}'

{
  "model": "kling-3.0-omni/image-to-video",
  "prompt": "A happy golden retriever running across a grassy field",
  "image_urls": [
    "https://example.com/reference.png",
    "https://example.com/reference.png"
  ],
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "auto",
  "elements": [
    {
      "name": "element_dog",
      "description": "A happy golden retriever",
      "element_input_urls": [
        "https://example.com/reference.png"
      ]
    }
  ]
}

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