Modelink

Kling 主体（Element）使用教程

「主体（Element）」是 Kling 视频生成里用来锁定同一形象/角色的能力：把某个主体喂给模型，生成的视频就会稳定复用这个形象。Kling 主体有两种用法：

形态怎么用适用场景
内联自动创建（推荐）视频请求里直接内联传主体源图 elements: [{ frontal_image_url, reference_image_urls }]，平台当场自动创建临时主体、生成完即删一次性生成、无需长期管理形象、想直接对齐 Kling/fal 官方请求体
预创建 + 引用先调 POST /v1/assets 上传主体、审核通过拿到 qasset://，再在视频请求里用 elements: [{ element_id }] 引用同一形象跨多次任务反复复用、需要集中管理素材库

本教程主讲内联自动创建，预创建引用在文末简要说明。

信息

各模型 / 接口对主体（elements）的具体支持范围与数量上限以可灵官方能力地图为准：Kling 视频能力地图。

内联自动创建

在支持的视频接口里，elements 数组的每一项直接内联传主体源图，平台会当场为每个主体自动创建一个临时主体并注入本次生成，视频生成结束后自动删除。

字段说明

elements[] 每一项是两种互斥形态二选一（每项只能命中一种）：

内联自动创建形态（本教程主推）：

字段类型说明
frontal_image_urlstring必填：主体正面图 URL，需公网可访问
reference_image_urlsstring[]选填：其他角度参考图 URL 列表，0~3 张

引用形态（见文末）：

字段类型说明
element_idstring / number官方主体库数字 ID 或 qasset:// 素材引用

警告

同一项里 element_id 与 frontal_image_url/reference_image_urls 不可混填，两者都不填也会返回 400。一个 elements 数组内可以逐项混用「内联」和「引用」两种形态。

在提示词中引用主体

elements 是有序的，可在 prompt 里按位置引用具体主体：

  • 用 @Element1、@Element2 … 依次对应 elements[0]、elements[1]。
  • 或用 <<<element_1>>>、<<<element_2>>> 语法（序号从 1 开始）。

关键特性

  • 零素材管理：无需预先调 /v1/assets，源图直接写进视频请求。
  • 用完即删：临时主体是本次生成的中间产物，生成结束后自动删除，不会出现在 GET /v1/assets 素材列表里，也不单独计费。
  • 对齐官方：frontal_image_url + reference_image_urls 与 Kling / fal 官方主体请求体一致。

三类接口示例

接入域名：中国大陆 https://api.qnaigc.com，海外 https://api.modelink.ai。以下示例用大陆域名，$QINIU_API_KEY 替换为你的 API Key。

1. 图生视频（Image-to-Video）

以最新的 o3 为例：起始帧 + 内联一个主体，生成时用 @Element1 引用。

curl "https://api.qnaigc.com/queue/fal-ai/kling-video/o3/pro/image-to-video" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $QINIU_API_KEY" \
    -d '{
        "prompt": "@Element1 走进画面，转身面向镜头微笑",
        "image_url": "https://example.com/start-frame.png",
        "duration": "5",
        "elements": [
            {
                "frontal_image_url": "https://example.com/subject-front.png",
                "reference_image_urls": ["https://example.com/subject-side.png"]
            }
        ]
    }'

2. 参考生视频（Reference-to-Video）

o3 参考生视频：不需要首尾帧，参考来自 image_urls 与内联的 elements。可内联多个主体。

curl "https://api.qnaigc.com/queue/fal-ai/kling-video/o3/pro/reference-to-video" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $QINIU_API_KEY" \
    -d '{
        "prompt": "@Element1 和 @Element2 从两侧走进同一场景对话",
        "elements": [
            {
                "frontal_image_url": "https://example.com/person-a-front.png",
                "reference_image_urls": ["https://example.com/person-a-side.png"]
            },
            {
                "frontal_image_url": "https://example.com/person-b-front.png"
            }
        ],
        "duration": "8",
        "aspect_ratio": "16:9"
    }'

3. 动作控制（Motion Control）

警告

动作控制的主体（elements）面部绑定仅 v3 支持（v2.6 不支持，也没有 o1/o3 动作控制接口）。因此本示例用 v3。

curl "https://api.qnaigc.com/queue/fal-ai/kling-video/v3/pro/motion-control" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $QINIU_API_KEY" \
    -d '{
        "prompt": "让 @Element1 按参考视频的动作跳舞",
        "image_url": "https://example.com/character.png",
        "video_url": "https://example.com/motion-reference.mp4",
        "character_orientation": "front",
        "elements": [
            {
                "frontal_image_url": "https://example.com/face-front.png"
            }
        ]
    }'

三个接口都返回 fal 队列风格的任务响应，用返回的 request_id 调 GET /queue/fal-ai/kling-video/requests/{request_id}/status 轮询、GET /queue/fal-ai/kling-video/requests/{request_id} 取结果。

支持内联 elements 的接口清单

以下接口在平台侧已接入内联主体（{mode} 取 std / pro，部分支持 4k）：

类别接口路径支持模型
图生视频/queue/fal-ai/kling-video/{model}/{mode}/image-to-videov3、o1、o3
参考生视频/queue/fal-ai/kling-video/{model}/{mode}/reference-to-videoo1、o3
文生视频/queue/fal-ai/kling-video/o1/{mode}/text-to-video仅 o1
视频生视频（编辑 / 参考）/queue/fal-ai/kling-video/{model}/{mode}/video-to-video/{edit|reference}o1、o3
动作控制/queue/fal-ai/kling-video/v3/{mode}/motion-control仅 v3

警告

以下接口不支持 elements：o3/v3/v2.6/v2.5-turbo/v3-turbo 的文生视频（o1 除外）、v2.5-turbo/v2.6/v3-turbo 的图生视频、v2.6 动作控制。传入会被忽略或按各接口 schema 处理。

预创建 + 引用（对比形态）

如果同一形象要跨多次任务反复复用，可以先把它建成长期素材再引用：

  1. 调 POST /v1/assets（model=kling-element-v1）上传主体正面图与参考图，平台异步审核。
  2. 轮询 GET /v1/assets/{qassetid} 直到 status=approved，拿到 qasset://qasset-xxx。
  3. 在视频请求里用引用形态 element_id 引用（可与内联形态混用）：
"elements": [
    { "element_id": "qasset://qasset-uid001-1716100100000000000" },
    { "element_id": 313464315622507 }
]

element_id 支持两种引用：qasset:// 引用你在平台创建的素材，或直接填 Kling 官方主体库的数字 ID。素材的完整上传、审核、分组流程见素材管理接口文档。

约束与常见错误

  • 形态二选一：同项混填 element_id 与内联字段，或两者都不填 → 400。
  • 参考图上限：reference_image_urls 每项最多 3 张，超过 → 400。
  • URL 安全：内联的 frontal_image_url / reference_image_urls 走 SSRF 白名单，内网地址或不可达 URL 会被拒。
  • 主体数量上限：图生视频最多 3 个主体；其余接口随模型 / 模式变化，超限由 Kling 侧报错，以可灵能力地图为准。
  • 与音色互斥：elements 与 voice_list 不能在同一请求共存。

Last updated

© 2026 Modelink. All rights reserved.

构建来自Clarify