添加伴奏回调

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

回调机制概述

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

回调时机

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

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

回调方式

HTTP方法: POST
内容类型: application/json
超时时间: 15秒

回调请求格式

任务完成后，系统会向您的callBackUrl发送如下格式的POST请求：

{
  "code": 200,
  "msg": "文本生成完成",
  "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('/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');
});

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
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'] ?? '';
$instrumentalData = $callbackData['data'] ?? [];

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

if ($code === 200) {
    // 任务成功
    switch ($callbackType) {
        case 'text':
            error_log("文本生成完成");
            break;
            
        case 'first':
            error_log("第一个伴奏音轨生成完成");
            if (!empty($instrumentalData)) {
                $track = $instrumentalData[0];
                error_log("音轨标题: " . ($track['title'] ?? ''));
                error_log("伴奏音频链接: " . ($track['audio_url'] ?? ''));
                error_log("时长: " . ($track['duration'] ?? 0) . " 秒");
                error_log("伴奏风格: " . ($track['tags'] ?? ''));
            }
            break;
            
        case 'complete':
            error_log("所有伴奏音轨生成完成");
            error_log("共生成 " . count($instrumentalData) . " 个伴奏音轨:");
            
            foreach ($instrumentalData as $index => $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']);
?>

最佳实践

伴奏生成回调配置建议

使用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

添加伴奏回调

回调机制概述

回调时机

回调方式

回调请求格式

状态码说明

回调接收示例

最佳实践

伴奏生成回调配置建议

重要提醒

故障排除

替代方案

轮询查询结果

Generate Music

Lyrics Generation

WAV Conversion

Vocal Removal

Music Video Generation

Account Management

文件上传API

​回调机制概述

​回调时机

​回调方式

​回调请求格式

​状态码说明

​回调接收示例

​最佳实践

​伴奏生成回调配置建议

​重要提醒

​故障排除

​替代方案

轮询查询结果

回调机制概述

回调时机

回调方式

回调请求格式

状态码说明

回调接收示例

最佳实践

伴奏生成回调配置建议

重要提醒

故障排除

替代方案