音乐生成回调

当您向音乐生成API提交任务时，可以使用 callBackUrl 参数设置回调URL。当任务完成时，系统会自动将结果推送到您指定的地址。

回调机制概述

回调机制免除了轮询API获取任务状态的需要。系统会主动将任务完成结果推送到您的服务器。

回调时机

系统会在以下情况发送回调通知：

文本生成完成（text 阶段）
第一首音乐生成完成（first 阶段）
所有音乐生成完成（complete 阶段）
音乐生成任务失败
任务处理过程中发生错误

回调方法

HTTP方法: POST
Content Type: application/json
超时设置: 15秒

回调请求格式

当任务完成时，系统会按以下格式向您的 callBackUrl 发送POST请求：

{
  "code": 200,
  "msg": "Text generation completed successfully.",
  "data": {
    "callbackType": "text",
    "task_id": "2fac****9f72",
    "data": []
  }
}

状态码说明

code

integer

必填

回调状态码，表示任务处理结果：

状态码	说明
200	成功 - 音乐生成完成
400	请求错误 - 参数错误或内容违规
401	未授权 - API密钥无效
413	内容过长 - 提示词或风格描述超出限制
429	积分不足 - 账户积分余额不足
500	服务器错误 - 请稍后重试

msg

string

必填

状态消息，提供详细的状态描述

data.callbackType

string

必填

回调类型，表示当前回调阶段：

text: 文本生成完成
first: 第一首音乐生成完成
complete: 所有音乐生成完成
failed: 任务失败

data.task_id

string

必填

任务ID，与您提交任务时返回的taskId一致

data.data

array

音乐生成结果信息，成功时返回

data.data[].id

string

音频唯一标识

data.data[].audio_url

string

音频文件下载链接

data.data[].source_audio_url

string

原始音频文件下载链接

data.data[].stream_audio_url

string

流式音频播放链接

data.data[].image_url

string

音乐封面图片链接

data.data[].prompt

string

生成使用的提示词/歌词

data.data[].model_name

string

使用的AI模型名称

data.data[].title

string

音乐标题

data.data[].tags

string

音乐风格标签

data.data[].createTime

string

创建时间

data.data[].duration

number

音频时长（秒）

回调接收示例

以下是各种流行编程语言接收回调的示例代码：

Node.js
Python
PHP

const express = require('express');
const app = express();

app.use(express.json());

app.post('/music-callback', (req, res) => {
  const { code, msg, data } = req.body;
  
  console.log('收到音乐生成回调:', {
    taskId: data.task_id,
    callbackType: data.callbackType,
    status: code,
    message: msg
  });
  
  if (code === 200) {
    // 任务成功
    const { callbackType, data: musicData } = data;
    
    switch (callbackType) {
      case 'text':
        console.log('文本生成完成');
        break;
        
      case 'first':
        console.log('第一首音乐生成完成');
        if (musicData.length > 0) {
          console.log(`音乐标题: ${musicData[0].title}`);
          console.log(`音频链接: ${musicData[0].audio_url}`);
          console.log(`时长: ${musicData[0].duration}秒`);
        }
        break;
        
      case 'complete':
        console.log('所有音乐生成完成');
        console.log(`共生成 ${musicData.length} 首音乐:`);
        musicData.forEach((track, index) => {
          console.log(`音乐 ${index + 1}: ${track.title} - ${track.audio_url}`);
        });
        
        // 处理生成的音乐
        // 可以下载音乐、保存到本地等
        break;
    }
    
  } else {
    // 任务失败
    console.log('音乐生成失败:', msg);
    
    // 处理失败情况...
    if (code === 400) {
      console.log('参数错误或内容违规');
    } else if (code === 429) {
      console.log('积分不足');
    } else if (code === 500) {
      console.log('服务器内部错误');
    }
  }
  
  // 返回200状态码确认收到回调
  res.status(200).json({ status: 'received' });
});

app.listen(3000, () => {
  console.log('回调服务器运行在端口 3000');
});

from flask import Flask, request, jsonify
import requests

app = Flask(__name__)

@app.route('/music-callback', methods=['POST'])
def handle_callback():
    data = request.json
    
    code = data.get('code')
    msg = data.get('msg')
    callback_data = data.get('data', {})
    task_id = callback_data.get('task_id')
    callback_type = callback_data.get('callbackType')
    music_data = callback_data.get('data', [])
    
    print(f"收到音乐生成回调: {task_id}, 类型: {callback_type}, 状态: {code}")
    
    if code == 200:
        # 任务成功
        if callback_type == 'text':
            print("文本生成完成")
            
        elif callback_type == 'first':
            print("第一首音乐生成完成")
            if music_data:
                track = music_data[0]
                print(f"音乐标题: {track.get('title')}")
                print(f"音频链接: {track.get('audio_url')}")
                print(f"时长: {track.get('duration')}秒")
                
        elif callback_type == 'complete':
            print("所有音乐生成完成")
            print(f"共生成 {len(music_data)} 首音乐:")
            
            for i, track in enumerate(music_data):
                print(f"音乐 {i + 1}: {track.get('title')} - {track.get('audio_url')}")
                
                # 下载音乐示例
                try:
                    audio_url = track.get('audio_url')
                    if audio_url:
                        response = requests.get(audio_url)
                        if response.status_code == 200:
                            filename = f"music_{task_id}_{i + 1}.mp3"
                            with open(filename, "wb") as f:
                                f.write(response.content)
                            print(f"音乐已保存为 {filename}")
                except Exception as e:
                    print(f"音乐下载失败: {e}")
                    
    else:
        # 任务失败
        print(f"音乐生成失败: {msg}")
        
        # 处理失败情况...
        if code == 400:
            print("参数错误或内容违规")
        elif code == 429:
            print("积分不足")
        elif code == 500:
            print("服务器内部错误")
    
    # 返回200状态码确认收到回调
    return jsonify({'status': 'received'}), 200

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=3000)

<?php
header('Content-Type: application/json');

// 获取POST数据
$input = file_get_contents('php://input');
$data = json_decode($input, true);

$code = $data['code'] ?? null;
$msg = $data['msg'] ?? '';
$callbackData = $data['data'] ?? [];
$taskId = $callbackData['task_id'] ?? '';
$callbackType = $callbackData['callbackType'] ?? '';
$musicData = $callbackData['data'] ?? [];

error_log("收到音乐生成回调: $taskId, 类型: $callbackType, 状态: $code");

if ($code === 200) {
    // 任务成功
    switch ($callbackType) {
        case 'text':
            error_log("文本生成完成");
            break;
            
        case 'first':
            error_log("第一首音乐生成完成");
            if (!empty($musicData)) {
                $track = $musicData[0];
                error_log("音乐标题: " . ($track['title'] ?? ''));
                error_log("音频链接: " . ($track['audio_url'] ?? ''));
                error_log("时长: " . ($track['duration'] ?? 0) . "秒");
            }
            break;
            
        case 'complete':
            error_log("所有音乐生成完成");
            error_log("共生成 " . count($musicData) . " 首音乐:");
            
            foreach ($musicData as $index => $track) {
                $title = $track['title'] ?? '';
                $audioUrl = $track['audio_url'] ?? '';
                error_log("音乐 " . ($index + 1) . ": $title - $audioUrl");
                
                // 下载音乐示例
                try {
                    if ($audioUrl) {
                        $audioContent = file_get_contents($audioUrl);
                        if ($audioContent !== false) {
                            $filename = "music_{$taskId}_" . ($index + 1) . ".mp3";
                            file_put_contents($filename, $audioContent);
                            error_log("音乐已保存为 $filename");
                        }
                    }
                } catch (Exception $e) {
                    error_log("音乐下载失败: " . $e->getMessage());
                }
            }
            break;
    }
    
} else {
    // 任务失败
    error_log("音乐生成失败: $msg");
    
    // 处理失败情况...
    if ($code === 400) {
        error_log("参数错误或内容违规");
    } elseif ($code === 429) {
        error_log("积分不足");
    } elseif ($code === 500) {
        error_log("服务器内部错误");
    }
}

// 返回200状态码确认收到回调
http_response_code(200);
echo json_encode(['status' => 'received']);
?>

最佳实践

回调URL配置建议

使用HTTPS: 确保回调URL使用HTTPS协议，保证数据传输安全
验证来源: 在回调处理中验证请求来源的合法性
幂等处理: 同一个taskId可能收到多次回调，确保处理逻辑具有幂等性
快速响应: 回调处理应尽快返回200状态码，避免超时
异步处理: 复杂的业务逻辑应异步处理，避免阻塞回调响应
分阶段处理: 根据不同的回调阶段（text、first、complete）进行相应的业务处理
音乐下载: 音乐下载和处理应在异步任务中进行，避免阻塞回调响应

重要提醒

回调URL必须是公网可访问的地址
服务器必须在15秒内响应，否则视为超时
连续3次重试失败后，系统将停止发送回调
请确保回调处理逻辑的稳定性，避免因异常导致回调失败
生成的音频URL可能有时效限制，建议及时下载保存
注意内容合规，避免因违规导致生成失败
音乐生成有三个阶段，每个阶段都会触发回调通知

故障排除

如果您没有收到回调通知，请检查以下几点：

网络连接问题

确认回调URL能够从公网访问
检查防火墙设置，确保入站请求未被阻止
验证域名解析是否正确

服务器响应问题

确保服务器在15秒内返回HTTP 200状态码
检查服务器日志是否有错误信息
验证接口路径和HTTP方法是否正确

内容格式问题

确认接收到的POST请求体为JSON格式
检查Content-Type是否为application/json
验证JSON解析是否正确

音乐处理问题

确认音频URL是否可访问
检查音乐下载权限和网络连接
验证音乐保存路径和权限
注意音乐内容是否符合内容政策

回调阶段处理

理解三个回调阶段的差异和处理方式
text阶段：仅表示文本生成完成，无音频数据
first阶段：第一首音乐完成，包含一首音乐的数据
complete阶段：所有音乐完成，包含完整的音乐列表

替代方案

如果您无法使用回调机制，也可以使用轮询方式：

轮询查询结果

使用获取音乐生成详情接口定期查询任务状态。建议每30秒查询一次。

Generate Music

Lyrics Generation

WAV Conversion

Vocal Removal

Music Video Generation

Account Management

文件上传API

音乐生成回调

回调机制概述

回调时机

回调方法

回调请求格式

状态码说明

回调接收示例

最佳实践

回调URL配置建议

重要提醒

故障排除

替代方案

轮询查询结果

Generate Music

Lyrics Generation

WAV Conversion

Vocal Removal

Music Video Generation

Account Management

文件上传API

​回调机制概述

​回调时机

​回调方法

​回调请求格式

​状态码说明

​回调接收示例

​最佳实践

​回调URL配置建议

​重要提醒

​故障排除

​替代方案

轮询查询结果

回调机制概述

回调时机

回调方法

回调请求格式

状态码说明

回调接收示例

最佳实践

回调URL配置建议

重要提醒

故障排除

替代方案