Skip to main content
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

CodeDescription
200Success - Task completed successfully
400Validation error - Parameter validation failed
408Timeout - Request timeout
500Server error - Unexpected error occurred
501Audio generation failed
531Server 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

​
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

  1. IP Whitelist: Restrict callback endpoints to known IP addresses
  2. HTTPS Only: Always use HTTPS for callback URLs in production
  3. Request Validation: Validate the structure and content of callback requests
  4. 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

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