接口与鉴权

GET https://top.qingyuntop.ai/v1/responses/{response_id}

请求头为 Authorization: Bearer YOUR_API_KEY，无需请求体。将 RESPONSE_ID 替换为创建响应或 response.created 事件里的 id。

查询示例

cURL 查询一次；Python 和 Node.js 每 10 秒轮询，最多等待 30 分钟。示例打印文本，并输出用于下载的 task_id。

curl --fail-with-body "https://top.qingyuntop.ai/v1/responses/RESPONSE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

状态和输出

queued、in_progress 表示未结束，继续 GET；completed 表示成功；failed 表示失败。观察时限导致的 incomplete 或断线不能直接等同于任务失败，应继续查询持久化状态。

响应没有 SunoAPI 的 code/data 外层。歌词任务在 message.content 的 output_text 中返回标题和歌词；音乐任务返回文本和包含 <audio controls src="..."> 的 output_text。它不是音频二进制，也没有保证提供一个 output_audio 字段。

插件只把上游结果的 text 字段拼入歌词文本；上游若把歌曲歌词放在 metadata.prompt，Responses 可能只显示 Music generation completed. 和播放器。需要原始歌曲字段时，可用 metadata.task_id 查询 SunoAPI 任务结果。

程序需要 MP3 时，读取 metadata.task_id 后使用下载音乐与封面，不必解析 audio HTML。应用展示文本时不要将任意模型输出直接赋给 innerHTML；可从产物列表的 content_url 构建自己的播放器。

典型错误

错误或现象处理
input is required音乐需非空描述或 metadata.prompt；歌词需最终非空 prompt
input must be a string or array不要把 input 写成单个对象
metadata must be an object使用 JSON 对象，不能是字符串、数组或 null
model must be suno_music or suno_lyrics检查 model；歌曲版本应放 metadata.mv
JSON body required / 415使用 application/json，不能上传 multipart 音频
401/403检查青云 API Key、模型权限与账户状态
404使用创建响应的 id，确认任务属于当前账号；不要使用歌曲 id
audio artifact is unavailable / artifact_url_error音频产物或下载地址生成失败，保留 task_id 排查；不要盲目重复创建
429 或暂时性 5xx降低频率，延迟重试查询；提交是否已成功应先核对

本插件没有保证通用 tools、结构化输出、对话续接、文件输入或取消操作的兼容性。background 也不是回调地址；客户端仍需查询或消费 SSE。