当您向 Suno API 提交音乐扩展任务时,可以通过 callBackUrl 参数设置回调地址。任务完成后,系统会自动将结果推送到您指定的地址。

回调机制概述

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

回调时机

系统会在以下情况发送回调通知:
  • 文本生成完成(callbackType: “text”)
  • 第一首音乐扩展完成(callbackType: “first”)
  • 全部音乐扩展完成(callbackType: “complete”)
  • 音乐扩展任务失败
  • 任务处理过程中发生错误

回调方式

  • HTTP 方法: POST
  • 内容类型: application/json
  • 超时设置: 15 秒
  • 重试机制: 失败后重试 3 次,间隔分别为 1 分钟、5 分钟、15 分钟

回调请求格式

任务进展或完成后,系统会向您的 callBackUrl 发送 POST 请求,格式如下:
{
  "code": 200,
  "msg": "All generated successfully.",
  "data": {
    "callbackType": "complete",
    "task_id": "2fac****9f72",
    "data": [
      {
        "id": "8551****662c",
        "audio_url": "https://example.cn/****.mp3",
        "stream_audio_url": "https://example.cn/****",
        "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
      }
    ]
  }
}

状态码说明

code
integer
required
回调状态码,表示任务处理结果:
状态码说明
200成功 - 请求已成功处理
400验证错误 - 歌词包含受版权保护的内容
408超出限制 - 超时
413冲突 - 上传的音频与现有艺术作品匹配
500服务器错误 - 处理请求时发生意外错误
501音频生成失败
531服务器错误 - 抱歉,由于问题生成失败。您的积分已退还。请重试
msg
string
required
状态消息,提供详细的状态描述
data.callbackType
string
required
回调类型,表示生成阶段:
  • text: 文本生成完成
  • first: 第一首完成
  • complete: 全部完成
  • error: 生成失败
data.task_id
string
required
任务 ID,与您提交任务时返回的 taskId 一致
data.data
array
required
生成的音乐数组。文本回调或失败时为空。
data.data[].id
string
音乐唯一标识
data.data[].audio_url
string
音频文件 URL,用于下载
data.data[].stream_audio_url
string
流式音频 URL,用于实时播放
data.data[].image_url
string
封面图片 URL
data.data[].prompt
string
使用的生成提示词/歌词
data.data[].model_name
string
使用的模型名称(如 “chirp-v3-5”)
data.data[].title
string
音乐标题
data.data[].tags
string
音乐标签/风格
data.data[].createTime
string
创建时间戳
data.data[].duration
number
音频时长(秒)

回调接收示例

以下是用流行编程语言接收回调的示例代码:
const express = require('express');
const fs = require('fs');
const https = require('https');
const app = express();

app.use(express.json());

app.post('/suno-extend-callback', (req, res) => {
  const { code, msg, data } = req.body;
  
  console.log('收到 Suno 音乐扩展回调:', {
    taskId: data.task_id,
    callbackType: data.callbackType,
    status: code,
    message: msg
  });
  
  if (code === 200) {
    // 任务进展或成功完成
    const { callbackType, task_id, data: tracks } = data;
    
    console.log(`回调类型: ${callbackType}`);
    console.log(`音乐数量: ${tracks.length}`);
    
    switch (callbackType) {
      case 'text':
        console.log('文本生成完成,等待音乐扩展...');
        break;
        
      case 'first':
        console.log('第一首扩展完成,正在处理剩余音乐...');
        downloadTracks(tracks, task_id);
        break;
        
      case 'complete':
        console.log('全部音乐扩展完成!');
        downloadTracks(tracks, task_id);
        break;
    }
    
  } else {
    // 任务失败
    console.log('Suno 音乐扩展失败:', msg);
    
    // 处理特定错误类型
    if (code === 400) {
      console.log('验证错误 - 检查版权内容');
    } else if (code === 408) {
      console.log('速率限制 - 请等待后重试');
    } else if (code === 413) {
      console.log('内容冲突 - 音频与现有作品匹配');
    } else if (code === 501) {
      console.log('扩展失败 - 可能需要调整参数');
    } else if (code === 531) {
      console.log('服务器错误已退还积分 - 可安全重试');
    }
  }
  
  // 返回 200 状态码确认收到回调
  res.status(200).json({ status: 'received' });
});

// 下载音乐函数
function downloadTracks(tracks, taskId) {
  tracks.forEach((track, index) => {
    const { id, audio_url, image_url, title, duration } = track;
    
    console.log(`音乐 ${index + 1}: ${title} (${duration}秒)`);
    
    // 下载音频文件
    if (audio_url) {
      downloadFile(audio_url, `suno_extend_${taskId}_${id}.mp3`)
        .then(() => console.log(`音频下载成功: ${id}`))
        .catch(err => console.error(`音频下载失败 ${id}:`, err));
    }
    
    // 下载封面图片
    if (image_url) {
      downloadFile(image_url, `suno_extend_cover_${taskId}_${id}.jpeg`)
        .then(() => console.log(`封面下载成功: ${id}`))
        .catch(err => console.error(`封面下载失败 ${id}:`, err));
    }
  });
}

// 辅助函数:下载文件
function downloadFile(url, filename) {
  return new Promise((resolve, reject) => {
    const file = fs.createWriteStream(filename);
    
    https.get(url, (response) => {
      if (response.statusCode === 200) {
        response.pipe(file);
        file.on('finish', () => {
          file.close();
          resolve();
        });
      } else {
        reject(new Error(`HTTP ${response.statusCode}`));
      }
    }).on('error', reject);
  });
}

app.listen(3000, () => {
  console.log('回调服务器运行在端口 3000');
});

最佳实践

回调 URL 配置建议

  1. 使用 HTTPS: 确保回调 URL 使用 HTTPS 协议,保证数据传输安全
  2. 验证来源: 在回调处理中验证请求来源的合法性
  3. 幂等处理: 同一个 task_id 可能收到多次回调,确保处理逻辑是幂等的
  4. 快速响应: 回调处理应尽快返回 200 状态码,避免超时
  5. 异步处理: 复杂的业务逻辑应异步处理,避免阻塞回调响应
  6. 处理多次回调: 准备接收同一任务的 text、first、complete 回调
  7. 扩展管理: 妥善管理扩展后的音频文件和元数据

重要提醒

  • 回调 URL 必须是公网可访问的地址
  • 服务器必须在 15 秒内响应,否则会被认为是超时
  • 连续 3 次重试失败后,系统将停止发送回调
  • 您可能收到同一任务的多次回调(text → first → complete)
  • 请确保回调处理逻辑的稳定性,避免因异常导致回调失败
  • 适当处理版权和冲突错误(代码 400, 413)
  • 某些服务器错误会自动退还积分(代码 531)
  • 扩展后的音频时长通常会比原音频更长

故障排查

如果没有收到回调通知,请检查以下几点:

扩展特定注意事项

音乐扩展特性

音乐扩展功能会基于现有音频继续生成,有以下特点:
  1. 时长增加: 扩展后的音频时长会比原音频更长
  2. 风格延续: 系统会尽量保持原音频的风格和节奏
  3. 平滑过渡: 扩展部分会与原音频自然衔接
  4. 质量保持: 扩展后的音频质量应与原音频相当
  5. 内容连贯: 歌词和旋律会保持逻辑连贯性

替代方案

如果无法使用回调机制,您也可以使用轮询方式:

轮询查询结果

使用获取音乐详情接口定期查询任务状态,建议每 30 秒查询一次。