> ## Documentation Index
> Fetch the complete documentation index at: https://docs.api.box/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload and Extend Audio Callbacks

> When upload and extend audio tasks are completed, the system will send results to your provided callback URL via POST request

When you submit a task to the upload and extend audio API, you can use the `callBackUrl` parameter to set a callback URL. When the task is completed, the system will automatically push the results to your specified address.

## Callback Mechanism Overview

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

### Callback Timing

The system will send callback notifications in the following situations:

* Text generation completed (`text` stage)
* First extended audio track generated (`first` stage)
* All extended audio tracks generated (`complete` stage)
* Audio extension task failed
* Error occurred during task processing

### Callback Method

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

## Callback Request Format

When a task is completed, the system will send a POST request to your `callBackUrl` in the following format:

<CodeGroup>
  ```json Text Generation Complete Callback theme={null}
  {
    "code": 200,
    "msg": "Text generation completed successfully.",
    "data": {
      "callbackType": "text",
      "task_id": "2fac****9f72",
      "data": []
    }
  }
  ```

  ```json First Track Complete Callback theme={null}
  {
    "code": 200,
    "msg": "First track extended successfully.",
    "data": {
      "callbackType": "first",
      "task_id": "2fac****9f72",
      "data": [
        {
          "id": "8551****662c",
          "audio_url": "https://example.cn/****.mp3",
          "source_audio_url": "https://example.cn/****.mp3",
          "stream_audio_url": "https://example.cn/****",
          "source_stream_audio_url": "https://example.cn/****",
          "image_url": "https://example.cn/****.jpeg",
          "source_image_url": "https://example.cn/****.jpeg",
          "prompt": "[Verse] Continue the beautiful melody of the uploaded audio",
          "model_name": "chirp-v3-5",
          "title": "Extended Music",
          "tags": "extended, original style",
          "createTime": "2025-01-01 00:00:00",
          "duration": 298.44
        }
      ]
    }
  }
  ```

  ```json All Complete Callback theme={null}
  {
    "code": 200,
    "msg": "All extended successfully.",
    "data": {
      "callbackType": "complete",
      "task_id": "2fac****9f72",
      "data": [
        {
          "id": "8551****662c",
          "audio_url": "https://example.cn/****.mp3",
          "source_audio_url": "https://example.cn/****.mp3",
          "stream_audio_url": "https://example.cn/****",
          "source_stream_audio_url": "https://example.cn/****",
          "image_url": "https://example.cn/****.jpeg",
          "source_image_url": "https://example.cn/****.jpeg",
          "prompt": "[Verse] Continue the beautiful melody of the uploaded audio",
          "model_name": "chirp-v3-5",
          "title": "Extended Music",
          "tags": "extended, original style",
          "createTime": "2025-01-01 00:00:00",
          "duration": 298.44
        }
      ]
    }
  }
  ```

  ```json Failed Callback theme={null}
  {
    "code": 400,
    "msg": "Extension failed, uploaded audio file is corrupted",
    "data": {
      "callbackType": "failed",
      "task_id": "2fac****9f72",
      "data": []
    }
  }
  ```
</CodeGroup>

## Status Code Description

<ParamField path="code" type="integer" required>
  Callback status code indicating task processing result:

  | Status Code | Description                                                       |
  | ----------- | ----------------------------------------------------------------- |
  | 200         | Success - Extension completed                                     |
  | 400         | Bad Request - Parameter error or invalid audio file               |
  | 401         | Unauthorized - Invalid API key                                    |
  | 413         | Content Too Long - Audio file too large or duration exceeds limit |
  | 429         | Insufficient Credits - Account credit balance insufficient        |
  | 500         | Server Error - Please retry later                                 |
</ParamField>

<ParamField path="msg" type="string" required>
  Status message providing detailed status description
</ParamField>

<ParamField path="data.callbackType" type="string" required>
  Callback type indicating current callback stage:

  * `text`: Text generation complete
  * `first`: First extension complete
  * `complete`: All extensions complete
  * `failed`: Task failed
</ParamField>

<ParamField path="data.task_id" type="string" required>
  Task ID, consistent with the taskId returned when you submitted the task
</ParamField>

<ParamField path="data.data" type="array">
  Extension result information, returned on success
</ParamField>

<ParamField path="data.data[].id" type="string">
  Unique audio identifier (audioId)
</ParamField>

<ParamField path="data.data[].audio_url" type="string">
  Extended audio file download link
</ParamField>

<ParamField path="data.data[].source_audio_url" type="string">
  Original audio file download link
</ParamField>

<ParamField path="data.data[].stream_audio_url" type="string">
  Streaming audio playback link
</ParamField>

<ParamField path="data.data[].image_url" type="string">
  Music cover image link
</ParamField>

<ParamField path="data.data[].prompt" type="string">
  Prompt/lyrics used for extension
</ParamField>

<ParamField path="data.data[].model_name" type="string">
  AI model name used
</ParamField>

<ParamField path="data.data[].title" type="string">
  Music title
</ParamField>

<ParamField path="data.data[].tags" type="string">
  Music style tags
</ParamField>

<ParamField path="data.data[].createTime" type="string">
  Creation time
</ParamField>

<ParamField path="data.data[].duration" type="number">
  Extended audio duration (seconds)
</ParamField>

## Best Practices

<Tip>
  ### Callback URL Configuration Recommendations

  1. **Use HTTPS**: Ensure callback URLs use HTTPS protocol for secure data transmission
  2. **Verify Source**: Validate the legitimacy of request sources in callback processing
  3. **Idempotent Processing**: The same taskId 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 should be processed asynchronously to avoid blocking callback response
  6. **Stage-based Processing**: Perform appropriate business processing based on different callback stages
  7. **Audio Comparison**: Compare audio duration and quality changes before and after extension
  8. **Upload Validation**: Ensure uploaded audio file quality and integrity
</Tip>

<Warning>
  ### Important Reminders

  * Callback URL must be a publicly accessible address
  * Server must respond within 15 seconds, otherwise considered timeout
  * After 3 consecutive retry failures, the system will stop sending callbacks
  * Please ensure the stability of callback processing logic to avoid callback failures due to exceptions
  * Extended audio URLs may have time limits, recommend downloading and saving promptly
  * Uploaded audio files must not exceed 8 minutes, ensure compliance with limits
  * Extension function will extend audio length while maintaining original style
  * Music extension has three stages, each stage will trigger callback notifications
</Warning>

## Troubleshooting

If you don't receive callback notifications, please check the following:

<AccordionGroup>
  <Accordion title="Network Connection Issues">
    * Confirm that the callback URL is accessible from the public internet
    * Check firewall settings to ensure inbound requests are not blocked
    * Verify that domain name resolution is correct
  </Accordion>

  <Accordion title="Server Response Issues">
    * Ensure the server returns HTTP 200 status code within 15 seconds
    * Check server logs for error information
    * Verify that the interface path and HTTP method are correct
  </Accordion>

  <Accordion title="Extension Parameter Issues">
    * Confirm that the upload URL is valid and accessible
    * Check the uploaded audio file format and quality
    * Verify that the audio file duration does not exceed the 2-minute limit
    * Confirm that extension parameters (continueAt, etc.) are set correctly
  </Accordion>

  <Accordion title="Callback Stage Processing">
    * Understand the differences and processing methods of the three callback stages
    * text stage: Only indicates text generation complete, no audio data
    * first stage: First extended music complete, contains data for one track
    * complete stage: All extended music complete, contains complete music list
  </Accordion>
</AccordionGroup>

## Alternative Solutions

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

<Card title="Poll Extension Results" icon="radar" href="/suno-api/get-music-generation-details">
  Use the Get Music Generation Details interface to regularly query extension task status. Recommend querying every 30 seconds.
</Card>