Audio Processing & StemstaskType: generate_sounds10 Credits / TaskAsync Webhook & Polling

Generate Sound Effects (SFX)

Create custom cinematic sound design, foley textures, video game audio assets, UI cues, and seamless ambient audio loops from text prompts. Each request delivers two distinct acoustic variations rendered by neural sound synthesis engines.

POST/api/v1/createTask
Test in Playground

Supported AI Engines

5 Models
V6DEFAULT

Refined, high-fidelity sound synthesis with rich dynamic range and crisp transient definition.

V6_WILD

Maximum creative expression for surreal, experimental, and otherworldly acoustic soundscapes.

V6_MINI

Lightweight model optimized for rapid prototyping and quick turnaround rendering.

Acoustic Control Parameters

Seamless Loop

Set sound_loop: true to render seamless ambient loops without start/end boundary clicks.

Tempo Control (BPM)

Specify sound_tempo (1–300 BPM) for rhythm-synced riser sweeps, ticking clocks, or percussive loops.

Musical Pitch Key

Specify sound_key (e.g. "Am", "C", "F#m") to ensure tonal sound effects match your project song key.

Validation Rules & Constraints

Prompt Length

The prompt field is strictly required and must be between 1 and 500 characters. Descriptive physical and acoustic adjectives produce the best results.

Dual Variation Output

Every generation job produces 2 distinct audio variations returned in the webhook payload or polling query under the data array.

Authentication & Headers

HeaderRequirementDescription
Authorizationrequired

Bearer YOUR_API_KEY

Secret API key generated in your dashboard.

Content-Typerequired

application/json

Request body format.

Request Body Parameters

8 fields
promptstringrequired

Detailed description of the sound effect, acoustic environment, foley action, or cinematic texture (maximum 500 characters).

modelstringoptional
default:V6

AI audio synthesis model to use: "V6" (Default, highest fidelity), "V6_WILD" (Experimental acoustics), "V6_MINI" (Fast synthesis), "V5", or "V5_5".

sound_loopbooleanoptional
default:false

Whether the synthesized audio should be seamlessly loopable without clicks or amplitude drops at boundary frames.

sound_tempointegeroptional

Rhythmic tempo in Beats Per Minute (BPM) for rhythmic or percussive sound effects (range: 1 to 300 BPM).

sound_keystringoptional

Musical pitch key for tonal sound effects (e.g. "C", "Cm", "F#m", "Am", "D", "G#m"). Defaults to "Any".

grab_lyricsbooleanoptional
default:false

Whether to extract or recognize any spoken vocal phrases or lyrics present in the prompt.

taskTypestringoptional
default:generate_sounds

Explicit task routing identifier. Can be set to "generate_sounds".

callBackUrlstringoptional

Public HTTPS webhook URL to receive asynchronous completion notification when sound effects rendering completes.

When Callbacks Are Sent

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

  • Sound generation task received and queued in synthesis pipeline
  • Diffusion model synthesizes acoustic textures and harmonic elements
  • Dual sound effect variations rendered, normalized, and uploaded to CDN
  • Webhook notification dispatched with direct MP3 and streaming links (code: 200)

Webhook Payload Format

Response Body(200 status)
{
  "code": 200,
  "msg": "All generated successfully.",
  "data": {
    "task_id": "dc1928bfcbc77cb6c85f3359a9c718b3",
    "data": [
      {
        "id": "8ca376e7-5b62-49d9-bbd3-08aaf2c6dd27",
        "audio_url": "https://file.aiquickdraw.com/s/04e6789a-bcde-f012-3456-789abcdef012.mp3",
        "stream_audio_url": "https://file.aiquickdraw.com/s/stream_04e6789a.mp3",
        "image_url": "https://file.aiquickdraw.com/s/cover_04e6789a.png",
        "title": "Plasma Rifle Blast SFX",
        "duration": 4.8,
        "status": "complete"
      },
      {
        "id": "9db487f8-6c73-40ea-cce4-19bbf3d7ee38",
        "audio_url": "https://file.aiquickdraw.com/s/15f789ab-cdef-0123-4567-89abcdef0123.mp3",
        "stream_audio_url": "https://file.aiquickdraw.com/s/stream_15f789ab.mp3",
        "image_url": "https://file.aiquickdraw.com/s/cover_15f789ab.png",
        "title": "Plasma Rifle Blast SFX (Variant 2)",
        "duration": 5.1,
        "status": "complete"
      }
    ]
  }
}

Callback Payload Fields

FieldTypeDescription
codeintegerHTTP status code (200: Success, 400: Bad prompt format, 500: Server error).
msgstringExecution status message ("All generated successfully." or error details).
data.task_idstringUnique task identifier assigned to the sound generation task.
data.dataarrayArray containing two generated sound effect variants with direct audio links, streaming URLs, and duration.

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 && Array.isArray(data?.data)) {
    console.log(`Sound effects task ${data.task_id} generated successfully!`);
    data.data.forEach((sfx: any) => {
      console.log(`SFX Variant: "${sfx.title}" (${sfx.duration}s)`);
      console.log(`Download Audio URL: ${sfx.audio_url}`);
    });

    // Store sound effects in game asset repository, soundboard, or user media library
  } else {
    console.error(`Sound effect 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": "generate_sounds",
    "prompt": "Futuristic sci-fi plasma rifle blast with metallic mechanical charging up and sub-bass impact",
    "model": "V6",
    "sound_loop": false,
    "sound_tempo": 120,
    "sound_key": "Am",
    "callBackUrl": "https://api.yourdomain.com/webhook/suno"
  }'
Response Body(200 status)
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "dc1928bfcbc77cb6c85f3359a9c718b3"
  }
}
Sound Generation Pro Tips

• Foley & Atmosphere: Describe the material, distance, acoustic space, and resonance (e.g. "Footsteps on wet autumn gravel in an empty warehouse").

• Game Audio: Use sound_loop: true for motor engines, rain, crowd murmurs, and torch fire crackles.

• Cost: 10 credits per task for 2 rendered sound variations.

Previous EndpointRecovery Audio RecordsNext EndpointGenerate Structured Lyrics

Ready to synthesize custom sound effects?

Generate your API key and synthesize professional gaming, cinematic, and UI sound effects in seconds.

Generate Secret Key