Skip to main content
POST
/
api
/
v1
/
voice
/
generate
Suno Voice Create Custom Voice API
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.

​
Usage Guide

  • Call this API after the validation phrase is generated and the user has recorded the verification audio.
  • The validation phrase is the validateInfo text returned by the server. For best voice generation results, have the user record the server-provided phrase in a singing voice rather than plain speech.
  • Submit the original validation taskId and the verification audio URL in verifyUrl.
  • Optional metadata such as voiceName, description, style, and singerSkillLevel helps organize and tune the generated voice.
  • The API returns a taskId; use it to query the final voiceId.
  • When callBackUrl is provided, the system sends a POST callback when the voice is created or the task fails. The callback URL must be publicly accessible and return HTTP 200 within 15 seconds.

​
Workflow

  1. Generate and retrieve the validation phrase.
  2. Record clear verification audio for the phrase; singing is recommended for best voice generation results.
  3. Upload or host the verification audio and pass the URL as verifyUrl.
  4. Submit the voice generation task and store the returned taskId.
  5. Receive voiceId through the record query API or callback when the task succeeds.

​
Callback

Custom Voice Generation Callbacks

Learn the callback payload sent when the custom voice is created or the task fails

​
Developer Notes

  • taskId must come from the validation phrase task for the same voice workflow.
  • verifyUrl should point to the user’s recording of the exact validation phrase returned by the server; for best results, recording it in a singing voice is recommended.
  • After receiving voiceId, use the availability check endpoint before starting generation workflows that depend on the custom voice.

Authorizations

​
Authorization
string
header
required

API Authentication

All endpoints require authentication using Bearer Token.

Get API Key

  1. Visit the API Key Management Page to obtain your API Key

Usage

Add to request headers:

Authorization: Bearer YOUR_API_KEY

Note:

  • Keep your API Key secure and do not share it with others
  • If you suspect your API Key has been compromised, reset it immediately from the management page

Body

application/json
​
taskId
string
required

Task ID

​
verifyUrl
string
required

Audio URL for the user's recording of the validation phrase returned by the server; singing is recommended for best results [Required]

​
voiceName
string

Voice name

​
description
string

Voice description

​
style
string

Voice style

​
singerSkillLevel
enum<string>
default:beginner

Singer skill level. Supported: beginner, intermediate, advanced, professional

Available options:
beginner,
intermediate,
advanced,
professional
​
callBackUrl
string

Callback URL used to receive custom voice generation results. When the task succeeds, the callback includes the generated voiceId; when it fails, it includes errorCode and errorMessage. The URL must be publicly accessible and return HTTP 200 within 15 seconds. For the payload format, see Custom Voice Generation Callbacks.

Response

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