文档 / 音乐系列 / Suno / 人声音色
人声音色POSTSunovoicepersonasuno_voice_sample
方法二第1步:上传演唱样本
Voice Persona 第一步：上传演唱样本，获取验证短语。
Bearer API KeyJSON服务端调用
用途#
提交一段演唱样本（voice sample），作为创建人声音色（persona）的第一步。接口为异步模式：请求接收后立即返回公开 task_id，后续使用 GET /v1/tasks/:id 轮询任务状态。
任务成功后，结果中会包含一句 phrase_text 验证短语。请让真人朗读并录制这句短语，再使用本次返回的 task_id 作为 /v1/music/voice/create 的 session_id，完成音色创建。
完整流程为：voice/sample 提交演唱样本并获取 task_id → 轮询获取 phrase_text → 真人朗读并录音 → voice/create 提交录音和 session_id。
请求体#
请使用 JSON 请求体，请求头设置 Content-Type: application/json。音频内容需先转换为 Base64 字符串，放入 audio 字段。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
audio | string | 是 | 演唱样本的 Base64 音频内容 |
filename | string | 否 | 原始音频文件名，例如 vocal.mp3 |
vocal_start_s | number | 否 | 取样人声起点，单位为秒 |
vocal_end_s | number | 否 | 取样人声终点，单位为秒 |
language | string | 否 | 验证短语语言，例如 zh、en、ja |
notify_hook | string | 否 | 任务到达终态时的回调地址 |
请求示例#
cURL#
bash
curl --request POST \
--url https://api.apimax.ai/v1/music/voice/sample \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"audio": "SUQzBAAAAA...",
"filename": "vocal.mp3",
"vocal_start_s": 0,
"vocal_end_s": 12,
"language": "zh",
"notify_hook": "https://example.com/hooks/voice-sample"
}'JSON 请求体#
json
{
"audio": "SUQzBAAAAA...",
"filename": "vocal.mp3",
"vocal_start_s": 0,
"vocal_end_s": 12,
"language": "zh",
"notify_hook": "https://example.com/hooks/voice-sample"
}audio 字段请替换为实际音频文件的 Base64 字符串。不需要回调时，可以省略 notify_hook。
成功响应#
200
{
"code": "success",
"message": "",
"data": "task_voice_01J..."
}响应字段#
| 字段 | 类型 | 说明 |
|---|---|---|
code | string | 响应码，成功固定为 success |
message | string | 提示信息，成功时通常为空 |
data | string | 公开任务 ID，同时作为后续 voice/create 请求的 session_id |
错误码#
| HTTP | code | 场景 |
|---|---|---|
| 400 | invalid_request | 请求体无法解析或必填字段不正确 |
| 503 | no_available_channel | 暂无可用服务 |
| 502 | upstream_failed | 请求处理失败 |
查询结果#
提交成功后，用返回的 task_id 轮询：
- 单个查询：
GET /v1/tasks/:id
任务 status 为 completed 时，具体结果位于 data 数组。 data 内包含验证短语，例如：
json
{
"created_at": 1785295769,
"data": [
{
"phrase_text": "Sing a joyful song with lively melodies today"
}
],
"finished_at": 1785295792,
"id": "task_voice_01JABCDEF0123456789",
"model": "suno_voice_sample",
"object": "task",
"platform": "suno",
"progress": 100,
"started_at": 1785295770,
"status": "completed",
"type": "suno"
}请让真人朗读 phrase_text 并录制音频，然后在 /v1/music/voice/create 中使用本次任务 ID 作为 session_id。