Skip to main content
When you submit a MIDI generation task to the Suno API, you can use the callBackUrl parameter to set a callback URL. The system will automatically push the results to your specified address when the task is completed.

Callback Mechanism Overview

The callback mechanism eliminates the need to poll the API for task status. The system will proactively push task completion results to your server.

Callback Timing

The system will send callback notifications in the following situations:
  • MIDI generation task completed successfully
  • MIDI generation task failed
  • Errors occurred during task processing

Callback Method

  • HTTP Method: POST
  • Content Type: application/json
  • Timeout Setting: 15 seconds

Callback Request Format

When the task is completed, the system will send a POST request to your callBackUrl:
{
  "task_id": "5c79****be8e",
  "code": 200,
  "msg": "success",
  "data": {
    "state": "complete",
    "instruments": [
      {
        "name": "Drums",
        "notes": [
          {
            "pitch": 73,
            "start": "0.036458333333333336",
            "end": "0.18229166666666666",
            "velocity": 1
          },
          {
            "pitch": 61,
            "start": 0.046875,
            "end": "0.19270833333333334",
            "velocity": 1
          },
          {
            "pitch": 73,
            "start": 0.1875,
            "end": "0.4895833333333333",
            "velocity": 1
          }
        ]
      },
      {
        "name": "Electric Bass (finger)",
        "notes": [
          {
            "pitch": 44,
            "start": 7.6875,
            "end": "7.911458333333333",
            "velocity": 1
          },
          {
            "pitch": 56,
            "start": 7.6875,
            "end": "7.911458333333333",
            "velocity": 1
          },
          {
            "pitch": 51,
            "start": 7.6875,
            "end": "7.911458333333333",
            "velocity": 1
          }
        ]
      }
    ]
  }
}

Status Code Description

code
integer
required
Callback status code indicating task processing result:
Status CodeDescription
200Success - MIDI generation completed successfully
500Internal Error - Please try again or contact support
msg
string
required
Status message providing detailed status description
task_id
string
required
Task ID, consistent with the task_id returned when you submitted the task
data
object
MIDI generation result information, returned on success

Success Response Fields

data.state
string
Processing state. Value: complete when successful
data.instruments
array
Array of detected instruments with their MIDI note data

Callback Reception Examples

Below are example codes for receiving callbacks in popular programming languages:
  • Node.js
  • Python
  • PHP
const express = require('express');
const app = express();

app.use(express.json());

app.post('/suno-midi-callback', (req, res) => {
  const { code, msg, task_id, data } = req.body;
  
  console.log('Received MIDI generation callback:', {
    taskId: task_id,
    status: code,
    message: msg
  });
  
  if (code === 200) {
    // Task completed successfully
    console.log('MIDI generation completed');
    
    if (data && data.instruments) {
      console.log(`Detected ${data.instruments.length} instruments`);
      
      data.instruments.forEach(instrument => {
        console.log(`\nInstrument: ${instrument.name}`);
        console.log(`  Note count: ${instrument.notes.length}`);
        
        // Process each note
        instrument.notes.forEach((note, idx) => {
          if (idx < 3) { // Show first 3 notes as example
            console.log(`  Note ${idx + 1}: Pitch ${note.pitch}, ` +
                       `Start ${note.start}s, End ${note.end}s, ` +
                       `Velocity ${note.velocity}`);
          }
        });
      });
      
      // Save MIDI data to database or file
      // processMidiData(task_id, data);
    }
    
  } else {
    // Task failed
    console.log('MIDI generation failed:', msg);
    
    // Handle failure scenarios...
  }
  
  // Return 200 status code to confirm callback received
  res.status(200).json({ status: 'received' });
});

app.listen(3000, () => {
  console.log('Callback server running on port 3000');
});

Best Practices

Callback URL Configuration Recommendations

  1. Use HTTPS: Ensure callback URL uses HTTPS protocol for secure data transmission
  2. Verify Origin: Verify the legitimacy of the request source in callback processing
  3. Idempotent Processing: The same task_id may receive multiple callbacks, ensure processing logic is idempotent
  4. Quick Response: Callback processing should return 200 status code quickly to avoid timeout
  5. Asynchronous Processing: Complex business logic (like MIDI file conversion) should be processed asynchronously
  6. Handle Missing Instruments: Not all instruments may be detected - handle empty or missing instrument arrays gracefully
  7. Store Raw Data: Save the complete JSON response for future reference and reprocessing

Important Reminders

  • Callback URL must be publicly accessible
  • Server must respond within 15 seconds, otherwise will be considered timeout
  • If 3 consecutive retry attempts fail, the system will stop sending callbacks
  • Please ensure the stability of callback processing logic to avoid callback failures due to exceptions
  • MIDI data is retained for 14 days - download and save promptly if needed long-term
  • The number and types of instruments detected depends on audio content
  • Note times (start/end) may be strings or numbers - handle both types

Troubleshooting

If you are not receiving callback notifications, please check the following:
  • Confirm callback URL is accessible from public internet
  • Check firewall settings to ensure inbound requests are not blocked
  • Verify domain name resolution is correct
  • Ensure server returns HTTP 200 status code within 15 seconds
  • Check server logs for error messages
  • Verify endpoint path and HTTP method are correct
  • Confirm received POST request body is in JSON format
  • Check if Content-Type is application/json
  • Verify JSON parsing is correct
  • Handle both string and number types for timing values
  • Some instruments may have empty note arrays
  • Not all audio will detect all instrument types
  • Verify the original vocal separation used split_stem type (not separate_vocal)
  • Check that the source taskId is from a successfully completed separation

Alternative Solutions

If you cannot use the callback mechanism, you can also use polling:

Poll Query Results

Use the Get MIDI Generation Details endpoint to periodically query task status. We recommend querying every 10-30 seconds.
I