文档 / 音乐系列 / Suno / 人声音色
方法一:从已有歌曲创建音色
使用本池已生成的歌曲 clip 直接创建人声音色。
用途#
直接使用本服务已生成的歌曲 clip 提取人声,一步创建可复用音色(persona)。接口为异步模式:服务在校验通过后立即返回公开 task_id,不会等待上游完成音色提取与创建。后续通过 GET /v1/tasks/:id 或 GET /v1/tasks/:id 轮询任务状态与结果。
与 voice/sample + voice/create 的两步验证流程不同,本接口省去演唱样本采集与朗读验证:它直接从一段已有歌曲 clip 中提取人声并创建音色,适合在已生成作品上快速复刻人声。任务成功后,结果中返回 persona_id。
源 clip_id 必须是本服务自有生成池产出的歌曲 clip。上传音频导入的 clip,以及由其 cover / extend 衍生出的 clip,均不能用于该接口。
请求体说明（透传）#
该接口不解析业务字段,以下参数原样转发上游。
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
clip_id | string | 是 | — | 源歌曲 clip 的 UUID,须为本生成池产出的非上传衍生 clip |
name | string | 是 | — | 音色名称 |
vocal_start_s | number | 是 | — | 提取人声起点,单位秒 |
vocal_end_s | number | 是 | — | 提取人声终点,单位秒 |
description | string | 否 | — | 音色描述 |
is_public | bool | 否 | false | 是否公开 |
user_input_styles | string | 否 | — | 风格描述 |
notify_hook | string | 否 | — | 任务到达终态时的回调通知地址 |
clip_id、name、vocal_start_s、vocal_end_s 为必需。上传音频及其 cover 或 extend 衍生 clip 不能用于该接口，否则上游 suno-pool 会返回相应错误，relay 原样透传。
请求示例#
curl --request POST \
--url https://api.apimax.ai/suno/voice/from-clip \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"clip_id": "11f1b88e-...",
"name": "我的音色",
"vocal_start_s": 0,
"vocal_end_s": 12,
"description": "",
"is_public": false,
"user_input_styles": "",
"notify_hook": ""
}'成功响应#
{
"code": "success",
"message": "",
"data": "task_voice_03L..."
}响应字段#
| 字段 | 类型 | 说明 |
|---|---|---|
code | string | 响应码,成功固定为 success |
message | string | 提示信息,成功时通常为空 |
data | string | 公开任务 ID(40 字符以内),用于后续查询 |
data 返回的是平台公开 task_id,并非上游原始 ID。所有后续查询均使用这个公开 ID。
错误码#
| HTTP | code | 场景 |
|---|---|---|
| 400 | invalid_request | 请求体解析失败,或缺少必填字段 |
| 503 | no_available_channel | 无可用渠道 |
| 502 | upstream_failed | 上游请求失败(网络错误等) |
业务级错误(如无法反查源 clip、clip 来源不符合要求等)由上游 suno-pool 返回并原样透传，不在本表枚举。异步阶段失败会落入任务 fail_reason,可通过 fetch 接口查看。
查询任务结果#
提交成功后,使用返回的 task_id 轮询:
- 单个查询:
GET /v1/tasks/:id - 批量查询:
GET /v1/tasks/:id
任务状态流转:SUBMITTED → QUEUED → IN_PROGRESS → SUCCESS / FAILURE。成功后结果在任务的 data 字段中返回,其中包含创建出的音色 ID,例如:
[
{ "persona_id": "7d20fabc-..." }
]拿到 persona_id 后,可在 /suno/submit/MUSIC 请求体中传入 persona_id,让生成结果复用该人声音色。