ModelFold Docs

简体中文

English

简体中文

English

Appearance

Kling 3.0 Omni 图生视频 ​

输入模式 1: 单张首帧 ​

接口 ​

POST /videos/generations

完整 URL: https://modelfold.ai/v1/videos/generations

鉴权：所有请求都需要 Authorization: Bearer <API_KEY> 请求头。

模型参数直接放在 JSON 请求体中，不要套 input。请求等待生成完成后返回 data[].url；支持的媒体模型也可使用 异步创建、轮询及回调。示例素材地址须替换为自己的公开可访问文件。计费及错误说明见 API 网关。

生成任务的输入参数。规则：①customize_multi_shots 与 prefer_multi_shots 不能同为 true;②customize_multi_shots 为 true 时须传 1–6 个 multi_prompt 镜头（单镜头 1–12 秒，合计 ≤15 秒）;③否则不要传 multi_prompt;④图生视频单镜头时 aspect_ratio 必须为 "auto"。

请求参数 ​

请求体 (application/json) ​

参数类型必填说明
modelstring是用于生成任务的模型名称。必填字段。
- 该接口必须使用 kling-3.0-omni/image-to-video 模型 默认值："kling-3.0-omni/image-to-video"。 可选值：kling-3.0-omni/image-to-video。 示例：kling-3.0-omni/image-to-video。
promptstring是本站网关要求传入 prompt，最长 2000 字。视频描述，去除首尾空白后不能为空，最长 3072 字符。 maxLength: 2000. pattern: ^.*\S.*$. 示例：一只快乐的金毛猎犬在草地上奔跑。
image_urlsarray&lt;string&gt;是首帧图片地址数组，必须且只能传入 1 张图片。支持 HTTP、HTTPS 和 OSS 地址。图片支持 JPG、JPEG、PNG 格式；单个文件不超过 50 MB；宽高均不小于 300 px；宽高比为 0.4 至 2.5。 minItems: 1. maxItems: 1.
durationinteger否视频总时长，单位为秒。可选，默认 5 秒，支持 3 至 15 秒的整数值。 默认值：5。 可选值：3 / 4 / 5 / 6 / 7 / 8 / 9 / 10 / 11 / 12 / 13 / 14 / 15。 minimum: 3. maximum: 15. 示例：5。
resolutionstring否视频分辨率。720p 表示输出 720P 视频，1080p 表示输出 1080P 视频，4k 表示输出 4K 视频。 默认值："720p"。 可选值：720p / 1080p / 4k。 示例：720p。
aspect_ratiostring否视频画幅比例。只要在开启自定义多镜头 customize_multi_shots 才可以选择 16:9、9:16、1:1，其余情况为 auto。 默认值："auto"。 可选值：16:9 / 9:16 / 1:1 / auto。 示例：auto。
audioboolean否是否开启音频。建议显式传入。true 表示开启音频，false 表示关闭音频。 示例：false。
customize_multi_shotsboolean否可选，默认 false。设为 true 为自定义分镜（需传 multi_prompt）。 默认值：false。 示例：true。
prefer_multi_shotsboolean否是否开启智能分镜。与 customize_multi_shots 互斥。 示例：true。
multi_promptarray&lt;object&gt;否自定义分镜列表。当 customize_multi_shots=true 必填，最多 6 个镜头；当 customize_multi_shots=false 时必须为空数组或不传。 minItems: 1. maxItems: 6.
  multi_prompt[].durationinteger是当前镜头时长（秒），1–12；所有镜头合计不超过 15 秒。 minimum: 1. maximum: 12. 示例：2。
  multi_prompt[].promptstring是当前镜头的视频描述，最长 512 个字符。 minLength: 1. maxLength: 512. 示例：A wide shot of the fox entering the snowy forest.。
elementsarray&lt;object&gt;否一次性主体素材列表，默认为空数组，最多 3 个主体。根据 element_input_urls 自动识别为多图主体或视频角色主体。 默认值：[]。 maxItems: 3.
  elements[].namestring是主体名称。同一请求内不能重复，可在提示词中通过 @name 引用。 示例：element_dog。
  elements[].descriptionstring是主体描述。 示例：A happy golden retriever。
  elements[].element_input_urlsarray&lt;string&gt;是多图主体传 2～4 张图片；视频角色主体恰好传 1 个视频；图片和视频不能混传。支持 HTTP、HTTPS 和 OSS 地址。 minItems: 1. maxItems: 4.
  elements[].element_input_audio_urlsarray&lt;string&gt;否可选的主体参考音频地址列表。可不传或传空数组；可读取到音频时长时，音频时长必须为 5 至 30 秒。 默认值：[]。
  elements[].start_timeinteger否视频角色主体的截取开始时间，单位为毫秒，默认 0。仅 element_input_urls 传入视频时生效。 默认值：0。 minimum: 0. 示例：0。
  elements[].end_timeinteger否视频角色主体的截取结束时间，单位为毫秒，默认 8000。必须大于 start_time，截取时长必须为 3000 至 8000 毫秒。 默认值：8000。 minimum: 3000. 示例：8000。

请求示例 ​

bash
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": "一只快乐的金毛猎犬在草地上奔跑",
  "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"
      ]
    }
  ]
}'
json
{
  "model": "kling-3.0-omni/image-to-video",
  "prompt": "一只快乐的金毛猎犬在草地上奔跑",
  "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"
      ]
    }
  ]
}

响应 ​

200 — 生成完成。usage 返回实际计费明细；结果地址仅作结构示例。 ​

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

输入模式 2: 首帧加尾帧 ​

接口 ​

POST /videos/generations

完整 URL: https://modelfold.ai/v1/videos/generations

鉴权：所有请求都需要 Authorization: Bearer <API_KEY> 请求头。

模型参数直接放在 JSON 请求体中，不要套 input。请求等待生成完成后返回 data[].url；支持的媒体模型也可使用 异步创建、轮询及回调。示例素材地址须替换为自己的公开可访问文件。计费及错误说明见 API 网关。

生成任务的输入参数。规则：①customize_multi_shots 与 prefer_multi_shots 不能同为 true;②customize_multi_shots 为 true 时须传 1–6 个 multi_prompt 镜头（单镜头 1–12 秒，合计 ≤15 秒）;③否则不要传 multi_prompt;④图生视频单镜头时 aspect_ratio 必须为 "auto"。

请求参数 ​

请求体 (application/json) ​

参数类型必填说明
modelstring是用于生成任务的模型名称。必填字段。
- 该接口必须使用 kling-3.0-omni/image-to-video 模型 默认值："kling-3.0-omni/image-to-video"。 可选值：kling-3.0-omni/image-to-video。 示例：kling-3.0-omni/image-to-video。
promptstring是本站网关要求传入 prompt，最长 2000 字。视频描述，去除首尾空白后不能为空，最长 3072 字符。 maxLength: 2000. pattern: ^.*\S.*$. 示例：一只快乐的金毛猎犬在草地上奔跑。
image_urlsarray&lt;string&gt;是首帧和尾帧图片地址数组，必须且只能传入 2 张图片。索引 0 为首帧，索引 1 为尾帧。支持 HTTP、HTTPS 和 OSS 地址。图片支持 JPG、JPEG、PNG 格式；单个文件不超过 50 MB；宽高均不小于 300 px；宽高比为 0.4 至 2.5。 minItems: 2. maxItems: 2.
durationinteger否视频总时长，单位为秒。可选，默认 5 秒，支持 3 至 15 秒的整数值。 默认值：5。 可选值：3 / 4 / 5 / 6 / 7 / 8 / 9 / 10 / 11 / 12 / 13 / 14 / 15。 minimum: 3. maximum: 15. 示例：5。
resolutionstring否视频分辨率。720p 表示输出 720P 视频，1080p 表示输出 1080P 视频，4k 表示输出 4K 视频。 默认值："720p"。 可选值：720p / 1080p / 4k。 示例：720p。
aspect_ratiostring否视频画幅比例。只要在开启自定义多镜头 customize_multi_shots 才可以选择 16:9、9:16、1:1，其余情况为 auto。 默认值："auto"。 可选值：16:9 / 9:16 / 1:1 / auto。 示例：auto。
audioboolean否是否开启音频。true 表示开启音频，false 表示关闭音频。 示例：false。
customize_multi_shotsboolean否可选，默认 false。设为 true 为自定义分镜（需传 multi_prompt）。 默认值：false。 示例：false。
prefer_multi_shotsboolean否是否开启智能分镜。与 customize_multi_shots 互斥。 示例：true。
multi_promptarray&lt;object&gt;否自定义分镜列表。当 customize_multi_shots=true 必填，最多 6 个镜头；当 customize_multi_shots=false 时必须为空数组或不传。 minItems: 1. maxItems: 6.
  multi_prompt[].durationinteger是当前镜头时长（秒），1–12；所有镜头合计不超过 15 秒。 minimum: 1. maximum: 12. 示例：2。
  multi_prompt[].promptstring是当前镜头的视频描述，最长 512 个字符。 minLength: 1. maxLength: 512. 示例：A wide shot of the fox entering the snowy forest.。
elementsarray&lt;object&gt;否一次性主体素材列表，默认为空数组，最多 3 个主体。 默认值：[]。 maxItems: 3.
  elements[].namestring是主体名称。 示例：element_dog。
  elements[].descriptionstring是主体描述。 示例：A happy golden retriever。
  elements[].element_input_urlsarray&lt;string&gt;是多图主体传 2～4 张图片；视频角色主体恰好传 1 个视频；图片和视频不能混传。支持 HTTP、HTTPS 和 OSS 地址。 minItems: 1. maxItems: 4.
  elements[].element_input_audio_urlsarray&lt;string&gt;否可选的主体参考音频地址列表。 默认值：[]。
  elements[].start_timeinteger否视频角色主体的截取开始时间，单位为毫秒，默认 0。 默认值：0。 示例：0。
  elements[].end_timeinteger否视频角色主体的截取结束时间，单位为毫秒，默认 8000。 默认值：8000。 示例：8000。

请求示例 ​

bash
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": "一只快乐的金毛猎犬在草地上奔跑",
  "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"
      ]
    }
  ]
}'
json
{
  "model": "kling-3.0-omni/image-to-video",
  "prompt": "一只快乐的金毛猎犬在草地上奔跑",
  "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"
      ]
    }
  ]
}

响应 ​

200 — 生成完成。usage 返回实际计费明细；结果地址仅作结构示例。 ​

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

ModelFold — 一个 API，接入所有主流 AI 模型。

© 2026 ModelFold