# 可灵主体与音色

> 创建、查询、复用与删除可灵主体和音色，含平台资源 ID、费用及结果未知处理。

先创建可复用的主体或音色，等创建任务成功后取得 `kr_...` 资源 ID，再在[可灵视频](native-kling.md)中引用。创建任务 ID、资源 ID、提示词内的引用名称分别有不同用途，不能互换。

<a id="native-kling-resources-h-019dc94f"></a>

## 接口与鉴权

Base URL：`https://platform.sgt.site/kling`

所有请求使用企业内的虚拟密钥：`Authorization: Bearer YOUR_VIRTUAL_KEY`。创建和删除还需 `Content-Type: application/json`。该密钥当前须有 `kling-3.0-omni` 的使用权限；创建前还需有相应的主体或音色创建价格及足够预算。请求体不传 `model`。

| 方法 | 相对于 Base URL 的路径 | 用途与返回 |
| --- | --- | --- |
| POST | `/v1/general/advanced-custom-elements` | 创建主体，返回平台创建任务 ID |
| GET | `/v1/general/advanced-custom-elements/{id}` | 按创建任务 ID 或自定义任务 ID 查询，成功后返回 `element_id` |
| GET | `/v1/general/advanced-custom-elements` | 当前调用主体可见的主体创建任务列表 |
| GET | `/v1/general/advanced-presets-elements` | 官方预置主体目录，返回可引用的平台主体 ID |
| POST | `/v1/general/delete-advanced-elements` | 删除自建主体，返回独立的删除任务 ID |
| POST | `/v1/general/custom-voices` | 创建音色，返回平台创建任务 ID |
| GET | `/v1/general/custom-voices/{id}` | 按创建任务 ID 或自定义任务 ID 查询，成功后返回 `voice_id` |
| GET | `/v1/general/custom-voices` | 当前调用主体可见的音色创建任务列表 |
| GET | `/v1/general/presets-voices` | 官方预置音色目录，返回可引用的平台音色 ID |
| POST | `/v1/general/delete-voices` | 删除自建音色，返回独立的删除任务 ID |

查询与复用仍会校验当前权限。资源属于创建它的用户及企业；知道另一个用户的 ID 不代表可以查看、引用或删除。调用方只能使用本接口返回的 `kr_...` ID，不能填写供应商账号里的原始资源 ID。

<a id="native-kling-resources-h-d0131c90"></a>

## 创建主体

`POST /v1/general/advanced-custom-elements` 支持以多张图片或一段视频创建主体，两种输入不能同时提供。一次调用创建一个主体。

| 字段 | 类型 | 必填条件与说明 |
| --- | --- | --- |
| `element_name` | string | 必填，非空，最多 20 个字符 |
| `element_description` | string | 必填，非空，最多 100 个字符 |
| `reference_type` | string | 必填，`image_refer` 或 `video_refer` |
| `element_image_list` | object | `image_refer` 必填；此时不传 `element_video_list` |
| `element_image_list.frontal_image` | string | 正面参考图，HTTP(S) URL 或图片 Base64 |
| `element_image_list.refer_images` | object[] | 1–3 张其他角度或细节参考图，每项为 `{"image_url":"..."}` |
| `element_video_list` | object | `video_refer` 必填；此时不传 `element_image_list` |
| `element_video_list.refer_videos` | object[] | 恰好一项 `{"video_url":"https://..."}` |
| `element_voice_id` | string | 可选，绑定一个当前主体可见的 `kr_...` 音色 ID；不传则不指定已有音色 |
| `tag_list` | object[] | 可选，每项为 `{"tag_id":"o_102"}`；允许值见下表 |
| `callback_url` | string | 可选，任务结果回调地址，必须通过平台的回调目标校验；回调使用平台任务 ID |
| `external_task_id` | string | 可选，最多 255 字节；当前用户及企业的可灵任务中须唯一，可用于查询，不能作为重复提交的幂等保证 |

不接受未知字段或顶层字段值 `null`。图片可使用可访问 URL、原始 Base64 或 `data:image/png;base64,...` / `data:image/jpeg;base64,...`。素材 URL 不能包含用户名或密码。

| 标签 | 含义 | 标签 | 含义 |
| --- | --- | --- | --- |
| `o_101` | 热梗 | `o_102` | 人物 |
| `o_103` | 动物 | `o_104` | 道具 |
| `o_105` | 服饰 | `o_106` | 场景 |
| `o_107` | 特效 | `o_108` | 其他 |

下面创建一个由正面图和侧面图定义的主体。示例中的素材 URL 需替换为你有权使用且模型可以访问的文件。

```bash
curl -X POST 'https://platform.sgt.site/kling/v1/general/advanced-custom-elements' \
  -H 'Authorization: Bearer YOUR_VIRTUAL_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "element_name": "演示人物",
  "element_description": "穿蓝色衬衫的成年人，保持面部和服装一致",
  "reference_type": "image_refer",
  "element_image_list": {
    "frontal_image": "https://media.example.com/person-front.jpg",
    "refer_images": [{"image_url": "https://media.example.com/person-side.jpg"}]
  },
  "tag_list": [{"tag_id": "o_102"}],
  "external_task_id": "demo-person-create-001"
}
JSON
```

受理响应示例：

```json
{
  "code": 0,
  "message": "",
  "request_id": "req_example",
  "data": {
    "task_id": "task_example_create",
    "task_status": "submitted",
    "task_info": {"external_task_id": "demo-person-create-001"},
    "created_at": 1792022400000,
    "updated_at": 1792022400000
  }
}
```

这表示创建已受理，尚不能用 `task_example_create` 生成视频。按下文查询，取得成功结果里的 `element_id`。

从视频创建主体的完整示例：

```bash
curl -X POST 'https://platform.sgt.site/kling/v1/general/advanced-custom-elements' \
  -H 'Authorization: Bearer YOUR_VIRTUAL_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "element_name": "演示视频人物",
  "element_description": "保留参考视频人物的脸部、服饰和动作特征",
  "reference_type": "video_refer",
  "element_video_list": {
    "refer_videos": [{"video_url": "https://media.example.com/person-reference.mp4"}]
  }
}
JSON
```

官方素材要求：图片为 JPEG/PNG，单张不超过 10 MB，宽高均至少 300 px，比例在 1:2.5 至 2.5:1；其他参考图应与正面图有差异。视频为 MP4/MOV，3–8 秒、1080p、16:9 或 9:16，最多 200 MB，目前用于写实人形主体。有声视频含人声时，模型可能创建并绑定音色。远程文件的格式、尺寸、时长和内容由模型进一步检查。视频创建的主体用于支持此类主体的 Omni 模型，不能假定所有视频模型都支持。参见[可灵官方主体说明](https://klingai.com/document-api/api/video/3-0-omni/elements)。

<a id="native-kling-resources-h-6f1534a5"></a>

## 创建音色

`POST /v1/general/custom-voices` 从一份音频或视频素材创建可复用音色。

| 字段 | 类型 | 必填条件与说明 |
| --- | --- | --- |
| `voice_name` | string | 必填，非空，最多 20 个字符 |
| `voice_url` | string | 必填，模型可访问的 HTTP(S) 音频或视频 URL |
| `callback_url` | string | 可选，规则与创建主体相同 |
| `external_task_id` | string | 可选，规则与创建主体相同 |

```bash
curl -X POST 'https://platform.sgt.site/kling/v1/general/custom-voices' \
  -H 'Authorization: Bearer YOUR_VIRTUAL_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary '{"voice_name":"演示人声","voice_url":"https://media.example.com/voice-sample.wav","external_task_id":"demo-voice-create-001"}'
```

受理响应与创建主体相同。查询路径改为 `/v1/general/custom-voices/{task_id}`，成功结果位于 `data.task_result.voices[]`：

```bash
curl 'https://platform.sgt.site/kling/v1/general/custom-voices/task_example_voice' \
  -H 'Authorization: Bearer YOUR_VIRTUAL_KEY'
```

```json
{
  "code": 0,
  "message": "",
  "request_id": "req_example",
  "data": {
    "task_id": "task_example_voice",
    "task_status": "succeed",
    "task_info": {"external_task_id": "demo-voice-create-001"},
    "created_at": 1792022400000,
    "updated_at": 1792022460000,
    "task_result": {
      "voices": [{"voice_id": "kr_example_voice", "voice_name": "演示人声", "owned_by": "platform"}]
    }
  }
}
```

官方支持 MP3/WAV/MP4/MOV，素材须只有一种清晰人声、无杂音，时长 5–30 秒。使用你有权使用的声音素材。当前入口通过 `voice_url` 创建；`video_id` 所需的历史 V2.6 有声视频、数字人或对口型来源不在本页模型范围内，提交该字段会在发送前返回 400。参见[可灵官方音色说明](https://klingai.com/document-api/api/video/3-0-omni/voice-customization)。

<a id="native-kling-resources-h-ffcd0668"></a>

## 查询创建结果

```bash
curl 'https://platform.sgt.site/kling/v1/general/advanced-custom-elements/task_example_create' \
  -H 'Authorization: Bearer YOUR_VIRTUAL_KEY'
```

也可将路径末尾替换为自己提交的 `external_task_id`；其中的特殊字符需要 URL 编码。`kr_...` 是资源 ID，不能放在这个任务查询位置。

主体创建成功示例：

```json
{
  "code": 0,
  "message": "",
  "request_id": "req_example",
  "data": {
    "task_id": "task_example_create",
    "task_status": "succeed",
    "task_info": {"external_task_id": "demo-person-create-001"},
    "created_at": 1792022400000,
    "updated_at": 1792022460000,
    "task_result": {
      "elements": [{
        "element_id": "kr_example_element",
        "element_name": "演示人物",
        "element_description": "穿蓝色衬衫的成年人，保持面部和服装一致",
        "reference_type": "image_refer",
        "owned_by": "platform"
      }]
    }
  }
}
```

| 字段 | 含义与处理 |
| --- | --- |
| `code` | 0 表示本次 API 请求成功；任务是否完成还需看 `task_status` |
| `request_id` | 本次 HTTP 请求的关联 ID，用于排查 |
| `data.task_id` | 平台任务 ID，用于后续查询 |
| `data.task_status` | `submitted` 已提交、`processing` 处理中、`succeed` 成功、`failed` 失败 |
| `data.task_status_msg` / `data.diagnostic` | 失败时可用的说明和诊断；不是生成素材 |
| `data.reconciliation_required` | 出现 `true` 表示仍需核对受理或账务证据；不要据此重复提交创建 |
| `data.created_at` / `data.updated_at` | Unix 毫秒时间戳 |
| `data.task_result.elements[].element_id` | 成功后的平台主体 ID，字符串 `kr_...` |
| `data.task_result.voices[].voice_id` | 成功后的平台音色 ID，字符串 `kr_...` |
| `element_voice_info` | 主体关联音色，存在时其中 `voice_id` 也为平台资源 ID |
| `owned_by` | `platform` 为当前调用主体的自建资源，`kling` 为官方预置资源 |
| 资源项 `status` | 删除后为 `deleted`，删除待确认时为 `deletion_pending`；此时不能用于新生成 |

`submitted`、`processing` 时不保证有 `task_result`。成功素材的描述、试听地址等附加字段按实际结果返回。平台只返回可见资源信息，不返回供应商账号信息或将供应商扣费字段作为调用方账单。

创建任务列表使用 `pageNum`、`pageSize`，默认 1 和 30，均须为 1–1000 的整数。列表按创建时间倒序，`data` 是任务数组；无可见任务时为 `[]`，没有 `total` 或游标字段。列表不包含删除控制任务。

```bash
curl 'https://platform.sgt.site/kling/v1/general/advanced-custom-elements?pageNum=1&pageSize=30' \
  -H 'Authorization: Bearer YOUR_VIRTUAL_KEY'
```

<a id="native-kling-resources-h-066fadf3"></a>

## 引用资源生成视频

将主体查询结果里的 `element_id` 放入视频请求的 `contents[].element_id`。同一项的 `id` 是本次提示词引用名称，例如 `person_1`，不是资源 ID。

```bash
curl -X POST 'https://platform.sgt.site/kling/omni-video/kling-3.0-omni' \
  -H 'Authorization: Bearer YOUR_VIRTUAL_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "contents": [
    {"type": "prompt", "text": "让 @person_1 面向镜头微笑并挥手"},
    {"type": "element", "id": "person_1", "element_id": "kr_example_element"}
  ],
  "settings": {"resolution": "720p", "duration": 5, "aspect_ratio": "16:9", "audio": "off", "multi_shot": false}
}
JSON
```

需要指定音色时，先在创建主体请求的 `element_voice_id` 中绑定 `kr_...` 音色，再按视频模型的有声生成规则引用该主体。当前视频请求不接受独立的 `contents.type=voice`。具体视频请求和计费见[可灵视频](native-kling.md)。

复用会使用该资源原来的服务身份；一份请求的多个资源必须能够在同一服务身份下使用。资源所属服务不可用、权限收回或服务身份改变时会拒绝调用，不会把资源 ID 交给另一个账号尝试。仍在生成或受理结果未知的引用会阻止删除，直至对应任务可以安全释放引用。

<a id="native-kling-resources-h-e4655511"></a>

## 官方预置资源

```bash
curl 'https://platform.sgt.site/kling/v1/general/advanced-presets-elements?pageNum=1&pageSize=30' \
  -H 'Authorization: Bearer YOUR_VIRTUAL_KEY'
```

音色目录改用 `/v1/general/presets-voices`。参数与创建任务列表相同。返回 `{"code":0,"message":"","request_id":"...","data":[...]}`；每项含 `task_status:"succeed"` 和 `task_result.elements[]` 或 `task_result.voices[]`，只包含官方预置资源。

取结果中的 `element_id` 或 `voice_id` 进行引用；目录项的 `task_id` 是目录标识，不是可轮询的创建任务。预置资源也会映射为当前调用主体可见的 `kr_...` ID。官方资源无法通过自定义资源删除接口删除。没有匹配项时 `data` 为 `[]`。

<a id="native-kling-resources-h-e21576a7"></a>

## 删除资源

删除主体与删除音色都使用 POST。请求只接受一个对应的资源 ID 字段。

```bash
curl -X POST 'https://platform.sgt.site/kling/v1/general/delete-advanced-elements' \
  -H 'Authorization: Bearer YOUR_VIRTUAL_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary '{"element_id":"kr_example_element"}'

curl -X POST 'https://platform.sgt.site/kling/v1/general/delete-voices' \
  -H 'Authorization: Bearer YOUR_VIRTUAL_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary '{"voice_id":"kr_example_voice"}'
```

成功受理示例：

```json
{"code":0,"message":"","request_id":"req_example","data":{"task_id":"task_example_delete","task_status":"submitted"}}
```

这是独立的删除任务 ID。主体删除仍通过 `/v1/general/advanced-custom-elements/task_example_delete` 查询，音色删除通过 `/v1/general/custom-voices/task_example_delete` 查询；返回 `data.resource_id` 指明被删资源。只有 `task_status=succeed` 才确认删除成功；`failed` 表示删除失败，可以重新检查资源状态。删除不退还已经完成的创建或视频生成费用。

资源仍被任务使用、已经删除或删除结果待确认时返回 409。发送后发生超时、断连、5xx 或无法确认的响应时，平台保留删除任务和资源锁，返回 503、平台 `task_id`、`resource_id` 及 `reconciliation_required:true`。此时查询同一删除任务，不要反复提交删除；未知结果不能当成已删除，也不能立即恢复为可引用资源。

<a id="native-kling-resources-h-cf6bf643"></a>

## 费用与异常处理

创建主体和创建音色各有独立的“每次成功创建”价格，与视频时长价格分开。发送前按本次有效价格预留一次费用；只有成功结果包含一个可信资源 ID 时才确认一次创建。已确认失败释放该次创建预留。视频生成另外按视频模型价格计费。查询、目录和删除没有资源创建费用。

平台按受理时的价格快照结算；创建后再改价不会改变已有任务的创建费用。缺少资源动作价格时会在发送前拒绝创建。受理结果未知、成功响应缺资源 ID 或证据矛盾时保留任务与资金，等待核对；不会自动重新 POST，也不会以查询超时为由自动释放。保存 `request_id` 和平台 `task_id` 便于核查。

| HTTP 状态 | 常见原因 | 调用方处理 |
| --- | --- | --- |
| 400 | 字段类型/素材组合错误、未知字段、回调地址不允许、当前不支持的 `video_id` | 按字段表修正；不要原样重试 |
| 401 | 未提供或无效的虚拟密钥 | 检查 Bearer 鉴权 |
| 403 | 非企业调用主体、模型权限不足、资源不属于当前主体或原服务身份不可用 | 确认当前授权和资源来源 |
| 404 | 不可见的任务/资源，或试图删除官方预置资源 | 检查 ID 类型与所属主体 |
| 409 | 自定义任务 ID 冲突，或资源正在使用、已删除、删除待确认 | 查询已有任务/资源，避免重复提交 |
| 502 / 503 | 上游或本地持久化异常，可能需要核对 | 优先保存关联 ID；有未知结果标记时查询原任务并核对 |

控制接口错误示例：`{"code":409,"message":"resource is referenced, deleted or awaiting deletion confirmation","request_id":"req_example"}`。创建期间还可能返回[原生错误](native-errors.md)中的任务诊断；HTTP 非 2xx 不一定意味着上游没有受理。