# 生成歌词
> Suno 的歌词生成接口，异步任务
> 可选两种歌词模型：classic 与 remi
> 结果可直接回填给「生成音乐」
`POST /v1/music/generations/lyrics`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 获取 API Key：[访问控制台](https://api.oairoute.com/keys) 创建。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_OAIRoute_KEY ```
## 请求参数
- `model` (string / 可选) — 音频模型，默认 `suno`。当前只有这一个取值。
- `prompt` (string / 必填) — 描述想生成什么样的歌词。去掉首尾空白后不能为空。
- `lyrics_model` (string / 可选) — 歌词模型，取值 `classic` 或 `remi`。不传则使用服务端默认设置。
> **Note:** 
> 本端点没有版本维度。传 `version` 会被丢弃，也不影响计费。
## 提交响应
- `code` (integer) — 响应状态码，成功为 200。
- `data[].status` (string) — 提交成功时固定为 `submitted`。
- `data[].task_id` (string) — 任务唯一标识，用于轮询 `GET /v1/music/tasks/{task_id}`。
## 查询结果
- `result.lyrics` (array) — 歌词数组，首选的读取结构。
- `result.lyrics[].text` (string) — 歌词正文。
- `result.lyrics[].title` (string) — 歌词标题。
- `result.lyrics[].tags` (string) — 歌词标签。
- `result.text` (string) — 兼容字段。`result.lyrics` 缺失时读这里。
> **Note:** 
> 返回结构有历史版本差异。稳妥的读法是：先看 `result.lyrics` 是否为数组，不是再看 `result.text`，都没有才判定为失败。直接把 `result.lyrics` 当字符串用，在老数据上会拿到空值。
## 两个歌词模型的差别
| 模型 | 倾向 |
|---|---|
| `classic` | 结构工整，主歌副歌分段清晰 |
| `remi` | 用词更新颖，适合流行与说唱 |
不确定时先用 `classic`，它的产出更容易直接用于演唱。
## 错误
| HTTP | type | 说明 |
|---|---|---|
| 400 | invalid_request_error | 请求参数无效，如 prompt 为空 |
| 401 | authentication_error | 身份验证失败，需检查 API 密钥 |
| 402 | payment_required | 账户余额不足 |
| 429 | rate_limit_error | 请求过于频繁 |
更多状态码与重试建议见[错误码与限流](../../../support/errors.html)，常见报错的排查步骤见[常见问题](../../../support/faq.html)。
## 使用示例
提交一个任务并拿到 `task_id`：
> **Note:** 
> 提交成功只表示任务已受理。真正的产物要拿返回的 `task_id` 去任务查询接口轮询，`status` 变成 `completed` 之后才有结果。
**生成歌词{Generate lyrics}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/music/generations/lyrics' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "suno",
    "prompt": "一首关于告别与重新出发的民谣",
    "lyrics_model": "classic"
  }'
```
**生成歌词{Generate lyrics}::Python**
```
import requests
res = requests.post(
    "https://api.oairoute.com/v1/music/generations/lyrics",
    headers={
        "Authorization": "Bearer YOUR_OAIRoute_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "suno",
        "prompt": "一首关于告别与重新出发的民谣",
        "lyrics_model": "classic",
    },
)
print(res.json()["data"][0]["task_id"])
```
**生成歌词{Generate lyrics}::JavaScript**
```
const url = "https://api.oairoute.com/v1/music/generations/lyrics";
const options = {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "suno",
    "prompt": "一首关于告别与重新出发的民谣",
    "lyrics_model": "classic"
  }),
};
fetch(url, options)
  .then((res) => res.json())
  .then((json) => console.log(json))
  .catch((err) => console.error(err));
```
**200 生成歌词{Generate lyrics}**
```
{
  "code": 200,
  "data": [
    { "status": "submitted", "task_id": "task_01K8C00M0HP1GJWBJYZMKX1XS1" }
  ]
}
```