Voice & PersonataskType: suno_voice_check_voice0 Credits (Free Query)

Check Voice Status

Check whether a previously created custom voice is deployed and available for use in music generation tasks. Returns real-time training status and the isAvailable confirmation flag with zero credit consumption.

POST/api/v1/createTask
Test in Playground

Key Verification Features

Zero Credit Cost

Polling voice readiness consumes 0 credits, allowing frequent pre-flight verification without billing overhead.

Fail-Safe Generation

Verify isAvailable: true before kicking off expensive generation tasks, preventing wasted credits on unready models.

Webhook Integration

Supports callBackUrl so your application can react immediately when a long-running custom voice finishes training.

Validation Rules & Usage

Task Identification

  • task_id is required and must correspond to a voice generation task submitted via /doc/suno-voice-generate.
  • If the task is still training, isAvailable will return false.
  • Once training completes, isAvailable returns true and the voice model can be safely used.

Usage in Subsequent Endpoints

  • After confirmation, pass the returned voiceId as persona_id in /api/v1/createTask.
  • Ensure you set persona_model: "voice_persona" when calling music generation endpoints.

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

3 fields
task_idstringrequired

Unique task identifier from the custom voice generation request (/doc/suno-voice-generate) to check.

taskTypestringoptional
default:suno_voice_check_voice

Task routing identifier. Explicitly set to "suno_voice_check_voice".

callBackUrlstringoptional

Public HTTPS webhook URL to receive asynchronous status updates with the voice availability result.

When Callbacks Are Sent

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

  • Voice availability query submitted
  • Backend checks training and deployment state
  • Voice availability result returned (code: 200, isAvailable: true/false)
  • Task failed due to invalid task_id or expired voice record (code: 400, 404, 500)

Webhook Payload Format

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

Callback Payload Fields

FieldTypeDescription
codeintegerStatus code (200: Success, 400: Invalid task_id, 404: Voice record not found, 500: Server error).
msgstringExecution message ("success" or specific error reason).
data.taskIdstringUnique task identifier corresponding to this check request.
data.isAvailablebooleanIndicates whether the custom voice model is ready to be used in music generation tasks (true/false).
data.voiceIdstringThe unique Voice ID associated with the checked task.
data.statusstringCurrent voice deployment status (e.g., "ready", "training", "failed").

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) {
    const { isAvailable, voiceId, voice_name } = data;
    if (isAvailable) {
      console.log(`Voice "${voice_name}" (${voiceId}) is ready for song generation!`);
      // Update your database flag to enable this voice model in your UI...
    } else {
      console.log(`Voice "${voice_name}" is still training or unavailable.`);
    }
  } else {
    console.error(`Voice check 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_check_voice",
    "task_id": "voice_task_8f9a0b1c2d3e4f5a6b7c",
    "callBackUrl": "https://api.yourdomain.com/webhook/suno"
  }'
Response Body(200 status)
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "check_task_1234567890abcdef"
  }
}
Previous EndpointRegenerate Voice PhraseNext EndpointGenerate Validation Phrase

Check custom voice availability anytime

Always verify custom voice models before launching music generations. Free of charge.

Generate Secret Key