音色管理

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

POST/v1/general/custom-voices

GET/v1/general/custom-voices/{id}

GET/v1/general/custom-voices

GET/v1/general/presets-voices

POST/v1/general/delete-voices

创建可在 Kling 4.0 全能参考中以 voice 素材引用的音色（voice_id），也可绑定到主体的 element_voice_id；并查询、删除自己的音色，查询官方音色库。属于旧版风格（响应字段 task_id / task_status）。

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

快速开始

curl https://api.vibelab.me/v1/general/custom-voices \
  -H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"voice_name":"旁白","voice_url":"https://example.com/voice.mp3","external_task_id":"my-narrator"}'

响应示例：

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

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

请求参数

创建音色请求体

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

参数	类型	必填	默认	说明
`voice_name`	string	是	-	不超过 20 个字符
`voice_url`	string	是	-	音视频地址，支持 MP3/WAV/MP4/MOV，要求干净单人声、5–30 秒；不支持上游历史作品 `video_id`
`callback_url`	string	否	-	任务状态变化时的 HTTPS 回调地址（顶层字段），见回调
`external_task_id`	string	否	-	自定义任务 ID，当前用户范围内唯一（顶层字段）

其他接口参数

接口	参数	类型	必填	默认	说明
`GET .../custom-voices/{id}`	`id`（路径）	string	是	-	创建任务 ID 或自定义任务 ID
`GET .../custom-voices`、`GET .../presets-voices`	`pageNum`	integer	否	`1`	`1`–`1000`
同上	`pageSize`	integer	否	`30`	`1`–`1000`
`POST .../delete-voices`	`voice_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.voices[].voice_id`	string	成功后的音色 ID
`data.task_result.voices[].voice_name`	string	音色名称
`data.task_result.voices[].trial_url`	string	试听地址

自定义音色列表只返回当前用户的创建任务记录，不受 30 天限制；官方列表实时查询上游。
首次引用预置音色前，须查询包含该 ID 的官方列表页。
删除成功后 LoopToken 停止允许引用该音色，原创建任务保留历史快照。
不返回上游成本字段。

计费

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

错误

HTTP	`code`	触发场景	处理
400	`1201`	`voice_name is required and must be a string` / `voice_url is required and must be a string`	补齐必填字段
400	`1201`	`voice_name must not exceed 20 characters`	缩短名称
400	`1201`	`video_id is not supported, use voice_url`	改传 `voice_url`
400	`1201`	`invalid pageNum` / `invalid pageSize`（列表）	页码 `1`–`1000`，每页 `1`–`1000`
400	`1201`	`invalid JSON body` / `asset ID is required`（删除）	请求体传 `{"voice_id":"..."}`
404	`1203`	`asset not found`（删除）：不是自己创建的音色，或渠道不可用	官方音色不能删除，核对 `voice_id`
404	`1203`	`task not found`（查询）	核对任务 ID

通用错误见 Kling 错误。

注意事项

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

音色管理

本页内容