入口与鉴权

基础地址为 https://top.qingyuntop.ai，使用 Authorization: Bearer YOUR_API_KEY。

步骤请求
列出产物GET /v1/tasks/{task_id}/artifacts
下载产物GET /v1/tasks/{task_id}/artifacts/{artifact_key}/content

SunoAPI 创建返回的 data 就是 task_id；Responses 结果使用 metadata.task_id。先确认任务成功，再列产物。插件只声明音频和封面产物，未开放 WAV 转换或视频下载协议。

产物结构

产物列表没有 SunoAPI 的 code/data 外层，直接读取 artifacts：

{"task_id":"TASK_ID","artifacts":[{"key":"audio-EXAMPLE_KEY","type":"audio","mime_type":"audio/mpeg","content_url":"https://top.qingyuntop.ai/v1/tasks/TASK_ID/artifacts/audio-EXAMPLE_KEY/content?access=EXAMPLE"}]}

示意中的 key 和 access 都是占位符。必须使用真实返回的 key，不要根据歌曲 id 自行计算。type: audio 是音乐，type: image 是封面。插件在 SUCCESS 且歌曲具有 id 和非空素材地址时才列出对应产物。

content_url 是带访问能力的播放链接，可用于播放器，不要将青云 API Key 拼到 URL 中。它应按私有结果链接保存，避免放入公开日志。下面的程序示例使用本站下载路径和请求头鉴权，无需提取 access。

下载示例

cURL 先查看列表，把 ARTIFACT_KEY 替换为一个 type=audio 的 key 后执行第二条；Python 和 Node.js 会下载列表中的全部音频。

curl --fail-with-body "https://top.qingyuntop.ai/v1/tasks/TASK_ID/artifacts" \
  -H "Authorization: Bearer YOUR_API_KEY"
curl --fail-with-body "https://top.qingyuntop.ai/v1/tasks/TASK_ID/artifacts/ARTIFACT_KEY/content" \
  -H "Authorization: Bearer YOUR_API_KEY" -o suno-song.mp3

封面使用同样的下载步骤，选择 type=image 的 key，并根据返回 Content-Type 保存文件扩展名。不要把封面写成 mp3。

空列表和下载错误

未完成任务和歌词任务可能没有产物。409 表示产物尚未就绪；404 可能是任务或 key 错误；上游素材失效、访问失败或本站产物地址配置错误也可能造成下载失败。保留原任务 ID 排查，不要再次生成代替查询。成功产物建议及时保存，不保证永久托管。