callBackUrl 参数设置回调URL。任务完成时,系统将自动向您指定的地址推送结果。
回调机制概述
回调机制消除了轮询API获取任务状态的需要。系统会主动向您的服务器推送任务完成结果。
回调时机
系统将在以下情况发送回调通知:- 封面生成任务成功完成
- 封面生成任务失败
- 任务处理过程中发生错误
回调方式
- HTTP方法: POST
- 内容类型: application/json
- 超时设置: 15秒
回调请求格式
任务完成时,系统将向您的callBackUrl 发送POST请求:
复制
{
"code": 200,
"data": {
"images": [
"https://tempfile.aiquickdraw.com/s/1753958521_6c1b3015141849d1a9bf17b738ce9347.png",
"https://tempfile.aiquickdraw.com/s/1753958524_c153143acc6340908431cf0e90cbce9e.png"
],
"taskId": "21aee3c3c2a01fa5e030b3799fa4dd56"
},
"msg": "success"
}
状态码说明
回调状态码,表示任务处理结果:
| 状态码 | 描述 |
|---|---|
| 200 | 成功 - 请求已成功处理 |
| 400 | 验证错误 - 请求参数有误 |
| 408 | 超出限制 - 超时 |
| 500 | 服务器错误 - 处理请求时发生意外错误 |
| 501 | 封面生成失败 |
| 531 | 服务器错误 - 抱歉,由于问题生成失败。您的积分已退还。请重试 |
状态消息,提供更详细的状态描述
任务ID,与您提交任务时返回的taskId一致
生成的封面图片URL数组,成功时返回。通常包含2张不同风格的封面图片
回调接收示例
以下是常用编程语言接收回调的示例代码:- Node.js
- Python
- Java
- PHP
复制
const express = require('express');
const app = express();
app.use(express.json());
app.post('/suno-cover-callback', (req, res) => {
const { code, msg, data } = req.body;
console.log('收到封面生成回调:', {
taskId: data.taskId,
status: code,
message: msg
});
if (code === 200) {
// 任务成功完成
console.log('封面生成完成');
const images = data.images;
if (images && images.length > 0) {
console.log('生成的封面图片:');
images.forEach((imageUrl, index) => {
console.log(`封面${index + 1}: ${imageUrl}`);
});
// 处理封面图片
// 可以下载图片、保存到本地、更新数据库等
downloadImages(images, data.taskId);
}
} else {
// 任务失败
console.log('封面生成失败:', msg);
// 处理失败情况...
}
// 返回200状态码确认收到回调
res.status(200).json({ status: 'received' });
});
// 下载图片函数
async function downloadImages(imageUrls, taskId) {
const fs = require('fs');
const path = require('path');
const https = require('https');
// 创建目录
const dir = `covers/${taskId}`;
if (!fs.existsSync(dir)) {
fs.mkdirSync(dir, { recursive: true });
}
for (let i = 0; i < imageUrls.length; i++) {
const url = imageUrls[i];
const filename = path.join(dir, `cover_${i + 1}.png`);
try {
await downloadFile(url, filename);
console.log(`已保存封面: ${filename}`);
} catch (error) {
console.error(`下载失败: ${error.message}`);
}
}
}
function downloadFile(url, filename) {
return new Promise((resolve, reject) => {
const file = fs.createWriteStream(filename);
https.get(url, (response) => {
response.pipe(file);
file.on('finish', () => {
file.close();
resolve();
});
}).on('error', (err) => {
fs.unlink(filename, () => {}); // 删除失败的文件
reject(err);
});
});
}
app.listen(3000, () => {
console.log('回调服务器运行在端口3000');
});
复制
from flask import Flask, request, jsonify
import requests
import os
from urllib.parse import urlparse
app = Flask(__name__)
@app.route('/suno-cover-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('taskId')
images = callback_data.get('images')
print(f"收到封面生成回调: {task_id}, 状态: {code}, 消息: {msg}")
if code == 200:
# 任务成功完成
print("封面生成完成")
if images:
print("生成的封面图片:")
for i, image_url in enumerate(images, 1):
print(f"封面{i}: {image_url}")
# 下载封面图片
download_images(images, task_id)
else:
# 任务失败
print(f"封面生成失败: {msg}")
# 处理失败情况...
# 返回200状态码确认收到回调
return jsonify({'status': 'received'}), 200
def download_images(image_urls, task_id):
"""下载封面图片"""
# 创建目录
dir_path = f"covers/{task_id}"
os.makedirs(dir_path, exist_ok=True)
for i, url in enumerate(image_urls, 1):
try:
# 获取文件扩展名
parsed_url = urlparse(url)
file_ext = os.path.splitext(parsed_url.path)[1] or '.png'
filename = os.path.join(dir_path, f"cover_{i}{file_ext}")
# 下载文件
response = requests.get(url, stream=True)
if response.status_code == 200:
with open(filename, 'wb') as f:
for chunk in response.iter_content(chunk_size=8192):
f.write(chunk)
print(f"已保存封面: {filename}")
else:
print(f"下载失败 {url}: HTTP {response.status_code}")
except Exception as e:
print(f"下载失败 {url}: {e}")
if __name__ == '__main__':
app.run(host='0.0.0.0', port=3000)
复制
/**
* @param request 回调请求
* @return ResponseEntity
* @author zj
* @description 处理Suno Cover生成回调
* @date 2025/1/15
**/
@PostMapping("/suno-cover-callback")
@Operation(summary = "Suno Cover生成回调", description = "接收Cover生成完成通知")
public ResponseEntity<Map<String, String>> handleCoverCallback(
@RequestBody CoverCallbackRequest request) {
log.info("收到封面生成回调: taskId={}, status={}, message={}",
request.getData().getTaskId(), request.getCode(), request.getMsg());
try {
if (request.getCode() == 200) {
// 任务成功完成
log.info("封面生成完成");
List<String> images = request.getData().getImages();
if (images != null && !images.isEmpty()) {
log.info("生成的封面图片: {}", images);
// 处理封面图片
processCoverImages(request.getData().getTaskId(), images);
}
} else {
// 任务失败
log.error("封面生成失败: {}", request.getMsg());
// 处理失败情况
handleCoverGenerationFailure(request.getData().getTaskId(),
request.getCode(), request.getMsg());
}
// 更新任务状态
coverTaskService.updateTaskStatus(request.getData().getTaskId(),
request.getCode(), request.getMsg(), request.getData().getImages());
} catch (Exception e) {
log.error("处理封面生成回调失败", e);
return ResponseEntity.status(500)
.body(Map.of("status", "error", "message", e.getMessage()));
}
// 返回200状态码确认收到回调
return ResponseEntity.ok(Map.of("status", "received"));
}
/**
* @param taskId 任务ID
* @param imageUrls 图片URL列表
* @author zj
* @description 处理封面图片
* @date 2025/1/15
**/
private void processCoverImages(String taskId, List<String> imageUrls) {
// 异步下载图片
CompletableFuture.runAsync(() -> {
try {
downloadCoverImages(taskId, imageUrls);
} catch (Exception e) {
log.error("下载封面图片失败: taskId={}", taskId, e);
}
});
}
/**
* @param taskId 任务ID
* @param imageUrls 图片URL列表
* @author zj
* @description 下载封面图片
* @date 2025/1/15
**/
private void downloadCoverImages(String taskId, List<String> imageUrls) {
String dirPath = "covers/" + taskId;
File dir = new File(dirPath);
if (!dir.exists()) {
dir.mkdirs();
}
for (int i = 0; i < imageUrls.size(); i++) {
String url = imageUrls.get(i);
String filename = dirPath + "/cover_" + (i + 1) + ".png";
try {
downloadFile(url, filename);
log.info("已保存封面: {}", filename);
} catch (Exception e) {
log.error("下载失败: {}", url, e);
}
}
}
@Data
public class CoverCallbackRequest {
private Integer code;
private String msg;
private CoverCallbackData data;
}
@Data
public class CoverCallbackData {
private String taskId;
private List<String> images;
}
复制
<?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['taskId'] ?? '';
$images = $callbackData['images'] ?? null;
error_log("收到封面生成回调: $taskId, 状态: $code, 消息: $msg");
if ($code === 200) {
// 任务成功完成
error_log("封面生成完成");
if ($images && is_array($images) && count($images) > 0) {
error_log("生成的封面图片: " . implode(', ', $images));
// 下载封面图片
downloadCoverImages($taskId, $images);
}
} else {
// 任务失败
error_log("封面生成失败: $msg");
// 处理失败情况...
}
/**
* 下载封面图片
* @param string $taskId 任务ID
* @param array $imageUrls 图片URL数组
*/
function downloadCoverImages($taskId, $imageUrls) {
// 创建目录
$dir = "covers/$taskId";
if (!is_dir($dir)) {
mkdir($dir, 0777, true);
}
foreach ($imageUrls as $index => $url) {
$filename = $dir . "/cover_" . ($index + 1) . ".png";
try {
$imageContent = file_get_contents($url);
if ($imageContent !== false) {
file_put_contents($filename, $imageContent);
error_log("已保存封面: $filename");
} else {
error_log("下载失败: $url");
}
} catch (Exception $e) {
error_log("下载失败 $url: " . $e->getMessage());
}
}
}
// 返回200状态码确认收到回调
http_response_code(200);
echo json_encode(['status' => 'received']);
?>
最佳实践
回调URL配置建议
- 使用HTTPS: 确保回调URL使用HTTPS协议以保证数据传输安全
- 验证来源: 在回调处理中验证请求来源的合法性
- 幂等处理: 同一taskId可能收到多次回调,确保处理逻辑是幂等的
- 快速响应: 回调处理应尽快返回200状态码以避免超时
- 异步处理: 复杂的业务逻辑应异步处理以避免阻塞回调响应
- 图片管理: 及时下载和保存图片,注意URL的有效期
- 错误重试: 针对下载失败的图片实现重试机制
重要提醒
- 回调URL必须是公开可访问的地址
- 服务器必须在15秒内响应,否则将被认为超时
- 如果连续3次重试失败,系统将停止发送回调
- 请确保回调处理逻辑的稳定性,避免因异常导致回调失败
- 封面图片URL可能有时效性,建议及时下载保存
- 通常会生成2张不同风格的封面图片供选择
- 注意处理图片下载失败的异常情况
故障排查
如果您未收到回调通知,请检查以下内容:网络连接问题
网络连接问题
- 确认回调URL可以从公网访问
- 检查防火墙设置,确保入站请求未被阻止
- 验证域名解析是否正确
服务器响应问题
服务器响应问题
- 确保服务器在15秒内返回HTTP 200状态码
- 检查服务器日志是否有错误消息
- 验证接口路径和HTTP方法是否正确
内容格式问题
内容格式问题
- 确认收到的POST请求体为JSON格式
- 检查Content-Type是否为application/json
- 验证JSON解析是否正确
图片处理问题
图片处理问题
- 确认图片URL是否可访问
- 检查图片下载权限和网络连接
- 验证文件保存路径和权限
- 注意图片URL的有效期限制
替代方案
如果您无法使用回调机制,也可以使用轮询方式:轮询查询结果
使用获取Cover详情端点定期查询任务状态。我们建议每30秒查询一次。
