跳转到主要内容
POST
/
api
/
v1
/
voice
/
generate
Suno Voice自建音色生成接口
curl --request POST \
  --url https://api.example.com/api/v1/voice/generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "taskId": "voice_create_001",
  "verifyUrl": "https://example.com/audio/verify_read.mp3",
  "voiceName": "My Voice",
  "description": "created from uploaded voice",
  "style": "Pop, Female Vocal",
  "singerSkillLevel": "beginner",
  "callBackUrl": "https://example.com/callback/suno/voice_create"
}
'
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "xxx_task_id_xxx"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.api.box/llms.txt

Use this file to discover all available pages before exploring further.

​
使用指南

  • 请在验证短句生成完成，并且用户已完成验证音频录制后调用此接口。
  • 验证短句是服务端返回的 validateInfo 文本。为获得更佳的音色生成效果，建议用户以演唱方式录制服务端返回的验证短句。
  • 提交原验证任务的 taskId，并在 verifyUrl 中传入验证音频 URL。
  • 可选的 voiceName、description、style 和 singerSkillLevel 可帮助管理并调整生成的音色。
  • 接口会返回新的 taskId，后续通过它查询最终 voiceId。
  • 如果传入 callBackUrl，系统会在音色创建完成或任务失败时发送 POST 回调。回调地址必须可公网访问，并在 15 秒内返回 HTTP 200。

​
流程

  1. 生成并获取验证短句。
  2. 录制用户完成该短句的验证音频；为获得更佳的音色生成效果，建议采用演唱方式录制。
  3. 上传或托管验证音频，并将 URL 作为 verifyUrl 传入。
  4. 提交音色生成任务，并保存返回的 taskId。
  5. 任务成功后，通过查询接口或回调获取 voiceId。

​
回调

自建音色生成回调

查看音色创建完成或失败时发送的回调格式

​
开发者注意事项

  • taskId 必须来自同一音色流程中的验证短句任务。
  • verifyUrl 应指向用户录制服务端返回的同一条验证短句的音频；为获得更佳效果，建议采用演唱方式录制。
  • 获取 voiceId 后，建议先调用音色可用性检查接口，再用于依赖自建音色的生成流程。

授权

​
Authorization
string
header
必填

API 认证说明

所有接口都需要通过 Bearer Token 方式进行认证。

获取 API Key

  1. 访问 API Key 管理页面 获取您的 API Key

使用方式

在请求头中添加：

Authorization: Bearer YOUR_API_KEY

注意：

  • 请妥善保管您的 API Key，不要泄露给他人
  • 如果怀疑 API Key 泄露，请立即在管理页面重置

请求体

application/json
​
taskId
string
必填

任务task_id

​
verifyUrl
string
必填

用户录制服务端返回的验证短句后的音频URL；为获得更佳效果，建议采用演唱方式录制[必填]

​
voiceName
string

音色名称

​
description
string

音色描述

​
style
string

音色风格

​
singerSkillLevel
enum<string>
默认值:beginner

歌手技能等级。支持：beginner、intermediate、advanced、professional

可用选项:
beginner,
intermediate,
advanced,
professional
​
callBackUrl
string

用于接收自建音色生成结果的回调地址。任务成功时，回调中会包含生成的 voiceId；任务失败时会包含 errorCode 和 errorMessage。该地址必须可公网访问，并在 15 秒内返回 HTTP 200。回调数据格式请参考 自建音色生成回调。

响应

200 - application/json
​
code
integer
必填
​
msg
string
必填
​
data
object
必填