文档 / 音乐系列 / Suno / 辅助功能
辅助功能POSTSunoLYRICSLyricssuno_lyrics
提交歌词生成任务
提交 LYRICS 任务，根据 prompt 生成歌词候选。
Bearer API KeyJSON服务端调用
用途#
提交一个 歌词生成（LYRICS） 任务。该接口调用 Suno 的独立歌词能力，根据提示词生成一段歌词文本，常用于在正式作曲前先打磨歌词。
接口为异步模式：服务在校验通过后立即返回公开 task_id，不会等待任务完成。后续通过 GET /v1/tasks/:id 轮询任务状态与结果。
LYRICS 只关心 prompt 一个字段。
请求字段#
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
prompt | string | 是 | — | 歌词生成提示词，描述主题、情绪或风格。留空将返回 prompt_empty 错误 |
callback_url | string | 否 | — | 任务到达终态时的回调通知地址 |
prompt 为必填项。若请求体中缺少 prompt 或其值为空字符串，接口会返回 400 prompt_empty，任务不会被创建。
callback_url 必须是公网可访问的 HTTPS 地址，长度不超过 2048 字符；禁止使用本机、内网、回环、链路本地地址，也禁止使用解析到这些地址的域名。
任务完成或失败后，服务会向该地址发送 POST JSON。回调接收端须在 10 秒内返回任意 2xx 状态码；超时、网络错误或非 2xx 响应均视为失败。
失败后会分别等待 1 秒、2 秒和 4 秒重试，连同首次请求最多发送 4 次。接收端应使用任务 ID 做幂等处理，避免重复处理。
请求示例#
cURL
curl --request POST \
--url https://api.apimax.ai/v1/music/lyrics \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"prompt": "写一首关于夏夜城市漫步的中文流行歌词，氛围温柔、带一点怀旧"
}'成功响应#
200
{
"code": "success",
"message": "",
"data": "task_01HV8..."
}响应字段#
| 字段 | 类型 | 说明 |
|---|---|---|
code | string | 响应码，成功固定为 success |
message | string | 提示信息，成功时通常为空 |
data | string | 公开任务 ID（40 字符以内），用于后续查询 |
data 返回公开 task_id，所有后续查询均使用该 ID。
错误码#
| HTTP | code | 场景 |
|---|---|---|
| 400 | prompt_empty | 缺少 prompt 或其值为空 |
| 400 | invalid_request | 请求体 JSON 解析失败 |
| 400 | invalid_action | action 不在支持列表内 |
| 503 | no_available_channel | 无可用渠道 |
| 502 | upstream_failed | 任务处理服务请求失败（网络错误等） |
查询任务结果#
提交成功后，使用返回的 task_id 轮询：
- 单个查询：
GET /v1/tasks/:id
status 枚举#
| 值 | 说明 |
|---|---|
queued | 任务已创建，等待处理 |
in_progress | 任务正在处理 |
completed | 任务处理完成，可读取 data |
failed | 任务处理失败，可读取 error |
completed 和 failed 为终态；其余状态请继续轮询。
查询结果中的 data 字段包含歌词数据，可能返回多个歌词候选。
歌词结果字段（data）#
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 歌词记录 ID |
status | string | 歌词生成状态 |
title | string | 歌词标题 |
text | string | 生成的歌词正文 |
下面是一个成功任务的完整查询响应示例（data 为歌词变体数组，可能包含多个候选）：
json
{
"id": "task_UbfL8V8Bdj1nTzNmkUtWdpLnnWuQqnXS",
"model": "suno_lyrics",
"object": "task",
"platform": "suno",
"type": "suno",
"status": "completed",
"progress": 100,
"created_at": 1783071193,
"started_at": 1783071194,
"finished_at": 1783071217,
"data": [
{
"id": "task_UbfL8V8Bdj1nTzNmkUtWdpLnnWuQqnXS",
"status": "complete",
"title": "我家有喜",
"text": "[Verse 1]
晨光落在窗沿
菜香绕过屋檐
...
[Chorus]
我家有喜
喜气满屋里
..."
},
{
"id": "task_UbfL8V8Bdj1nTzNmkUtWdpLnnWuQqnXS",
"status": "complete",
"title": "喜进我家",
"text": "[Verse 1]
门口那双鞋
今天都带笑
...
[Chorus]
我家有喜
喜在心上
..."
}
]
}生成的歌词文本可直接作为后续 MUSIC 任务 的 prompt，进入正式作曲流程。