> ## 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 * **内容类型**: application/json * **超时时间**: 15秒 ## 回调请求格式任务完成后，系统会向您的`callBackUrl`发送如下格式的POST请求： ```json 文本生成完成回调 theme={null} { "code": 200, "msg": "文本生成完成", "data": { "callbackType": "text", "task_id": "2fac****9f72", "data": [] } } ``` ```json 第一个音轨完成回调 theme={null} { "code": 200, "msg": "第一个伴奏音轨生成成功", "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": "[Instrumental] 带有环境质感的轻松钢琴旋律", "model_name": "chirp-v3-5", "title": "轻松钢琴伴奏", "tags": "轻松, 钢琴, 伴奏, 环境音乐", "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": "[Instrumental] 带有环境质感的轻松钢琴旋律", "model_name": "chirp-v3-5", "title": "轻松钢琴伴奏", "tags": "轻松, 钢琴, 伴奏, 环境音乐", "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": "[Instrumental] 分层伴奏编排", "model_name": "chirp-v3-5", "title": "轻松钢琴伴奏", "tags": "轻松, 钢琴, 伴奏, 环境音乐", "createTime": "2025-01-01 00:00:00", "duration": 228.28 } ] } } ``` ```json 失败回调 theme={null} { "code": 400, "msg": "伴奏生成失败，源音频格式无效", "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('/instrumental-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: instrumentalData } = data; switch (callbackType) { case 'text': console.log('文本生成完成'); break; case 'first': console.log('第一个伴奏音轨生成完成'); if (instrumentalData.length > 0) { console.log(`音轨标题: ${instrumentalData[0].title}`); console.log(`伴奏音频链接: ${instrumentalData[0].audio_url}`); console.log(`时长: ${instrumentalData[0].duration} 秒`); console.log(`伴奏风格: ${instrumentalData[0].tags}`); } break; case 'complete': console.log('所有伴奏音轨生成完成'); console.log(`共生成 ${instrumentalData.length} 个伴奏音轨:`); instrumentalData.forEach((track, index) => { console.log(`音轨 ${index + 1}: ${track.title} - ${track.audio_url}`); console.log(`风格: ${track.tags}`); }); // 处理生成的伴奏音轨 // 可以下载音频、本地保存等 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('/instrumental-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') instrumental_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 instrumental_data: track = instrumental_data[0] print(f"音轨标题: {track.get('title')}") print(f"伴奏音频链接: {track.get('audio_url')}") print(f"时长: {track.get('duration')} 秒") print(f"伴奏风格: {track.get('tags')}") elif callback_type == 'complete': print("所有伴奏音轨生成完成") print(f"共生成 {len(instrumental_data)} 个伴奏音轨:") for i, track in enumerate(instrumental_data): print(f"音轨 {i + 1}: {track.get('title')} - {track.get('audio_url')}") print(f"风格: {track.get('tags')}") # 下载伴奏音频示例 try: audio_url = track.get('audio_url') if audio_url: response = requests.get(audio_url) if response.status_code == 200: filename = f"instrumental_{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'] ?? ''; $tags = $track['tags'] ?? ''; error_log("音轨 " . ($index + 1) . ": $title - $audioUrl"); error_log("风格: $tags"); // 下载伴奏音频示例 try { if ($audioUrl) { $audioContent = file_get_contents($audioUrl); if ($audioContent !== false) { $filename = "instrumental_{$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']); ?> ``` ## 最佳实践 ### 伴奏生成回调配置建议 1. **使用HTTPS**: 确保回调URL使用HTTPS协议以保证数据传输安全 2. **验证来源**: 在回调处理中验证请求来源的合法性 3. **幂等处理**: 确保处理逻辑具有幂等性，因为相同taskId可能收到多次回调 4. **快速响应**: 回调处理应快速返回200状态码，避免超时 5. **异步处理**: 复杂的业务逻辑应异步处理，避免阻塞回调响应 6. **分阶段处理**: 针对不同回调阶段（text、first、complete）实施相应的业务逻辑 7. **音频质量评估**: 实施生成伴奏音轨的音频质量评估 8. **风格验证**: 验证生成的伴奏是否符合请求的风格和特征 ### 重要提醒 * 回调URL必须可公开访问 * 服务器必须在15秒内响应，否则视为超时 * 连续3次重试失败后，系统将停止发送回调 * 确保回调处理逻辑的稳定性，避免因异常导致回调失败 * 生成的伴奏音频URL可能有时效性，建议及时下载保存 * 注意源音频质量以确保最佳的伴奏生成效果 * 伴奏生成分为三个阶段，每个阶段都会触发回调通知 * 考虑实施源文件的音频格式验证 ## 故障排除如果您没有收到回调通知，请检查以下项目： * 确认回调URL可从公网访问 * 检查防火墙设置，确保入站请求不被阻止 * 验证域名解析是否正确 * 确保服务器在15秒内返回HTTP 200状态码 * 检查服务器日志中的错误信息 * 验证接口路径和HTTP方法是否正确 * 确认接收到的POST请求体为JSON格式 * 检查Content-Type是否为application/json * 验证JSON解析是否正确 * 确认伴奏音频URL可访问 * 检查伴奏音频下载权限和网络连通性 * 验证音频保存路径和权限 * 确保源音频格式受支持且有效 * 验证伴奏质量是否符合您的应用要求 * 理解三个回调阶段的差异和处理方法 * text阶段：仅表示文本生成完成，无音频数据 * first阶段：第一个伴奏音轨完成，包含一个音轨的数据 * complete阶段：所有伴奏音轨完成，包含完整的伴奏音轨列表 * 实施源文件的音频格式验证 * 检查伴奏音频质量和格式兼容性 * 评估生成的伴奏是否符合风格要求 * 适当处理不同的伴奏风格和编排 ## 替代方案如果您无法使用回调机制，还可以使用轮询方式：使用获取音乐生成详情接口定期查询任务状态。建议每30秒查询一次。