Skip to main content
POST
/
v1
/
suno
/
submit
/
music
official-format (text to audio)
curl --request POST \
  --url https://api.example.com/v1/suno/submit/music
Suno’s text to audio.mdx for the text to audio API. 
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"
}'

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

"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"

​
Parameters

ParameterTypeRequiredDefaultDescription
promptstring❌ NoCompose a tense pre-battle anthemCustom-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_promptstring❌ NoEthereal female vocals blending with cinematic drumsInspiration-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_instrumentalboolean❌ NofalseSet to true to generate instrumental music without vocals. Set to false to include vocals in the generated music.
mvstring❌ Nochirp-v3-0Model version to use for generation. Available options: - "chirp-v3-5" - Latest model with improved quality - "chirp-v3-0" - Default stable model
tagsstring❌ Nocinematic,epic,ambientMusic 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.
titlestring❌ NoBefore the ChargeCustom-mode title for the generated song. If not provided, a title will be auto-generated based on the prompt or description.
continue_atnumber❌ No8Extension 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_idstring❌ Noclip-123456Clip 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_idstring❌ Notask-001Follow-up task ID for tracking related generation tasks. Use this to link multiple generation requests together for better organization and tracking.

​
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

​
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