Skip to main content
When you submit a task to the WAV format conversion 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

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

​
Callback Timing

The system will send callback notifications in the following situations:
  • WAV format conversion completed
  • WAV conversion task failed
  • Error occurred during task processing
WAV format conversion has only one callback stage, providing the download URL upon completion

​
Callback Method

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

​
Callback Request Format

When the task is completed, the system will send a POST request to your callBackUrl in the following format: 
{
  "code": 200,
  "msg": "success",
  "data": {
    "audioWavUrl": "https://example.com/s/04e6****e727.wav",
    "task_id": "988e****c8d3"
  }
}

​
Status Code Description

​
code
integer
required
Callback status code indicating task processing result:
Status CodeDescription
200Success - WAV conversion completed
400Bad Request - Invalid source audio or parameter error
401Unauthorized - Invalid API key
429Insufficient Credits - Account credit balance insufficient
500Server Error - Please retry later
​
msg
string
required
Status message providing detailed status description
​
data.task_id
string
required
Task ID, consistent with the taskId returned when you submitted the task
​
data.audioWavUrl
string
WAV format audio file download URL (returned on success)

​
Callback Reception Examples

Here are example codes for receiving callbacks in various popular programming languages:
  • Node.js
  • Python
  • PHP
const express = require('express');
const fs = require('fs');
const https = require('https');
const app = express();

app.use(express.json());

app.post('/wav-callback', (req, res) => {
  const { code, msg, data } = req.body;
  
  console.log('Received WAV conversion callback:', {
    taskId: data.task_id,
    status: code,
    message: msg
  });
  
  if (code === 200 && data.audioWavUrl) {
    // WAV conversion successful
    console.log(`WAV file ready: ${data.audioWavUrl}`);
    
    // Download WAV file
    downloadWavFile(data.audioWavUrl, data.task_id);
    
  } else {
    // Task failed
    console.log('WAV conversion failed:', msg);
    
    // Handle failure cases...
    if (code === 400) {
      console.log('Invalid source audio or parameter error');
    } else if (code === 429) {
      console.log('Insufficient credits');
    } else if (code === 500) {
      console.log('Server internal error');
    }
  }
  
  // Return 200 status code to confirm callback received
  res.status(200).json({ status: 'received' });
});

function downloadWavFile(url, taskId) {
  const filename = `wav_${taskId}.wav`;
  const file = fs.createWriteStream(filename);
  
  https.get(url, (response) => {
    response.pipe(file);
    
    file.on('finish', () => {
      file.close();
      console.log(`WAV file downloaded: ${filename}`);
    });
  }).on('error', (err) => {
    console.error('WAV download failed:', err.message);
  });
}

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

​
Best Practices

​
WAV Conversion Callback Configuration

  1. File Management: Implement proper file naming conventions for downloaded WAV files
  2. Storage Planning: Ensure adequate storage space for high-quality WAV files
  3. Quality Verification: Verify WAV file integrity after download
  4. Metadata Preservation: Maintain track information and metadata with WAV files
  5. Batch Processing: Consider batch conversion for multiple tracks
  6. Cleanup: Implement cleanup procedures for temporary files

​
WAV-Specific Considerations

  • WAV files are typically larger than MP3 files due to lossless compression
  • Download times may be longer due to file size
  • Ensure sufficient bandwidth for WAV file downloads
  • WAV format provides maximum audio quality for professional use
  • Consider storage costs for large WAV file collections

​
Troubleshooting

Common issues specific to WAV conversion callbacks:
  • Verify the WAV URL is accessible and not expired
  • Check network connectivity and bandwidth
  • Ensure sufficient local storage space
  • Verify download permissions and file paths
  • Confirm the source audio quality meets WAV conversion requirements
  • Check if the original audio file is corrupted
  • Verify that the converted WAV maintains expected quality
  • Test WAV file playback in different audio applications
  • Implement proper file naming to avoid conflicts
  • Monitor storage usage for WAV file collections
  • Consider automated cleanup for old WAV files
  • Verify file integrity after download completion

​
Alternative Solutions

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

Poll WAV Results

Use the Get WAV Conversion Details interface to regularly query conversion task status. Recommend querying every 20 seconds.