可灵 3.0 自定义主体 API

高级自定义主体（advanced custom elements，又称主体管理）用一组参考图或一段参考视频定义一个可复用主体（一个角色 / 一个物体 / 一个 IP 形象）。创建并查询成功后拿到的 element_id，可直接在 Omni 多模态生成与动作控制中通过 element 素材引用，让同一主体在多次生成里保持一致。与 Omni 里 refer_image 传图后由网关临时创建主体不同，这里创建的是显式、可复用、可命名的主体：一次创建，多次引用。

主体管理与视频任务在三处不同，接入时请注意：

task_id 是网关签名的不透明令牌：创建 / 预置列表返回的 data.task_id 恒以 ace_ 开头，不是上游原始 ID。后续查询必须原样使用该令牌——它无状态地把查询路由回创建时的同一渠道（创建与查询是两次独立请求，令牌自带渠道信息才能命中同一上游账号）。请勿自行拼接或改写。
渠道级能力、不计费：主体的创建 / 查询 / 预置列表不扣费，也不是任务提交，不走计费管线。
路径可选 /v1 前缀：三个端点均可写成 /v1/general/advanced-custom-elements...，带与不带行为一致。

创建自定义主体

POST /general/advanced-custom-elements 用参考图（image_refer）或参考视频（video_refer）创建一个主体。

cURL

curl -X POST "https://api.looprouter.com/general/advanced-custom-elements" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "element_name": "my-hero",
    "element_description": "一位身穿红色斗篷的动画英雄",
    "reference_type": "image_refer",
    "element_image_list": {
      "frontal_image": "https://example.com/hero-front.png",
      "refer_images": [
        { "image_url": "https://example.com/hero-side.png" },
        { "image_url": "https://example.com/hero-back.png" }
      ]
    },
    "tag_list": [{ "tag_id": "o_101" }]
  }'

参数	类型	必填	说明
`element_name`	string	是	主体名称，长度 ≤ 20
`element_description`	string	是	主体描述，长度 ≤ 100
`reference_type`	string	是	`image_refer`（用参考图）/ `video_refer`（用参考视频）
`element_image_list`	object	条件	`reference_type=image_refer` 时必填，见下
`element_video_list`	object	条件	`reference_type=video_refer` 时必填，见下
`element_voice_id`	string	否	绑定的音色 ID，仅 `video_refer` 主体可绑定
`tag_list`	array	否	主体标签，元素为 `{ "tag_id": "o_101" }`，`tag_id` 枚举 `o_101`~`o_108`

element_image_list（image_refer）：

字段	类型	说明
`frontal_image`	string	1 张正脸图 URL
`refer_images`	array	1~3 张其他角度参考图，元素为 `{ "image_url": "..." }`

图片要求：.jpg / .jpeg / .png 或 Base64URL；单张 ≤ 10MB，短边 ≥ 300px，宽高比 1:2.5 ~ 2.5:1。

element_video_list（video_refer）：

字段	类型	说明
`refer_videos`	array	至多 1 段参考视频，元素为 `{ "video_url": "..." }`

视频要求：MP4 / MOV，时长 3~8 秒，宽高比 16:9 或 9:16，≤ 200MB。

提交成功返回创建 ack，data.task_id 为网关签名令牌（创建 ack 无 task_result，用该令牌查询才拿到 element_id）：

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "202608131429431085002008268d9d6gxQi3MuZ",
  "data": {
    "task_id": "ace_NjA6dHNrLWFiYzEyMw.4f3c…",
    "task_status": "submitted",
    "created_at": 1786372183136,
    "updated_at": 1786372183136
  }
}

查询自定义主体

GET /general/advanced-custom-elements/{task_id} 用创建返回的 task_id 令牌查询主体。任务状态机：submitted → processing → succeed / failed。

cURL

curl "https://api.looprouter.com/general/advanced-custom-elements/ace_NjA6dHNrLWFiYzEyMw.4f3c…" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY"

响应 data 字段：

字段	类型	说明
`task_id`	string	网关签名令牌（回显你持有的那个 `ace_` 令牌）
`task_status`	string	`submitted` / `processing` / `succeed` / `failed`
`task_status_msg`	string	失败原因（若有）
`task_result`	object	成功时出现，含 `elements[]`
`created_at` / `updated_at`	int	Unix 毫秒时间戳

task_result.elements[] 元素（关键字段）：

字段	类型	说明
`element_id`	number	主体 ID，用于 Omni / 动作控制的 `element` 引用
`element_name`	string	主体名称
`element_description`	string	主体描述
`element_type`	string	`image_refer` / `video_refer`（注意：响应里是 `element_type`，创建请求里是 `reference_type`）
`element_image_list`	object	参考图集合（`image_refer` 主体）
`element_video_list`	object	参考视频集合（`video_refer` 主体）
`element_voice_info`	object	绑定音色信息（若有）：`voice_id` / `voice_name` / `trial_url`
`tag_list`	array	标签，元素为 `{ id, name, description }`

成功响应示例：

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "202608131430078425945008268d9d6ZEra2TSv",
  "data": {
    "task_id": "ace_NjA6dHNrLWFiYzEyMw.4f3c…",
    "task_status": "succeed",
    "task_result": {
      "elements": [
        {
          "element_id": 171,
          "element_name": "my-hero",
          "element_description": "一位身穿红色斗篷的动画英雄",
          "element_type": "image_refer",
          "element_image_list": {
            "frontal_image": "https://example.com/hero-front.png",
            "refer_images": [
              { "image_url": "https://example.com/hero-side.png" },
              { "image_url": "https://example.com/hero-back.png" }
            ]
          },
          "tag_list": [
            { "id": "o_101", "name": "animal", "description": "The content of description." }
          ]
        }
      ]
    },
    "created_at": 1786372183000,
    "updated_at": 1786372184000
  }
}

查询官方预置主体

GET /general/advanced-presets-elements 分页查询可灵官方预置主体列表，可直接引用其 element_id，无需自己创建。

cURL

curl "https://api.looprouter.com/general/advanced-presets-elements?pageNum=1&pageSize=30" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY"

查询参数	类型	必填	说明
`pageNum`	int	否	页码，默认 1（缺省或非正数交由上游取默认值）
`pageSize`	int	否	每页条数，默认 30（缺省或非正数交由上游取默认值）

data 恒为数组，每项结构同「查询自定义主体」的 data（含 task_result.elements[]），每条的 task_id 同样是网关签名令牌。

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "202608131431556730001008268d9d6ListVz",
  "data": [
    {
      "task_id": "ace_cHJlc2V0OjE2MA.9a1b…",
      "task_status": "succeed",
      "task_result": {
        "elements": [
          { "element_id": 160, "element_name": "preset-cat", "element_type": "image_refer" }
        ]
      },
      "created_at": 1786372183000,
      "updated_at": 1786372184000
    }
  ]
}

用 element_id 生成视频

拿到 element_id 后，在 Omni（POST /omni-video/{model}）或动作控制（POST /motion-control/{model}）的 contents 里用 element 素材引用它：

{
  "contents": [
    { "type": "prompt", "text": "英雄在雨中奔跑" },
    { "type": "element", "element_id": 171 }
  ],
  "settings": { "resolution": "1080p", "duration": 5 }
}

element 素材传数字 element_id（查询响应里的数字，而非 ace_ 令牌）。ace_ 令牌只用于主体查询端点；生成端点引用主体用的是 element_id。

计费

主体管理（创建 / 查询 / 预置列表）是渠道级能力，不计费：这些调用不扣费、不产生消费日志。实际产生费用的是随后用 element_id 发起的视频生成（Omni / 动作控制按分辨率 × 时长计费）。

在线调试（试一试）

创建自定义主体

POST /general/advanced-custom-elements

查询自定义主体

GET /general/advanced-custom-elements/

查询官方预置主体

GET /general/advanced-presets-elements

视频生成 API

Omni / 动作控制里如何用 element 引用主体

能力总览与定价

模型清单、技术规格、计费规则

产品基础

视频模型

图片模型

可灵 3.0 自定义主体 API

创建自定义主体

查询自定义主体

查询官方预置主体

用 element_id 生成视频

计费

在线调试（试一试）

创建自定义主体

查询自定义主体

查询官方预置主体

相关文档

视频生成 API

能力总览与定价

​创建自定义主体

​查询自定义主体

​查询官方预置主体

​用 element_id 生成视频

​计费

​在线调试（试一试）

创建自定义主体

查询自定义主体

查询官方预置主体

​相关文档

视频生成 API

能力总览与定价

创建自定义主体

查询自定义主体

查询官方预置主体

用 element_id 生成视频

计费

在线调试（试一试）

相关文档