> ## 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. # 音乐生成回调 > 当音乐生成任务完成时，系统会通过POST请求将结果发送到您提供的回调URL 当您向音乐生成API提交任务时，可以使用 `callBackUrl` 参数设置回调URL。当任务完成时，系统会自动将结果推送到您指定的地址。 ## 回调机制概述回调机制免除了轮询API获取任务状态的需要。系统会主动将任务完成结果推送到您的服务器。 ### 回调时机系统会在以下情况发送回调通知： * 文本生成完成（`text` 阶段） * 第一首音乐生成完成（`first` 阶段） * 所有音乐生成完成（`complete` 阶段） * 音乐生成任务失败 * 任务处理过程中发生错误 ### 回调方法 * **HTTP方法**: POST * **Content Type**: application/json * **超时设置**: 15秒 ## 回调请求格式当任务完成时，系统会按以下格式向您的 `callBackUrl` 发送POST请求： ```json 文本生成完成回调 theme={null} { "code": 200, "msg": "Text generation completed successfully.", "data": { "callbackType": "text", "task_id": "2fac****9f72", "data": [] } } ``` ```json 第一首完成回调 theme={null} { "code": 200, "msg": "First track generated 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] 夜晚城市灯火辉煌", "model_name": "chirp-v3-5", "title": "钢铁侠", "tags": "electrifying, rock", "createTime": "2025-01-01 00:00:00", "duration": 198.44 } ] } } ``` ```json 全部完成回调 theme={null} { "code": 200, "msg": "All generated 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] 夜晚城市灯火辉煌", "model_name": "chirp-v3-5", "title": "钢铁侠", "tags": "electrifying, rock", "createTime": "2025-01-01 00:00:00", "duration": 198.44 }, { "id": "bd15****1873", "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] 夜晚城市灯火辉煌", "model_name": "chirp-v3-5", "title": "钢铁侠", "tags": "electrifying, rock", "createTime": "2025-01-01 00:00:00", "duration": 228.28 } ] } } ``` ```json 失败回调 theme={null} { "code": 400, "msg": "Failed to generate music, containing sensitive content", "data": { "callbackType": "failed", "task_id": "2fac****9f72", "data": [] } } ``` ## 状态码说明回调状态码，表示任务处理结果： | 状态码 | 说明 | | --- | ------------------- | | 200 | 成功 - 音乐生成完成 | | 400 | 请求错误 - 参数错误或内容违规 | | 401 | 未授权 - API密钥无效 | | 413 | 内容过长 - 提示词或风格描述超出限制 | | 429 | 积分不足 - 账户积分余额不足 | | 500 | 服务器错误 - 请稍后重试 | 状态消息，提供详细的状态描述回调类型，表示当前回调阶段： * `text`: 文本生成完成 * `first`: 第一首音乐生成完成 * `complete`: 所有音乐生成完成 * `failed`: 任务失败任务ID，与您提交任务时返回的taskId一致音乐生成结果信息，成功时返回音频唯一标识音频文件下载链接原始音频文件下载链接流式音频播放链接音乐封面图片链接生成使用的提示词/歌词使用的AI模型名称音乐标题音乐风格标签创建时间音频时长（秒） ## 回调接收示例以下是各种流行编程语言接收回调的示例代码： ```javascript theme={null} 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'); }); ``` ```python theme={null} 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 theme={null} $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配置建议 1. **使用HTTPS**: 确保回调URL使用HTTPS协议，保证数据传输安全 2. **验证来源**: 在回调处理中验证请求来源的合法性 3. **幂等处理**: 同一个taskId可能收到多次回调，确保处理逻辑具有幂等性 4. **快速响应**: 回调处理应尽快返回200状态码，避免超时 5. **异步处理**: 复杂的业务逻辑应异步处理，避免阻塞回调响应 6. **分阶段处理**: 根据不同的回调阶段（text、first、complete）进行相应的业务处理 7. **音乐下载**: 音乐下载和处理应在异步任务中进行，避免阻塞回调响应 ### 重要提醒 * 回调URL必须是公网可访问的地址 * 服务器必须在15秒内响应，否则视为超时 * 连续3次重试失败后，系统将停止发送回调 * 请确保回调处理逻辑的稳定性，避免因异常导致回调失败 * 生成的音频URL可能有时效限制，建议及时下载保存 * 注意内容合规，避免因违规导致生成失败 * 音乐生成有三个阶段，每个阶段都会触发回调通知 ## 故障排除如果您没有收到回调通知，请检查以下几点： * 确认回调URL能够从公网访问 * 检查防火墙设置，确保入站请求未被阻止 * 验证域名解析是否正确 * 确保服务器在15秒内返回HTTP 200状态码 * 检查服务器日志是否有错误信息 * 验证接口路径和HTTP方法是否正确 * 确认接收到的POST请求体为JSON格式 * 检查Content-Type是否为application/json * 验证JSON解析是否正确 * 确认音频URL是否可访问 * 检查音乐下载权限和网络连接 * 验证音乐保存路径和权限 * 注意音乐内容是否符合内容政策 * 理解三个回调阶段的差异和处理方式 * text阶段：仅表示文本生成完成，无音频数据 * first阶段：第一首音乐完成，包含一首音乐的数据 * complete阶段：所有音乐完成，包含完整的音乐列表 ## 替代方案如果您无法使用回调机制，也可以使用轮询方式：使用获取音乐生成详情接口定期查询任务状态。建议每30秒查询一次。