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": {
    "audio_wav_url": "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.audio_wav_url
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:
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.audio_wav_url) {
    // WAV conversion successful
    console.log(`WAV file ready: ${data.audio_wav_url}`);
    
    // Download WAV file
    downloadWavFile(data.audio_wav_url, 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:

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.