主体管理

/v1/general/*：创建、查询和删除 Kling 主体，以及查询官方主体库；创建异步，用 GET /v1/general/advanced-custom-elements/{id} 查询

POST/v1/general/advanced-custom-elements

GET/v1/general/advanced-custom-elements/{id}

GET/v1/general/advanced-custom-elements

GET/v1/general/advanced-presets-elements

POST/v1/general/delete-advanced-elements

创建可在 Kling 4.0 全能参考中引用的主体（element_id），并查询、删除自己的主体，查询官方主体库。接口风格与可灵官方一致，属于旧版风格（响应字段 task_id / task_status）。

项	值
模型	`kling-custom-elements`
模式	创建为异步（提交 → 轮询 `GET /v1/general/advanced-custom-elements/{id}`）；列表、官方库、删除为同步
计费	创建按次计费，价格以定价页为准；查询、列表和删除不向用户计费

快速开始

curl https://api.vibelab.me/v1/general/advanced-custom-elements \
  -H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"element_name":"小猫","element_description":"白色长毛猫","reference_type":"image_refer","element_image_list":{"frontal_image":"https://example.com/front.jpg","refer_images":[{"image_url":"https://example.com/side.jpg"}]},"external_task_id":"my-cat"}'

响应示例：

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "6a0d571e-d36c-4811-bb2b-698c94b19a8c",
  "data": {
    "task_id": "893605946402811985",
    "task_status": "submitted",
    "task_info": {
      "external_task_id": "my-cat"
    },
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  }
}

data.task_id 是创建任务 ID，不是主体 ID。轮询见响应。

请求参数

创建主体请求体

认证为 Authorization: Bearer $LOOPTOKEN_API_KEY，Content-Type: application/json。

参数	类型	必填	默认	说明
`element_name`	string	是	-	不超过 20 个字符
`element_description`	string	是	-	不超过 100 个字符
`reference_type`	string	是	-	`image_refer` 或 `video_refer`
`element_image_list`	object	`image_refer` 必填	-	`frontal_image`（正面图）加 1–3 张 `refer_images[].image_url`
`element_video_list`	object	`video_refer` 必填	-	`refer_videos: [{"video_url": "URL"}]`，仅 1 段
`element_voice_id`	string	否	-	绑定自己的音色，或已通过官方列表查询过的官方音色
`tag_list`	array	否	-	`[{"tag_id":"o_102"}]`
`callback_url`	string	否	-	任务状态变化时的 HTTPS 回调地址（顶层字段），见回调
`external_task_id`	string	否	-	自定义任务 ID，同一账号下不可重复（顶层字段）

图片：URL 或 Base64，JPG/JPEG/PNG，≤ 10MB，宽高 ≥ 300px，比例 1:2.5–2.5:1。
视频：MP4/MOV，3–8 秒，1080p，16:9 或 9:16，≤ 200MB，仅支持写实人形；视频包含人声时上游可能自动定制并绑定音色。
标签 o_101–o_108 依次为热梗、人物、动物、道具、服饰、场景、特效、其他。

其他接口参数

接口	参数	类型	必填	默认	说明
`GET .../advanced-custom-elements/{id}`	`id`（路径）	string	是	-	创建任务 ID 或自定义任务 ID
`GET .../advanced-custom-elements`、`GET .../advanced-presets-elements`	`pageNum`	integer	否	`1`	`1`–`1000`
同上	`pageSize`	integer	否	`30`	`1`–`500`
`POST .../delete-advanced-elements`	`element_id`	string	是	-	要删除的主体 ID

响应

轮询单个查询，data.task_status 为 submitted、processing、succeed（终态）、failed（终态）。

字段	类型	说明
`data.task_id`	string	创建任务 ID
`data.task_status`	string	任务状态
`data.task_info.external_task_id`	string	自定义任务 ID
`data.task_result.elements[].element_id`	string	成功后的主体 ID，在 Omni 的 `contents` 中以 `element` 素材引用

列表（GET .../advanced-custom-elements）只返回当前用户的创建任务记录，不受 30 天限制；官方列表实时查询上游。
删除成功后 LoopToken 立即停止允许引用该主体，原创建任务快照保留历史结果。
不返回上游成本字段。

计费

创建时预扣一次，失败任务退款；查询、列表和删除不收费。

错误

创建时的参数校验返回 400 / 1201，其余为本页特有的错误：

HTTP	`code`	触发场景	处理
400	`1201`	`element_name is required and must be a string` / `element_description is required and must be a string`	补齐必填字段
400	`1201`	`element_name must not exceed 20 characters` / `element_description must not exceed 100 characters`	缩短文本
400	`1201`	`reference_type must be image_refer or video_refer`	传二者之一
400	`1201`	`element_image_list requires frontal_image and 1-3 refer_images` / `refer_images require image_url`	补正面图，参考图 1–3 张且都带 `image_url`
400	`1201`	`element_video_list requires exactly one refer_videos entry with video_url`	`refer_videos` 恰好 1 项且带 `video_url`
400	`1201`	`invalid pageNum` / `invalid pageSize`（列表）	页码 `1`–`1000`，每页 `1`–`500`
400	`1201`	`invalid JSON body` / `asset ID is required`（删除）	请求体传 `{"element_id":"..."}`
404	`1203`	`asset not found`（删除）：不是自己创建的主体，或渠道不可用	官方主体不能删除，核对 `element_id`
404	`1203`	`task not found`（查询）	核对任务 ID
503	`5001`	没有能使用所引用音色（`element_voice_id`）的渠道	确认音色是自己创建的，或先查询官方列表

通用错误见 Kling 错误。

注意事项

引用主体 → 只能引用自己创建的主体，或已通过官方列表核实的预置主体。
删除 → 只有创建者可以删除自定义主体，官方主体不能删除。
渠道绑定 → 主体与音色都绑定到原上游渠道账号，不能跨渠道账号引用。

主体管理

本页内容