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

Webhook Security

To ensure the authenticity and integrity of callback requests, we strongly recommend implementing webhook signature verification. See our Webhook Verification Guide for detailed implementation steps.

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

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)

id (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

tags (string) — Style tags for the music

createTime (string) — Creation timestamp

duration (number) — Duration of the audio in seconds

Implementation Examples

Node.js (Express)

Python (Flask)

PHP

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

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

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#

Callback Security#

Verification Recommendations#

Example Security Implementation#

Troubleshooting#

Common Issues#

Best Practices#

Callback Mechanism

When Callbacks Are Sent

Callback Method

Request Format

Success Callback

Failure Callback

Status Codes

Response Fields

Success Response Fields

Implementation Examples

Callback Security

Verification Recommendations

Example Security Implementation

Troubleshooting

Common Issues

Best Practices