Voice & PersonataskType: generate_persona5 Credits / Task

Generate Persona

Extract a reusable singer identity and distinct vocal timbre from a previously generated Suno track. Maintain character continuity and consistent vocals across albums, sequels, and recurring music series.

POST/api/v1/createTask
Test in Playground

How Suno AI Personas Work

Acoustic Profiling

Isolates vocal frequency response, vibrato characteristics, and emotional timbre from your chosen 10~30s audio segment.

Reusable Persona ID

Assigns a permanent persona_id that you can inject into any generation endpoint to clone the artist identity.

Cross-Genre Continuity

Bring the same singer persona into acoustic ballads, EDM anthems, or R&B tracks while preserving vocal tone.

Validation Rules & Constraints

Prerequisites & Task Status

  • The original music generation task must be fully completed before requesting a persona.
  • Supported models: Works with tracks generated using Suno V4, V5, V5.5, and V6 (v3.5 and below not supported).
  • Each audio_id can only be used to generate a Persona once.
  • audio_id and name are required fields.

Segment Extraction Window

  • vocal_start must be strictly less than vocal_end.
  • The extraction duration (vocal_end - vocal_start) must be between 10 and 30 seconds.
  • Defaults to 0.0s – 30.0s if unspecified.
  • Choose a segment featuring clear, upfront vocals for the best persona accuracy.

Authentication & Headers

HeaderRequirementDescription
Authorizationrequired

Bearer YOUR_API_KEY

Secret API Key obtained from your Suno API dashboard.

Content-Typerequired

application/json

Request payload format.

Request Body Schema

9 fields
audio_idstringrequired

Unique identifier of the audio track to create the Persona from (must be from a completed task generated with V4, V5, or V6 models).

namestringrequired

A descriptive name capturing the identity of the musical persona (e.g. "Luna - Indie Dream Pop").

descriptionstringoptional

Detailed description of the persona’s musical characteristics, style, personality, timbre, and vocal tone.

task_idstringoptional

Unique identifier of the original completed music generation or extension task.

vocal_startnumberoptional
default:0.0

Start timestamp (in seconds) for persona analysis segment extraction. Must be strictly less than vocal_end. Defaults to 0.0.

vocal_endnumberoptional
default:30.0

End timestamp (in seconds) for persona analysis segment extraction. The analysis duration (vocal_end - vocal_start) must be between 10 and 30 seconds. Defaults to 30.0.

tagsstringoptional

Supplemental musical genre and style tags (e.g. "Dream Pop, Female Vocals, Melancholic").

taskTypestringoptional
default:generate_persona

Task routing identifier. Explicitly set to "generate_persona".

callBackUrlstringoptional

Public HTTPS webhook URL to receive asynchronous completion notifications with the generated persona_id.

When Callbacks Are Sent

The SongMesh API automatically triggers an HTTP POST request to your designated callBackUrl under these events:

  • Persona analysis task queued & audio downloaded
  • Vocal timbre, pitch curve, and style profile extracted
  • Persona successfully created with persona_id (code: 200)
  • Task failed due to incomplete source task or invalid duration range (code: 400, 500, 501)

Webhook Payload Format

Response Body(200 status)
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c",
    "persona_id": "persona_98f12a3b4c5d6e7f80ab12cd",
    "name": "Luna - Indie Dream Pop",
    "description": "Ethereal, warm female indie-pop vocals with airy high notes and gentle vibrato",
    "tags": "Indie Pop, Dream Pop, Female Vocals",
    "status": "complete"
  }
}

Callback Payload Fields

FieldTypeDescription
codeintegerStatus code (200: Success, 400: Validation error, 408: Timeout, 500: Server error, 501: Extraction failed).
msgstringStatus message ("success" or specific error reason).
data.taskIdstringUnique task identifier matching the taskId returned when submitting the creation task.
data.persona_idstringThe generated Persona ID. Pass this identifier in future music generation tasks to reproduce this singer identity.
data.namestringThe assigned persona name.
data.descriptionstringDetailed description of the persona’s musical and vocal attributes.

Receiver Implementation Example

Webhook Receiver
// Next.js App Router Webhook Receiver (/api/webhook/suno/route.ts)
import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { code, msg, data } = payload;

  if (code === 200 && data?.persona_id) {
    const { taskId, persona_id, name } = data;
    console.log(`Persona "${name}" created successfully! Persona ID: ${persona_id}`);

    // Store persona_id in your user profile/database
    // You can now pass this persona_id into future /api/v1/createTask calls:
    // { "persona_id": persona_id, "persona_model": "style_persona", ... }
  } else {
    console.error(`Persona creation failed (${code}): ${msg}`);
  }

  return NextResponse.json({ received: true });
}

Webhook Security Recommendation

Always verify incoming webhook payloads on your server. Respond with a 200 OK immediately after parsing the payload to prevent redundant delivery retries from the webhook dispatcher.

Request Sample
curl -X POST "https://api.sunoapi.top/api/v1/createTask" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskType": "generate_persona",
    "audio_id": "8ca376e7-5678-4901-abcd-08aaf2c6dd27",
    "task_id": "5c79b182e0a4401fa9c6691456a02b11",
    "name": "Luna - Indie Dream Pop",
    "description": "Ethereal, warm female indie-pop vocals with airy high notes and gentle vibrato",
    "tags": "Indie Pop, Dream Pop, Female Vocals",
    "vocal_start": 10.0,
    "vocal_end": 35.0,
    "callBackUrl": "https://api.yourdomain.com/webhook/suno"
  }'
Response Body(200 status)
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c"
  }
}
Previous EndpointUpload and Cover AudioNext EndpointCustom Voice Cloning

Ready to integrate Generate Persona?

Create your account, obtain your API key, and build persistent AI singer identities across your music catalogue.

Generate Secret Key