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

Callback Request Format

When the task progresses or completes, the system will send a POST request to your callBackUrl in the following format:

Complete Success Callback

First Track Success Callback

Text Generation Callback

Failure Callback

{
  "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": "[Verse] Night city lights shining bright",
        "model_name": "chirp-v4-5",
        "title": "Iron Man",
        "createTime": 1786343609818,
        "duration": 198.44,
        "tags": "electrifying, rock",
        "source_audio_url":"https://example.cn/****.jpeg",
        "source_image_url":"https://example.cn/****.mp3",
        "source_stream_audio_url":"https://example.cn/****"
      },
      {
        "id": "e231****-****-****-****-****8cadc7dc",
        "audio_url": "https://example.cn/****.mp3",
        "stream_audio_url": "https://example.cn/****",
        "image_url": "https://example.cn/****.jpeg",
        "prompt": "[Verse] Night city lights shining bright",
        "model_name": "chirp-v4-5",
        "title": "Iron Man",
        "createTime": 1786343609818,
        "duration": 198.44,
        "tags": "electrifying, rock",
        "source_audio_url":"https://example.cn/****.jpeg",
        "source_image_url":"https://example.cn/****.mp3",
        "source_stream_audio_url":"https://example.cn/****"
      }
    ]
  }
}

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

msg (string, required)

Status message providing detailed status description

data.callbackType (string, required)

Callback type indicating the stage of generation:

text: Text generation complete

first: First track complete

complete: All tracks complete

error: Generation failed

data.task_id (string, required)

Task ID, consistent with the taskId returned when you submitted the task

`data.data` (array)

Array of generated audio data.

`data.data[].id` (string)

Unique identifier of the audio.

`data.data[].audio_url` (string)

Audio file URL.

`data.data[].stream_audio_url` (string)

Streaming audio URL.

`data.data[].image_url` (string)

Cover image URL.

`data.data[].prompt` (string)

Generation prompt or lyrics.

`data.data[].model_name` (string)

Name of the model used.

`data.data[].title` (string)

Music title.

`data.data[].tags` (string)

Music tags.

`data.data[].createTime` (integer)

Creation time.

`data.data[].duration` (number)

Audio duration in seconds.

`data.data[].source_audio_url`（string）

Source audio file URL.

`data.data[].source_image_url`（string）

Source cover image URL.

`data.data[].source_stream_audio_url`（string）

Source streaming audio URL.

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#

Callback Request Format#

Status Codes#

msg (string, required)#

data.callbackType (string, required)#

data.task_id (string, required)#

data.data (array)#

data.data[].id (string)#

data.data[].audio_url (string)#

data.data[].stream_audio_url (string)#

data.data[].image_url (string)#

data.data[].prompt (string)#

data.data[].model_name (string)#

data.data[].title (string)#

data.data[].tags (string)#

data.data[].createTime (integer)#

data.data[].duration (number)#

data.data[].source_audio_url（string）#

data.data[].source_image_url（string）#

data.data[].source_stream_audio_url（string）#

Implementation Examples#

Callback Security#

Verification Recommendations#

Example Security Implementation#

Troubleshooting#

Common Issues#

Best Practices#

Callback Mechanism

When Callbacks Are Sent

Callback Method

Callback Request Format

Status Codes

msg (string, required)

data.callbackType (string, required)

data.task_id (string, required)

`data.data` (array)

`data.data[].id` (string)

`data.data[].audio_url` (string)

`data.data[].stream_audio_url` (string)

`data.data[].image_url` (string)

`data.data[].prompt` (string)

`data.data[].model_name` (string)

`data.data[].title` (string)

`data.data[].tags` (string)

`data.data[].createTime` (integer)

`data.data[].duration` (number)

`data.data[].source_audio_url`（string）

`data.data[].source_image_url`（string）

`data.data[].source_stream_audio_url`（string）

Implementation Examples

Callback Security

Verification Recommendations

Example Security Implementation

Troubleshooting

Common Issues

Best Practices