Kling 4.0 全能参考生成视频

接口

POST /videos/generations

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

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

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

生成任务的输入参数。

请求参数

请求体 (application/json)

参数	类型	必填	说明
model	string	是	用于生成任务的模型名称。必填字段。 - 该接口必须使用 kling-4.0/reference-to-video 模型 默认值："kling-4.0/reference-to-video"。 可选值：kling-4.0/reference-to-video。 示例：kling-4.0/reference-to-video。
prompt	string	是	本站网关要求传入 prompt，最长 2000 字。描述要生成的视频。 用 @ 引用本次请求里已上传的素材： - @image_1、@image_2… 按顺序对应 image_urls（从 1 开始） - @video_1、@video_2… 对应 video_urls - @名称 对应 elements 或 voices 中的 name 每个 @ 引用都必须能匹配到本次请求已传入的素材，否则请求会被拒绝。引用按已声明名称做最长匹配；若匹配到的名称以字母、数字或下划线结尾，紧跟的下一个字符不能再是字母、数字或下划线。 minLength: 1. maxLength: 2000. 示例：@Hero 坐在 @video_1 的桌前，拿起 @image_1 里的玩偶，用 @Narrator 的声音打招呼。
duration	integer	否	输出视频时长（秒），3–30 的整数，默认 5。 默认值：5。 minimum: 3. maximum: 30. 示例：5。
resolution	string	否	输出分辨率：720p 或 1080p，默认 720p。 默认值："720p"。 可选值：720p / 1080p。 示例：720p。
aspect_ratio	string	否	输出画面比例，可选。 - 不传且提供了任意参考素材时，使用 auto - 不传且没有任何参考素材时，使用 16:9 可选值：auto / 16:9 / 9:16 / 1:1 / 21:9。 示例：auto。
image_urls	array<string>	否	参考图，最多 10 张，需公网可访问。提示词里按数组顺序用 @image_1、@image_2… 引用。每边 300–65536 像素，宽高比 0.4–2.5。 默认值：[]。 maxItems: 10.
video_urls	array<string>	否	参考视频，最多 5 个，每个 2–30 秒。提示词里用 @video_1、@video_2… 引用。参考视频与 elements 中的视频主体合计不超过 5 个。 默认值：[]。 maxItems: 5.
keep_original_sound	boolean	否	是否保留参考视频的原声。只在传了 video_urls 时生效，默认 false。不传参考视频时固定生成原生音频。 默认值：false。 示例：false。
elements	array<object>	否	仅本次任务使用的主体，最多 7 个，其中视频主体最多 3 个。提示词里用 @名称 引用。image_urls、video_urls、elements、voices 四类按条数合计不超过 15。 默认值：[]。 maxItems: 7.
elements[].name	string	是	提示词里 @名称 引用用的名字。1–20 个字符，仅限中文、字母、数字、下划线。与 elements、voices 中的其它名称不能重复（不区分大小写）。不能使用保留名（不区分大小写，N 为数字）：image_N、video_N、keyframe_N、object_N、audio_N、first_frame、last_frame。 pattern: ^[一-龥A-Za-z0-9_]{1,20}$. 示例：Hero。
elements[].image_urls	array<string>	否	图片主体用的 2–4 张公网可访问图片，不能与 video_url 同时传。第 1 张是主图（正脸或主视角），其余是副图。 minItems: 2. maxItems: 4.
elements[].video_url	string	否	视频主体用的人物视频地址，不能与 image_urls 同时传。1 个视频，3–8 秒，单镜头连续画面（不能有剪切），最短边不小于 700 像素。 pattern: ^https?://.
elements[].tag	string	否	主体分类。图片主体可选，不传时按主图自动识别；视频主体固定为 character，传其它值会被拒绝。 可选值：character / animal / prop / costume / scene / effect / others。 示例：character。
elements[].description	string	否	可选的主体描述，最多 100 个字符。 maxLength: 100.
elements[].voice_url	string	否	可选，绑定在该主体上的参考音频。不能单独用 @ 引用，也不占 voices 名额。只有人物主体能绑定：图片主体的 tag 须为 character 或不传；视频主体不传时，若视频里有人声则自动使用。 pattern: ^https?://.
voices	array<object>	否	仅本次任务使用的独立声音参考，最多 3 个。提示词里用 @名称 引用。主体上通过 voice_url 绑定的声音与此无关，不占名额。 默认值：[]。 maxItems: 3.
voices[].name	string	是	提示词里 @名称 引用用的名字。1–20 个字符，仅限中文、字母、数字、下划线。与 elements、voices 中的其它名称不能重复（不区分大小写）。不能使用保留名（不区分大小写，N 为数字）：image_N、video_N、keyframe_N、object_N、audio_N、first_frame、last_frame。 pattern: ^[一-龥A-Za-z0-9_]{1,20}$. 示例：Narrator。
voices[].audio_url	string	是	公网可访问的参考音频地址，必填。识别不到可用声音时任务失败。 pattern: ^https?://.

请求示例

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": "@image_1 中的人物缓缓转头看向镜头。",
  "duration": 3,
  "resolution": "720p",
  "image_urls": [
    "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-tob-release-note/ch12_2_dark_hair_fighter_ref.png"
  ]
}'

{
  "model": "kling-4.0/reference-to-video",
  "prompt": "@image_1 中的人物缓缓转头看向镜头。",
  "duration": 3,
  "resolution": "720p",
  "image_urls": [
    "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-tob-release-note/ch12_2_dark_hair_fighter_ref.png"
  ]
}

计费与默认值

• 两条线路使用相同的对外字段及计费规则。省略 duration / resolution 时为 5 秒 / 720p。不传帧仍支持纯文生视频，官方线路会改用全能接口承接；传帧时忽略 aspect_ratio。
• 不带视频输入：积分 = 向上取整（基础费率 × 输出秒数 × 当前定价系数）。720p 基础费率为 28.5 积分/秒，1080p 为 42.5。按当前系数，720p 的 3 秒为 112 积分，5 秒为 186；价格可能调整，以服务端报价为准。
• 带 video_urls 或视频主体（elements[].video_url）时，合计所有输入视频时长，保留小数秒；计费秒数 = 输出秒数 + max（输入总秒数，输出秒数）。720p 基础费率改为 17，1080p 改为 25.5，再乘当前定价系数，仅最终积分向上取整。图片主体、独立声音不增加输入视频秒数。
• 任一视频时长探测失败时，网关保守地至少按 150 秒输入计价。例如输出 5 秒、720p、参考视频无法探测，当前报价为 3426 积分；成功时按该报价收费，并非自动按实际时长退差价的预估。请使用可公开下载且能探测时长的素材；生成失败原路退款。
• 默认生成原生音频，没有通用的关闭音频参数。keep_original_sound 默认 false，只作用于 video_urls；明确要求保留原声而所选上游没有对应开关时，会由兼容线路承接。

下方响应以 720p、3 秒为例。usage.credits 为实扣积分，balance 为剩余积分，latencyMs 为请求耗时（毫秒）；rate、seconds、resolution、source 为报价口径。全能参考还返回 inputSeconds，带视频时另有 inputVideos；数值和可选字段随请求变化。created 为秒级 Unix 时间戳，data 为可下载视频地址列表。

响应

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

{
  "ok": true,
  "created": 1792134000,
  "data": [
    {
      "url": "https://modelfold.ai/uploads/outputs/result.mp4"
    }
  ],
  "usage": {
    "credits": 112,
    "rate": 28.5,
    "seconds": 3,
    "resolution": "720p",
    "source": "no_video",
    "balance": 888,
    "latencyMs": 120000,
    "inputSeconds": 0
  }
}