# 可灵 3.0 自定义主体 API

> 可灵 3.0 高级自定义主体（advanced custom elements / 主体管理）：用参考图或参考视频定义可复用主体，产出 element_id 供 Omni / 动作控制引用，渠道级能力、不计费

高级自定义主体（advanced custom elements，又称**主体管理**）用一组**参考图**或一段**参考视频**定义一个**可复用主体**（一个角色 / 一个物体 / 一个 IP 形象）。创建并查询成功后拿到的 `element_id`，可直接在 [Omni 多模态生成](/api-capabilities/kling/video-generation#omni-多模态)与[动作控制](/api-capabilities/kling/video-generation#动作控制)中通过 `element` 素材引用，让同一主体在多次生成里保持一致。

与 Omni 里 `refer_image` 传图后**由网关临时创建主体**不同，这里创建的是**显式、可复用、可命名**的主体：一次创建，多次引用。

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

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

## 创建自定义主体

`POST /general/advanced-custom-elements`

用参考图（`image_refer`）或参考视频（`video_refer`）创建一个主体。

```bash 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": "..." }` |

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

`element_video_list`（`video_refer`）：

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

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

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

```json
{
  "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`。

```bash 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 }` |

成功响应示例：

```json
{
  "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`，无需自己创建。

```bash 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` 同样是网关签名令牌。

```json
{
  "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](/api-capabilities/kling/video-generation#omni-多模态)（`POST /omni-video/{model}`）或[动作控制](/api-capabilities/kling/video-generation#动作控制)（`POST /motion-control/{model}`）的 `contents` 里用 `element` 素材引用它：

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

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

## 计费

<Info>
主体管理（创建 / 查询 / 预置列表）是**渠道级能力，不计费**：这些调用不扣费、不产生消费日志。实际产生费用的是随后用 `element_id` 发起的[视频生成](/api-capabilities/kling/overview#模型定价)（Omni / 动作控制按分辨率 × 时长计费）。
</Info>

## 在线调试（试一试）

<CardGroup cols={2}>
  <Card title="创建自定义主体" icon="flask" href="/api-reference/kling/create-custom-element">
    POST /general/advanced-custom-elements
  </Card>
  <Card title="查询自定义主体" icon="flask" href="/api-reference/kling/get-custom-element">
    GET /general/advanced-custom-elements/{task_id}
  </Card>
  <Card title="查询官方预置主体" icon="flask" href="/api-reference/kling/list-preset-elements">
    GET /general/advanced-presets-elements
  </Card>
</CardGroup>

## 相关文档

<CardGroup cols={2}>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/kling/video-generation">
    Omni / 动作控制里如何用 element 引用主体
  </Card>
  <Card title="能力总览与定价" icon="circle-info" href="/api-capabilities/kling/overview">
    模型清单、技术规格、计费规则
  </Card>
</CardGroup>