当您向添加人声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": []
}
}
状态码说明
回调状态码,表示任务处理结果:| 状态码 | 说明 |
|---|
| 200 | 成功 - 人声生成完成 |
| 400 | 请求错误 - 参数错误或内容违规 |
| 401 | 未授权 - API密钥无效 |
| 413 | 内容过长 - 提示词或风格描述超出限制 |
| 429 | 积分不足 - 账户积分余额不足 |
| 500 | 服务器错误 - 请稍后重试 |
回调类型,表示当前回调阶段:
text: 文本生成完成
first: 第一个人声音轨生成完成
complete: 所有人声音轨生成完成
failed: 任务失败
data.data[].source_audio_url
原始源音频文件下载链接
data.data[].stream_audio_url
带人声的流式音频播放链接
回调接收示例
以下是使用各种流行编程语言接收回调的示例代码:
const express = require('express');
const app = express();
app.use(express.json());
app.post('/vocals-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: vocalsData } = data;
switch (callbackType) {
case 'text':
console.log('文本生成完成');
break;
case 'first':
console.log('第一个人声音轨生成完成');
if (vocalsData.length > 0) {
console.log(`音轨标题: ${vocalsData[0].title}`);
console.log(`人声音频链接: ${vocalsData[0].audio_url}`);
console.log(`时长: ${vocalsData[0].duration} 秒`);
console.log(`人声提示词: ${vocalsData[0].prompt}`);
}
break;
case 'complete':
console.log('所有人声音轨生成完成');
console.log(`共生成 ${vocalsData.length} 个人声音轨:`);
vocalsData.forEach((track, index) => {
console.log(`音轨 ${index + 1}: ${track.title} - ${track.audio_url}`);
console.log(`人声: ${track.prompt}`);
});
// 处理生成的人声音轨
// 可以下载音频、本地保存等
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('/vocals-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')
vocals_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 vocals_data:
track = vocals_data[0]
print(f"音轨标题: {track.get('title')}")
print(f"人声音频链接: {track.get('audio_url')}")
print(f"时长: {track.get('duration')} 秒")
print(f"人声提示词: {track.get('prompt')}")
elif callback_type == 'complete':
print("所有人声音轨生成完成")
print(f"共生成 {len(vocals_data)} 个人声音轨:")
for i, track in enumerate(vocals_data):
print(f"音轨 {i + 1}: {track.get('title')} - {track.get('audio_url')}")
print(f"人声: {track.get('prompt')}")
# 下载人声音频示例
try:
audio_url = track.get('audio_url')
if audio_url:
response = requests.get(audio_url)
if response.status_code == 200:
filename = f"vocals_{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'] ?? '';
$vocalsData = $callbackData['data'] ?? [];
error_log("收到人声生成回调: $taskId, 类型: $callbackType, 状态: $code");
if ($code === 200) {
// 任务成功
switch ($callbackType) {
case 'text':
error_log("文本生成完成");
break;
case 'first':
error_log("第一个人声音轨生成完成");
if (!empty($vocalsData)) {
$track = $vocalsData[0];
error_log("音轨标题: " . ($track['title'] ?? ''));
error_log("人声音频链接: " . ($track['audio_url'] ?? ''));
error_log("时长: " . ($track['duration'] ?? 0) . " 秒");
error_log("人声提示词: " . ($track['prompt'] ?? ''));
}
break;
case 'complete':
error_log("所有人声音轨生成完成");
error_log("共生成 " . count($vocalsData) . " 个人声音轨:");
foreach ($vocalsData as $index => $track) {
$title = $track['title'] ?? '';
$audioUrl = $track['audio_url'] ?? '';
$prompt = $track['prompt'] ?? '';
error_log("音轨 " . ($index + 1) . ": $title - $audioUrl");
error_log("人声: $prompt");
// 下载人声音频示例
try {
if ($audioUrl) {
$audioContent = file_get_contents($audioUrl);
if ($audioContent !== false) {
$filename = "vocals_{$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秒查询一次。