ModelFold Docs

简体中文

English

简体中文

English

Appearance

Kling 3.0 Omni Reference-To-Video ​

输入模式 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。

请求参数 ​

请求体 (application/json) ​

参数类型必填说明
modelstring是用于生成任务的模型名称。必填字段。
- 该接口必须使用 kling-3.0-omni/reference-to-video 模型 默认值："kling-3.0-omni/reference-to-video"。 可选值：kling-3.0-omni/reference-to-video。 示例：kling-3.0-omni/reference-to-video。
promptstring是本站网关要求传入 prompt，最长 2000 字。视频描述。去除首尾空白后不能为空，最长 3072 字符。 minLength: 1. maxLength: 2000. 示例：参考图片中的角色外观，生成角色在城市街道行走的视频。。
image_urlsarray&lt;string&gt;是参考图片地址数组，图片数量上限与参考主体数量和参考主体类型有关，其中：无参考视频+仅有多图主体时，参考图片与多图主体数量之和不得超过7。无参考视频+同时有视频角色主体和多图主体时，参考图片与多图主体数量之和不得超过4。支持 HTTP、HTTPS 和 OSS 地址。图片支持 JPG、JPEG、PNG 格式；单个文件不超过 50 MB；宽高均不小于 300 px；宽高比为 0.4 至 2.5。 maxItems: 7.
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否无视频输入时支持 16:9、9:16、1:1 默认值："16:9"。 可选值：16:9 / 9:16 / 1:1。 示例：16:9。
audioboolean否是否开启音频。无视频输入时支持 true 或 false。 示例：true。
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[].promptstring是当前镜头的视频描述，最长 512 个字符。 minLength: 1. maxLength: 512.
  multi_prompt[].durationinteger是当前镜头时长（秒），1–12；所有镜头合计不超过 15 秒。 minimum: 1. maximum: 12.
elementsarray&lt;object&gt;否一次性主体素材列表，默认为空数组。主体数量受参考图片、参考视频和主体类型共同限制。无参考视频+仅有多图主体时，参考图片与多图主体数量之和不得超过7。无参考视频+仅有视频角色主体时，视频角色主体数量不得超过3。无参考视频+同时有视频角色主体和多图主体时，视频角色主体数量不得超过3，参考图片与多图主体数量之和不得超过4。 默认值：[]。
  elements[].namestring是主体名称。同一请求内不能重复，可在 prompt 中通过 @name 引用。 示例：element_dog。
  elements[].descriptionstring是主体描述。 示例：A happy golden retriever。
  elements[].element_input_urlsarray&lt;string&gt;是主体图片或视频素材地址，需要传入 1 至 4 个。 minItems: 1. maxItems: 4.
  elements[].element_input_audio_urlsarray&lt;string&gt;否可选的主体参考音频地址列表，可读取到时长时必须为 5 至 30 秒。 默认值：[]。
  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/reference-to-video",
  "prompt": "参考图片中的角色外观，生成角色在城市街道行走的视频。",
  "image_urls": [
    "https://example.com/reference.png"
  ],
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "elements": [
    {
      "name": "element_dog",
      "description": "A happy golden retriever",
      "element_input_urls": [
        "https://example.com/reference.png"
      ]
    }
  ]
}'
json
{
  "model": "kling-3.0-omni/reference-to-video",
  "prompt": "参考图片中的角色外观，生成角色在城市街道行走的视频。",
  "image_urls": [
    "https://example.com/reference.png"
  ],
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "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。

请求参数 ​

请求体 (application/json) ​

参数类型必填说明
modelstring是用于生成任务的模型名称。必填字段。
- 该接口必须使用 kling-3.0-omni/reference-to-video 模型 默认值："kling-3.0-omni/reference-to-video"。 可选值：kling-3.0-omni/reference-to-video。 示例：kling-3.0-omni/reference-to-video。
promptstring是本站网关要求传入 prompt，最长 2000 字。视频描述。去除首尾空白后不能为空，最长 3072 字符。 minLength: 1. maxLength: 2000. 示例：根据输入视频生成自然流畅的镜头变化。。
video_urlsarray&lt;string&gt;是视频地址数组，必须且只能传入 1 个视频。支持 HTTP、HTTPS 和 OSS 地址。视频支持 MP4、MOV 格式；单个文件不超过 200 MB；时长为 3 至 15.5 秒；宽高为 700 至 4553 px；总像素不超过 8,294,400；宽高比为 0.4 至 2；帧率为 24 至 60 fps。 minItems: 1. maxItems: 1.
resolutionstring否视频分辨率。720p 表示输出 720P 视频，1080p 表示输出 1080P 视频，4k 表示输出 4K 视频。 默认值："720p"。 可选值：720p / 1080p / 4k。 示例：720p。
aspect_ratiostring是仅视频输入时只能使用 auto。 默认值："auto"。 可选值：auto。 示例：auto。
audioboolean是有视频输入时不生成音频，请传 false。 示例：false。
elementsarray&lt;object&gt;否一次性主体素材列表。主体数量受参考图片、参考视频和主体类型共同限制。
- 有参考视频+仅有多图主体时，参考图片与多图主体数量之和不得超过 4。
- 有参考视频+仅有视频角色主体时，视频角色主体数量不得超过 1。
- 有参考视频时，不同时支持视频角色主体和多图主体或参考图片。 默认值：[]。
  elements[].namestring是主体名称。同一请求内不能重复，可在 prompt 中通过 @name 引用。 示例：element_dog。
  elements[].descriptionstring是主体描述。 示例：A happy golden retriever。
  elements[].element_input_urlsarray&lt;string&gt;是主体图片或视频素材地址，需要传入 1 至 4 个。 minItems: 1. maxItems: 4.
  elements[].element_input_audio_urlsarray&lt;string&gt;否可选的主体参考音频地址列表，可读取到时长时必须为 5 至 30 秒。 默认值：[]。
  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/reference-to-video",
  "prompt": "根据输入视频生成自然流畅的镜头变化。",
  "video_urls": [
    "https://example.com/reference.mp4"
  ],
  "aspect_ratio": "auto",
  "audio": false,
  "resolution": "720p",
  "elements": [
    {
      "name": "element_dog",
      "description": "A happy golden retriever",
      "element_input_urls": [
        "https://example.com/reference.png"
      ]
    }
  ]
}'
json
{
  "model": "kling-3.0-omni/reference-to-video",
  "prompt": "根据输入视频生成自然流畅的镜头变化。",
  "video_urls": [
    "https://example.com/reference.mp4"
  ],
  "aspect_ratio": "auto",
  "audio": false,
  "resolution": "720p",
  "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": {}
}

输入模式 3: 视频加图片 ​

接口 ​

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。

请求参数 ​

请求体 (application/json) ​

参数类型必填说明
modelstring是用于生成任务的模型名称。必填字段。
- 该接口必须使用 kling-3.0-omni/reference-to-video 模型 默认值："kling-3.0-omni/reference-to-video"。 可选值：kling-3.0-omni/reference-to-video。 示例：kling-3.0-omni/reference-to-video。
promptstring是本站网关要求传入 prompt，最长 2000 字。视频描述。去除首尾空白后不能为空，最长 3072 字符。 minLength: 1. maxLength: 2000. 示例：参考视频和图片中的角色，生成角色在城市街道行走的视频。。
image_urlsarray&lt;string&gt;是参考图片地址数组，图片数量上限与参考主体数量和参考主体类型有关，其中：
    仅有多图主体时，参考图片与多图主体数量之和不得超过4
    不同时支持视频角色主体和多图主体或参考图片。
支持 HTTP、HTTPS 和 OSS 地址。图片支持 JPG、JPEG、PNG 格式；单个文件不超过 50 MB；宽高均不小于 300 px；宽高比为 0.4 至 2.5。 maxItems: 4.
video_urlsarray&lt;string&gt;是视频地址数组，必须且只能传入 1 个视频。支持 HTTP、HTTPS 和 OSS 地址。视频支持 MP4、MOV 格式；单个文件不超过 200 MB；时长为 3 至 15.5 秒；宽高为 700 至 4553 px；总像素不超过 8,294,400；宽高比为 0.4 至 2；帧率为 24 至 60 fps。 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否视频画幅比例。 默认值："16:9"。 可选值：16:9 / 9:16 / 1:1。 示例：16:9。
audioboolean是有视频输入时不生成音频，请传 false。 示例：false。
elementsarray&lt;object&gt;否一次性主体素材列表。有参考视频+仅有多图主体时，参考图片与多图主体数量之和不得超过4。有参考视频+仅有视频角色主体时，视频角色主体数量不得超过1。有参考视频时，不同时支持视频角色主体和多图主体或参考图片。
注意：有视频输入且 customize_multi_shots=false 时不可用（必须为空数组或不传）。 默认值：[]。
  elements[].namestring是主体名称。同一请求内不能重复，可在 prompt 中通过 @name 引用。 示例：element_dog。
  elements[].descriptionstring是主体描述。 示例：A happy golden retriever。
  elements[].element_input_urlsarray&lt;string&gt;是主体图片或视频素材地址，需要传入 1 至 4 个。 minItems: 1. maxItems: 4.
  elements[].element_input_audio_urlsarray&lt;string&gt;否可选的主体参考音频地址列表，可读取到时长时必须为 5 至 30 秒。 默认值：[]。
  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/reference-to-video",
  "prompt": "参考视频和图片中的角色，生成角色在城市街道行走的视频。",
  "image_urls": [
    "https://example.com/reference.png"
  ],
  "video_urls": [
    "https://example.com/reference.mp4"
  ],
  "audio": false,
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "elements": [
    {
      "name": "element_dog",
      "description": "A happy golden retriever",
      "element_input_urls": [
        "https://example.com/reference.png"
      ]
    }
  ]
}'
json
{
  "model": "kling-3.0-omni/reference-to-video",
  "prompt": "参考视频和图片中的角色，生成角色在城市街道行走的视频。",
  "image_urls": [
    "https://example.com/reference.png"
  ],
  "video_urls": [
    "https://example.com/reference.mp4"
  ],
  "audio": false,
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "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