Replace Music Section Callbacks

Understand the callback mechanism for replace music section tasks

When you submit a replace music section task to the API, you can provide a callBackUrl to receive real-time notifications about task progress and completion.

Callback Mechanism

When Callbacks Are Sent

The system sends callbacks at the following times:

Complete: When the replacement task is fully completed

Callback Method

HTTP Method: POST
Content-Type: application/json
Timeout: 10 seconds
Retry Policy: Up to 3 attempts with exponential backoff

Request Format

Success Callback

When the replacement task completes successfully:

{
  "code": 200,
  "msg": "All generated successfully.",
  "data": {
    "callbackType": "complete",
    "task_id": "2fac****9f72",
    "data": [
      {
        "id": "e231****-****-****-****-****8cadc7dc",
        "audio_url": "https://example.cn/****.mp3",
        "stream_audio_url": "https://example.cn/****",
        "image_url": "https://example.cn/****.jpeg",
        "prompt": "A calm and relaxing piano track.",
        "model_name": "chirp-v3-5",
        "title": "Relaxing Piano",
        "tags": "Jazz",
        "createTime": "2025-01-01 00:00:00",
        "duration": 198.44
      }
    ]
  }
}

Failure Callback

When the replacement task fails:

{
  "code": 501,
  "msg": "Audio generation failed.",
  "data": {
    "callbackType": "error",
    "task_id": "2fac****9f72",
    "error": "Generation failed due to technical issues"
  }
}

Status Codes

Code	Description
200	Success - Task completed successfully
400	Validation error - Parameter validation failed
408	Timeout - Request timeout
500	Server error - Unexpected error occurred
501	Audio generation failed
531	Server error - Generation failed, credits refunded

Response Fields

Success Response Fields

code

integer

required

Status code indicating the result of the replacement task

msg

string

required

Status message describing the result

data

object

required

Container for callback data

Show Data object properties

callbackType

string

required

Type of callback: complete or error

task_id

string

required

The task ID for the replacement request

data

array

Array of replaced music data (only present on success)

Show Music data properties

string

Unique identifier for the music segment

audio_url

string

Direct URL to the audio file

stream_audio_url

string

Streaming URL for the audio

image_url

string

URL to the cover image

prompt

string

The prompt used for generating the replacement

model_name

string

Name of the AI model used

title

string

Title of the music

Implementation Examples

Node.js (Express)

const express = require('express');
const app = express();

app.use(express.json());

app.post('/replace-section-callback', (req, res) => {
  const { code, msg, data } = req.body;
  
  console.log('Replace section callback received:', {
    code,
    msg,
    taskId: data.task_id,
    callbackType: data.callbackType
  });
  
  if (code === 200 && data.callbackType === 'complete') {
    // Handle successful replacement
    console.log('Replacement completed successfully');
    data.data.forEach((music, index) => {
      console.log(`Music ${index + 1}:`, {
        id: music.id,
        title: music.title,
        duration: music.duration,
        audioUrl: music.audio_url
      });
    });
  } else {
    // Handle failure
    console.log('Replacement failed:', msg);
  }
  
  // Always respond with success to acknowledge receipt
  res.json({ code: 200, msg: 'success' });
});

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

Python (Flask)

from flask import Flask, request, jsonify
import logging

app = Flask(__name__)
logging.basicConfig(level=logging.INFO)

@app.route('/replace-section-callback', methods=['POST'])
def replace_section_callback():
    data = request.json
    code = data.get('code')
    msg = data.get('msg')
    callback_data = data.get('data', {})
    
    logging.info(f"Replace section callback received: code={code}, msg={msg}")
    
    if code == 200 and callback_data.get('callbackType') == 'complete':
        # Handle successful replacement
        logging.info("Replacement completed successfully")
        music_data = callback_data.get('data', [])
        for i, music in enumerate(music_data):
            logging.info(f"Music {i + 1}: {music.get('title')} - {music.get('duration')}s")
    else:
        # Handle failure
        logging.error(f"Replacement failed: {msg}")
    
    # Always respond with success
    return jsonify({"code": 200, "msg": "success"})

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=3000)

PHP

<?php
header('Content-Type: application/json');

// Get the raw POST data
$input = file_get_contents('php://input');
$data = json_decode($input, true);

if ($data === null) {
    http_response_code(400);
    echo json_encode(['code' => 400, 'msg' => 'Invalid JSON']);
    exit;
}

$code = $data['code'] ?? null;
$msg = $data['msg'] ?? '';
$callbackData = $data['data'] ?? [];

error_log("Replace section callback received: code=$code, msg=$msg");

if ($code === 200 && ($callbackData['callbackType'] ?? '') === 'complete') {
    // Handle successful replacement
    error_log("Replacement completed successfully");
    $musicData = $callbackData['data'] ?? [];
    foreach ($musicData as $index => $music) {
        $title = $music['title'] ?? 'Unknown';
        $duration = $music['duration'] ?? 0;
        error_log("Music " . ($index + 1) . ": $title - {$duration}s");
    }
} else {
    // Handle failure
    error_log("Replacement failed: $msg");
}

// Always respond with success
echo json_encode(['code' => 200, 'msg' => 'success']);
?>

Callback Security

Verification Recommendations

IP Whitelist: Restrict callback endpoints to known IP addresses
HTTPS Only: Always use HTTPS for callback URLs in production
Request Validation: Validate the structure and content of callback requests
Timeout Handling: Implement proper timeout handling for callback processing

Example Security Implementation

const crypto = require('crypto');

function verifyCallback(req, res, next) {
  // Verify request structure
  const { code, msg, data } = req.body;
  if (typeof code !== 'number' || typeof msg !== 'string' || !data) {
    return res.status(400).json({ code: 400, msg: 'Invalid callback format' });
  }
  
  // Verify task ID format
  const taskId = data.task_id;
  if (!taskId || !/^[a-f0-9\*]{12}$/.test(taskId)) {
    return res.status(400).json({ code: 400, msg: 'Invalid task ID' });
  }
  
  next();
}

app.post('/replace-section-callback', verifyCallback, (req, res) => {
  // Process verified callback
  // ... callback handling logic
});

Troubleshooting

Common Issues

Q: Callbacks are not being received

Verify your callback URL is publicly accessible
Check that your server is responding within 10 seconds
Ensure your endpoint accepts POST requests with JSON content

Q: Receiving duplicate callbacks

This can happen due to network issues or timeouts
Implement idempotency using the task_id to handle duplicates

Q: Callback data is missing or incomplete

Check the callbackType field to understand the callback stage
For error callbacks, check the error message for details

Q: How to handle callback failures?

Always return a 200 status code to acknowledge receipt
Use the Get Music Details endpoint to poll task status as a fallback

Best Practices

Always Acknowledge: Return HTTP 200 even if your processing fails
Implement Retry Logic: Handle temporary failures gracefully
Log Everything: Keep detailed logs for debugging
Use Fallback Polling: Don’t rely solely on callbacks for critical workflows
Validate Data: Always validate callback data before processing

To find navigation and other pages in this documentation, fetch the llms.txt file at: https://docs.apikley.ru/llms.txt

Rate limits and quotas are enforced by Apikley and may differ from upstream providers.

Getting Started

Veo3 API

Suno API

Runway API

Image Models

Video Models

Audio Models

Luma API

Flux Kontext API

4o Image API

File Upload API

Common API

Suno api replace section callbacks

Replace Music Section Callbacks

Callback Mechanism

When Callbacks Are Sent

Callback Method

Request Format

Success Callback

Failure Callback

Status Codes

Response Fields

Success Response Fields

Implementation Examples

Node.js (Express)

Python (Flask)

PHP

Callback Security

Verification Recommendations

Example Security Implementation

Troubleshooting

Common Issues

Best Practices

​Replace Music Section Callbacks

​Callback Mechanism

​When Callbacks Are Sent

​Callback Method

​Request Format

​Success Callback

​Failure Callback

​Status Codes

​Response Fields

​Success Response Fields

​Implementation Examples

​Node.js (Express)

​Python (Flask)

​PHP

​Callback Security

​Verification Recommendations

​Example Security Implementation

​Troubleshooting

​Common Issues

​Best Practices

Replace Music Section Callbacks

Callback Mechanism

When Callbacks Are Sent

Callback Method

Request Format

Success Callback

Failure Callback

Status Codes

Response Fields

Success Response Fields

Implementation Examples

Node.js (Express)

Python (Flask)

PHP

Callback Security

Verification Recommendations

Example Security Implementation

Troubleshooting

Common Issues

Best Practices