Skip to main content
Text to Audio
curl --request POST \
  --url https://gptproto.com/v1/suno/submit/music \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "<string>",
  "gpt_description_prompt": "<string>",
  "make_instrumental": true,
  "mv": "<string>",
  "tags": "<string>",
  "title": "<string>",
  "continue_at": 123,
  "continue_clip_id": "<string>",
  "task_id": "<string>"
}'
{
  "code": "error",
  "data": null,
  "message": "Invalid prompt: prompt cannot be empty"
}

Overview

Suno AI is a powerful music generation platform that creates high-quality music from text descriptions. Using Suno’s API, you can create original songs, background music, instrumentals, and custom audio compositions by simply describing what you want in natural language. Related Guides: Suno Official Documentation | Music Generation Guide This endpoint allows you to submit music generation tasks using simple text prompts. The generation is processed asynchronously - you’ll receive a task ID immediately, which you can use to check the status and retrieve the generated audio once complete.

Authentication

This endpoint requires authentication using a Bearer token.
Authorization
string
default:"sk-***********"
required
Your API key in the format: Bearer YOUR_API_KEY

Request Body

prompt
string
default:"Compose a tense pre-battle anthem"
Custom-mode lyrics or description. Provide detailed text description of the music you want to generate for custom mode with specific lyrics or theme.
gpt_description_prompt
string
Inspiration-mode prompt. Use AI to generate music from a high-level description. This mode lets the AI interpret and create music based on your creative description. Great for exploring new musical ideas.
make_instrumental
boolean
default:"false"
Set to true to generate instrumental music without vocals. Set to false to include vocals in the generated music.
mv
string
default:"chirp-v3-0"
Model version to use for generation. Available options:
  • "chirp-v3-5" - Latest model with improved quality
  • "chirp-v3-0" - Default stable model
tags
string
default:"cinematic,epic,ambient"
Music style tags separated by commas for custom mode (e.g., “cinematic,epic,ambient”, “orchestral,dramatic,intense”). These tags help guide the style and mood of the generated music.
title
string
default:"Before the Charge"
Custom-mode title for the generated song. If not provided, a title will be auto-generated based on the prompt or description.
continue_at
number
default:"8"
Extension length in seconds. Specify how many seconds to extend from the original clip (e.g., 8 for 8 seconds extension). Used when extending existing music.
continue_clip_id
string
default:"clip-123456"
Clip ID to extend from (e.g., “clip-123456”). Use this parameter to continue or extend previously generated music clips. Get the clip ID from previous generation responses.
task_id
string
default:"task-001"
Follow-up task ID for tracking related generation tasks. Use this to link multiple generation requests together for better organization and tracking.

Request Example

curl --location 'https://gptproto.com/v1/suno/submit/music' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "prompt": "Compose a tense pre-battle anthem"
}'

Response

Success
200
Successful response
{
  "code": "success",
  "data": "15410652-357c-47fa-8ad9-a4a145fbfa14",
  "message": ""
}

Error Responses

{
  "code": "error",
  "data": null,
  "message": "Invalid prompt: prompt cannot be empty"
}

Generation Modes

Suno supports two main generation modes:

Inspiration Mode (AI-Driven)

Use gpt_description_prompt to let the AI interpret your creative description and generate music. Best for: Creative exploration, when you want AI to interpret your idea
{
  "gpt_description_prompt": "Ethereal female vocals blending with cinematic drums",
  "mv": "chirp-v3-5",
  "make_instrumental": false
}

Custom Mode (Direct Control)

Use prompt, tags, and title for more direct control over the output. Best for: Specific requirements, when you know exactly what you want
{
  "prompt": "Compose a tense pre-battle anthem",
  "tags": "cinematic,epic,ambient",
  "title": "Before the Charge",
  "make_instrumental": true,
  "mv": "chirp-v3-5"
}

Extension/Continuation Mode

Extend existing music clips using continue_clip_id and continue_at. Best for: Making longer tracks, creating variations
{
  "continue_clip_id": "clip-123456",
  "continue_at": 8,
  "mv": "chirp-v3-5"
}

Next Steps

After successfully submitting a music generation task, you’ll receive a task ID. Use this ID to:
  1. Check Task Status - Query the Task Status endpoint to monitor progress
  2. Retrieve Generated Audio - Once completed, get the audio URL from the task status response
  3. Download Audio - Use the audio URL to download your generated music file

Example Workflow

Python
import requests
import time

# Step 1: Submit music generation task
submit_url = "https://gptproto.com/v1/suno/submit/music"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

submit_data = {
    "prompt": "Epic orchestral battle music",
    "tags": "orchestral,epic,cinematic",
    "mv": "chirp-v3-5",
    "make_instrumental": True
}

response = requests.post(submit_url, headers=headers, json=submit_data)
result = response.json()

if result["code"] == "success":
    task_id = result["data"]
    print(f"Task submitted: {task_id}")

    # Step 2: Poll for completion
    query_url = f"https://gptproto.com/v1/suno/fetch/{task_id}"

    while True:
        time.sleep(5)  # Wait 5 seconds between checks

        query_response = requests.get(query_url, headers=headers)
        query_result = query_response.json()

        if query_result["code"] == "success" and query_result["data"]:
            task = query_result["data"][0]

            if task["status"] == "completed":
                print(f"Music ready! URL: {task['audio_url']}")
                break
            elif task["status"] == "failed":
                print(f"Generation failed: {task.get('error_message', 'Unknown error')}")
                break
            else:
                print(f"Status: {task['status']}...")

Best Practices

Writing Effective Prompts

For best results:
  • Be Specific: Include details about mood, tempo, instruments, and style
  • Use Descriptive Words: Add adjectives like “epic”, “calm”, “upbeat”, “dramatic”
  • Mention Genre: Specify the musical style (orchestral, electronic, jazz, rock, etc.)
  • Set Context: Describe the intended use case or scene
  • Keep It Clear: Focus on one musical idea per generation

Example Prompts

"Ethereal female vocals blending with cinematic drums and atmospheric synths"

"Gentle piano melody with soft string accompaniment for peaceful meditation"

"Intense electric guitar riffs with heavy bass and driving drums for action scenes"

"Smooth jazz saxophone with light piano backing and subtle percussion"

Model Selection

ModelBest ForCharacteristics
chirp-v3-5Latest features, highest qualityImproved audio quality, better style adherence
chirp-v3-0Stable, reliable generationDefault choice, well-tested

Parameter Recommendations

Use CaseRecommended Settings
Background Musicmake_instrumental: true, tags: “ambient,background,subtle”
Game Sound Effectsmake_instrumental: true, mv: “chirp-v3-5”
Podcast Intromake_instrumental: true, tags: “intro,professional,upbeat”
Video ContentUse gpt_description_prompt for creative freedom
Custom SongSet custom title, specify detailed prompt and tags
Music ExtensionUse continue_clip_id and continue_at
  • Query Task Status - Check generation progress and retrieve audio
  • Custom Music - Generate with lyrics and advanced options
  • Music Continuation - Extend existing tracks

Official Resources

Suno AI Documentation

GPT Proto Resources

Additional Resources