Voice & PersonataskType: suno_voice_generate5 Credits / Task

Custom Voice Cloning

Create a custom voice model by submitting verified voice audio. Clones the vocal characteristics, timbre, and singing articulation from the sample to generate a reusable voice ID for music generation tasks.

POST/api/v1/createTask
Test in Playground

Custom Voice Creation Workflow

1. Phrase Verification

Obtain a security validation phrase from /doc/suno-voice-validate to confirm ownership of the vocal sample.

2. Timbre Synthesis

Submit your task_id and verify_url to extract vocal resonance, formant curves, and singing style.

3. Reusable Voice ID

Receive a permanent voiceId. Use it with persona_model: "voice_persona" in any Suno music generation.

Validation Rules & Constraints

Audio Quality Best Practices

  • Provide dry, acapella singing recordings without background instrumentals or heavy reverb.
  • Supported audio formats include high-fidelity WAV and MP3 files.
  • Ensure the audio URL is publicly accessible over HTTPS without token redirects.

Validation & Pipeline Rules

  • task_id is required and links to your voice validation phrase task.
  • Use the returned voiceId as persona_id with persona_model: "voice_persona".
  • Using Webhooks (callBackUrl) is strongly recommended due to async model training latency.

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

8 fields
task_idstringrequired

Unique validation task identifier obtained from the verification phrase step (/doc/suno-voice-validate).

verify_urlstringoptional

Publicly accessible URL to the user recording reciting the validation phrase (MP3 or WAV).

voice_namestringoptional

Display name for the custom voice model (e.g. "Aria - Pop Vocalist").

descriptionstringoptional

Detailed description of the vocal characteristics, dynamic range, and vocal timbre.

stylestringoptional

Musical genre, style tags, or vocal delivery cues (e.g. "Pop, Modern, Crisp Highs").

singer_skill_levelstringoptional

Skill level benchmark for the custom voice model (e.g. "professional", "standard").

taskTypestringoptional
default:suno_voice_generate

Task routing identifier. Explicitly set to "suno_voice_generate".

callBackUrlstringoptional

Public HTTPS webhook URL to receive asynchronous completion notifications when custom voice generation finishes.

When Callbacks Are Sent

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

  • Verification phrase audio downloaded and validated
  • Voice timbre training and pitch curve extraction started
  • Voice model generated successfully with voiceId (code: 200)
  • Task failed due to invalid phrase recording or background noise (code: 400, 500, 501)

Webhook Payload Format

Response Body(200 status)
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "voice_task_8f9a0b1c2d3e4f5a6b7c",
    "voiceId": "voice_4a5b6c7d8e9f0123456789ab",
    "voice_name": "Aria - Pop Vocalist",
    "status": "success"
  }
}

Callback Payload Fields

FieldTypeDescription
codeintegerStatus code (200: Success, 400: Validation error, 408: Timeout, 500: Server error, 501: Voice training failed).
msgstringExecution message ("success" or specific error reason).
data.taskIdstringUnique task identifier corresponding to the taskId returned when submitting the creation task.
data.voiceIdstringThe created custom Voice ID. Use this with persona_model: "voice_persona" in music generation.
data.voice_namestringThe assigned display name for the custom voice.
data.statusstringTask execution state: "success", "failed", or "processing".

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?.voiceId || data?.voice_id)) {
    const voiceId = data.voiceId || data.voice_id;
    console.log(`Custom voice "${data.voice_name}" generated! Voice ID: ${voiceId}`);

    // Save voiceId to your user profile or database.
    // In future generation requests, pass this ID as persona_id with persona_model: "voice_persona":
    // { "persona_id": voiceId, "persona_model": "voice_persona", ... }
  } else {
    console.error(`Voice generation 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": "suno_voice_generate",
    "task_id": "val_7a8b9c1d2e3f4a5b6c7d",
    "verify_url": "https://example.com/audio/user_voice_sample.wav",
    "voice_name": "Aria - Pop Vocalist",
    "description": "Bright, crystal clear female soprano singing voice with smooth articulation and modern pop timbre",
    "style": "Pop, Modern, Crisp Highs",
    "singer_skill_level": "professional",
    "callBackUrl": "https://api.yourdomain.com/webhook/suno"
  }'
Response Body(200 status)
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "voice_task_8f9a0b1c2d3e4f5a6b7c"
  }
}
Previous EndpointGenerate PersonaNext EndpointRegenerate Voice Phrase

Ready to clone custom voices?

Create your account, obtain your API key, and begin building custom singing voices with Suno AI.

Generate Secret Key