创建自定义主体

用图片或一段视频创建可灵自定义主体，得到的主体 ID 填入视频请求的 `subjects[].id`。

POST/v1/kling/subjects

image_refer 需要一张正面图加 1–3 张辅助参考图；video_refer 需要一段视频，可选绑定 voice_id。两种方式的字段不能混用。所有地址都必须是公网 HTTP(S) 绝对地址，规则同素材定位。

创建是异步任务，目前不计费。提交返回 202 与任务 id（object 为 kling.subject.task），用查询视频任务轮询；完成后结果里带 element_ids（主体 ID 数组）与 elements（每项含 id，可能带 info）。

请求体是严格的 JSON 格式：表外字段在任务创建前返回 400。字段校验全部在提交前完成，不合规不会创建任务。

创建自定义主体

curl https://api.hop-base.com/v1/kling/subjects \
  -H "Authorization: Bearer $HOPBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "橘猫",
    "description": "短毛橘猫，绿色眼睛",
    "reference_type": "image_refer",
    "frontal_image_url": "https://cdn.example.com/cat-front.png",
    "reference_image_urls": [
      "https://cdn.example.com/cat-side.png",
      "https://cdn.example.com/cat-back.png"
    ]
  }'

202application/json

{
  "id": "ktEXAMPLE",
  "object": "kling.subject.task",
  "status": "queued",
  "created": 1790000000
}

请求头

Authorization:必填string

Bearer sk-…：控制台「API 密钥」里创建的密钥，所属分组须包含请求的模型

请求体参数JSON

name:必填string

主体名称，前后空白会被去掉

长度1–20 字符

description:可选string

主体描述

长度≤ 100 字符

reference_type:必填string

image_refer 用图片创建，video_refer 用一段视频创建

可选值image_refervideo_refer

frontal_image_url:可选string

正面图地址；image_refer 必填，video_refer 不能带，必须是公网可访问的绝对 HTTP(S) 地址

长度≥ 1 字符

reference_image_urls:可选array of string

辅助参考图地址；image_refer 必填，1–3 个，不能与正面图重复、彼此也不能重复；video_refer 不能带

数量1–3 项

video_url:可选string

视频地址；video_refer 必填，image_refer 不能带，必须是公网可访问的绝对 HTTP(S) 地址

长度≥ 1 字符

voice_id:可选string

绑定到主体的音色，仅 video_refer 可用

tag_ids:可选array of string

用于归类主体的标签 ID，每项非空且不重复

202已受理，返回主体创建任务

id:可选string

任务 ID，用 GET /v1/video/tasks/{task_id} 轮询

object:可选string

固定为 kling.subject.task

status:可选string

固定为 queued

created:可选integer

创建时间，Unix 秒

错误

400提交前校验失败，不创建任务。原文如： request body does not match the JSON contract: …：JSON 不合法、带了表外字段或请求体后面还有第二个 JSON 值 name is required、name cannot exceed 20 characters、description cannot exceed 100 characters reference_type must be image_refer or video_refer reference_type=image_refer does not accept video_url、voice_id is only supported with reference_type=video_refer、reference_type=video_refer does not accept image references reference_image_urls must contain 1 to 3 reference images different from the frontal image、reference_image_urls[<序号>] duplicates the frontal image or another reference image <字段> is required、<字段>.url must be a publicly accessible absolute http(s) URL tag_ids[<序号>] cannot be empty、tag_ids[<序号>] is duplicated

401没带密钥、密钥无效或已过期（missing_api_key / invalid_api_key / api_key_expired）

请求头

请求体参数JSON

返回

错误

相关页面