Skip to main content
POST
/
api
/
v1
/
generate
/
generate-persona
Generate Persona
curl --request POST \
  --url https://api.sunoapi.org/api/v1/generate/generate-persona \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "taskId": "5c79****be8e",
  "audioId": "e231****-****-****-****-****8cadc7dc",
  "name": "Electronic Pop Singer",
  "description": "A modern electronic music style pop singer, skilled in dynamic rhythms and synthesizer tones",
  "vocalStart": 0,
  "vocalEnd": 30,
  "style": "Electronic Pop"
}
'
{
  "code": 200,
  "msg": "success",
  "data": {
    "personaId": "a1b2****c3d4",
    "name": "Electronic Pop Singer",
    "description": "A modern electronic music style pop singer, skilled in dynamic rhythms and synthesizer tones"
  }
}

​
Usage Guide

  • Use this endpoint to create Personas (music characters) for generated music
  • Requires the taskId from music generation related endpoints (generate, extend, cover, upload-extend, mashup) and audio ID
  • Customize the Persona name and description to give music unique personality
  • Generated Personas can be used for subsequent music creation and style transfer
  • Optionally specify vocalStart and vocalEnd to define the time range (10-30 seconds) for analysis. If not provided, defaults to 0.0 and 30.0 respectively

​
Parameter Details

  • taskId: Required parameter, can be obtained from the following endpoints:
  • audioId: Required parameter, specifies the audio ID to create Persona for
  • name: Required parameter, assigns an easily recognizable name to the Persona
  • description: Required parameter, describes the Persona’s musical characteristics, style, and personality
  • vocalStart: Optional parameter, start time (in seconds) of the audio segment to analyze. Default value is 0.0. Must be between 0 and the audio duration, and the segment length (vocalEnd - vocalStart) must be between 10-30 seconds.
  • vocalEnd: Optional parameter, end time (in seconds) of the audio segment to analyze. Default value is 30.0. Must be between 0 and the audio duration, and the segment length (vocalEnd - vocalStart) must be between 10-30 seconds.
  • style: Optional parameter, music style label to help categorize the Persona

​
Developer Notes

  • Important: Ensure the music generation task is fully completed before calling this endpoint. If the music is still generating, this endpoint will return a failure
  • Model Requirement: Persona generation supports taskId from music generated with models V4 and above
  • It is recommended to provide detailed descriptions for Personas to better capture musical characteristics
  • The returned personaId can be used in subsequent music generation requests to create music with similar style characteristics
  • You can apply the personaId to the following endpoints:
  • Each audio ID can only generate a Persona once

​
Parameter Example

{
  "taskId": "5c79****be8e",
  "audioId": "e231****-****-****-****-****8cadc7dc",
  "name": "Electronic Pop Singer",
  "description": "A modern electronic music style pop singer, skilled in dynamic rhythms and synthesizer tones",
  "style": "Electronic Pop"
}
Ensure that the music generation task corresponding to the taskId is complete and the audioId is valid.
Providing detailed and specific descriptions for Personas helps the system more accurately capture musical style characteristics.

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

Unique identifier of the original music generation task. This can be a taskId returned from any of the following endpoints:

  • Generate Music (/api/v1/generate)
  • Extend Music (/api/v1/generate/extend)
  • Upload And Cover Audio (/api/v1/generate/upload-cover)
  • Upload And Extend Audio (/api/v1/generate/upload-extend)
Example:

"5c79****be8e"

​
audioId
string
required

Audio ID of the music track to create Persona for.

Example:

"e231****-****-****-****-****8cadc7dc"

​
name
string
required

Name for the Persona. A descriptive name that captures the essence of the musical style or character.

Example:

"Electronic Pop Singer"

​
description
string
required

Detailed description of the Persona's musical characteristics, style, and personality. Be specific about genre, mood, instrumentation, and vocal qualities.

Example:

"A modern electronic music style pop singer, skilled in dynamic rhythms and synthesizer tones"

​
vocalStart
number
default:0

Start time (in seconds) of the audio segment to analyze for Persona generation. Optional. Default value is 0.0. Must be between 0 and the audio duration. The segment length (vocalEnd - vocalStart) must be between 10-30 seconds.

Required range: x >= 0
Example:

0

​
vocalEnd
number
default:30

End time (in seconds) of the audio segment to analyze for Persona generation. Optional. Default value is 30.0. Must be between 0 and the audio duration. The segment length (vocalEnd - vocalStart) must be between 10-30 seconds.

Required range: x >= 0
Example:

30

​
style
string

Music style label to help categorize the Persona. Optional.

Example:

"Electronic Pop"

Response

Request successful

​
code
enum<integer>

Response Status Codes

  • 200: Success - Request has been processed successfully
  • 401: Unauthorized - Authentication credentials are missing or invalid
  • 402: Insufficient Credits - Account does not have enough credits to perform the operation
  • 404: Not Found - The requested resource or endpoint does not exist
  • 409: Conflict - Persona already exists for this music
  • 422: Validation Error - The request parameters failed validation checks
  • 429: Rate Limited - Request limit has been exceeded for this resource
  • 451: Unauthorized - Failed to fetch the music data. Kindly verify any access limits set by you or your service provider
  • 455: Service Unavailable - System is currently undergoing maintenance
  • 500: Server Error - An unexpected error occurred while processing the request
Available options:
200,
401,
402,
404,
409,
422,
429,
451,
455,
500
​
msg
string

Error message when code != 200

Example:

"success"

​
data
object