文档 / 音乐系列 / Suno / 人声音色
人声音色POSTSunovoicepersonasuno_voice_create
方法二第2步:验证并创建音色
Voice Persona 第二步：上传验证录音并创建 persona。
Bearer API KeyJSON服务端调用
用途#
提交上一步 phrase_text 的真人朗读录音，并携带 session_id 验证并创建人声音色（persona）。请求接收后会立即返回公开 task_id，完成后通过任务查询接口获取结果。
这是音色创建流程的第二步。session_id 来自 voice/sample 返回的任务 ID，录音内容必须与该任务返回的 phrase_text 一致。
请使用真人朗读 phrase_text 并提交录音。完成后，结果中的 persona_id 可用于后续音乐生成。
音频传参#
支持 multipart 表单和 JSON Base64 两种方式提交录音。
请求体#
请提交 session_id、真人朗读录音和音色名称。
| 字段 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
session_id | body / form / query | string | 是 | voice/sample 返回的任务 ID |
| 音频 | body / form | file / string | 是 | 对应 phrase_text 的真人朗读录音；JSON 方式填写 Base64 字符串 |
name | body / form / query | string | 是 | 音色名称 |
description | body / form / query | string | 否 | 音色描述 |
is_public | body / form / query | bool | 否 | 是否公开，默认 false |
user_input_styles | body / form / query | string | 否 | 风格描述 |
notify_hook | body / form / query | string | 否 | 任务完成时的回调地址 |
session_id、音频和 name 为必填项。session_id 必须对应已成功获取验证短语的 voice/sample 任务，录音内容应与该任务返回的 phrase_text 一致。
请求示例#
multipart#
cURL
curl --request POST \
--url https://api.apimax.ai/v1/music/voice/create \
--header 'Authorization: Bearer <token>' \
--form 'audio=@/path/to/phrase.mp3' \
--form 'session_id=task_voice_01J...' \
--form 'name=我的音色' \
--form 'is_public=false'JSON Base64#
json
{
"session_id": "task_voice_01J...",
"audio": "<base64验证录音>",
"name": "我的音色",
"description": "温暖、清晰的人声",
"is_public": false,
"user_input_styles": "流行",
"notify_hook": "https://example.com/hooks/voice-create"
}成功响应#
200
{
"code": "success",
"message": "",
"data": "task_voice_02K..."
}响应字段#
| 字段 | 类型 | 说明 |
|---|---|---|
code | string | 响应码，成功固定为 success |
message | string | 提示信息，成功时通常为空 |
data | string | 公开任务 ID，用于后续查询 |
错误码#
| HTTP | code | 场景 |
|---|---|---|
| 400 | invalid_request | 请求体解析失败，或缺少 session_id / name |
| 503 | no_available_channel | 暂无可用服务 |
| 502 | request_failed | 请求处理失败 |
查询任务结果#
提交成功后，使用返回的 task_id 轮询：
- 单个查询：
GET /v1/tasks/:id
status 枚举#
| 值 | 说明 |
|---|---|
queued | 任务已创建，等待处理 |
in_progress | 任务正在处理 |
completed | 任务处理完成，可读取 data |
failed | 任务处理失败，可读取 error |
completed 和 failed 为终态；其余状态请继续轮询。
任务完成后，data 数组中包含创建出的音色 ID，例如：
json
[
{ "persona_id": "7d20fabc-..." }
]拿到 persona_id 后，即可在音乐生成请求中复用该音色。