# 生成歌词
> Flow Music 的歌词生成接口，异步任务
> 输出带 `[Intro]`、`[Verse 1]` 等段落标记的歌词
> 结果可直接回填给「生成音乐」接口
`POST /v1/music/generations/lyricsFlowMusic`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 获取 API Key：[访问控制台](https://api.oairoute.com/keys) 创建。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_OAIRoute_KEY ```
## 请求参数
- `model` (string / 必填) — 固定填 `flowmusic`，大小写不敏感。缺省时返回 `model_required`。
- `prompt` (string / 必填) — 歌词生成提示词，长度不超过 3000 字符。 建议写清歌曲主题、风格与情绪。例如「一首关于坚持的摇滚歌曲」。
## 提交响应
- `code` (integer) — 状态码，成功为 200。
- `data[].status` (string) — 任务状态，初始值为 `submitted`。
- `data[].task_id` (string) — 任务唯一标识，用于查询进度与结果。
## 查询结果
用 `GET /v1/music/tasks/{task_id}` 查询。
- `result.lyrics` (array) — 歌词结果数组。
- `result.lyrics[].title` (string) — 歌词标题。
- `result.lyrics[].lyrics` (string) — 歌词正文，带 `[Intro]`、`[Verse 1]`、`[Chorus]` 等段落标记。
## 完整流程
歌词生成与音乐生成是两个独立任务，串起来用：
1. 调本接口生成歌词，拿 `task_id`
2. 轮询拿到 `result.lyrics[0]` 的 `title` 与 `lyrics`
3. 把这两个值作为「生成音乐」的 `title` 与 `lyrics` 入参
4. 配上 `sound_prompt` 描述风格，一起提交
这样歌词与曲风能同步，不会出现「词很燃、曲子很柔」的错配。
## 错误
| HTTP | error.code | error.type | 说明 |
|---|---|---|---|
| 400 | model_required | invalid_request | model is required |
| 429 | rate_limit_error | rate_limit_error | 当前分组容量饱和，请稍后重试 |
> **Note:** 
> 这段路径拼写是 `lyricsFlowMusic`，不是 `lyrics`。Flow Music 的每个操作各有独立路径，别按 REST 惯例去猜。
更多状态码与重试建议见[错误码与限流](../../../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/lyricsFlowMusic' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "flowmusic",
    "prompt": "一首关于坚持的摇滚歌曲"
  }'
```
**生成歌词{Generate lyrics}::Python**
```
import time, requests
BASE = "https://api.oairoute.com"
HEAD = {"Authorization": "Bearer YOUR_OAIRoute_KEY",
        "Content-Type": "application/json"}
# 1. 提交歌词任务
r = requests.post(f"{BASE}/v1/music/generations/lyricsFlowMusic",
                  headers=HEAD,
                  json={"model": "flowmusic",
                        "prompt": "一首关于坚持的摇滚歌曲"})
task_id = r.json()["data"][0]["task_id"]
# 2. 轮询
while True:
    d = requests.get(f"{BASE}/v1/music/tasks/{task_id}",
                     headers=HEAD).json()["data"]
    if d["status"] == "completed":
        lyric = d["result"]["lyrics"][0]
        break
    if d["status"] == "failed":
        raise RuntimeError(d.get("error"))
    time.sleep(5)
# 3. 回填给音乐生成
requests.post(f"{BASE}/v1/music/generations",
              headers=HEAD,
              json={"model": "flowmusic",
                    "title": lyric["title"],
                    "lyrics": lyric["lyrics"],
                    "sound_prompt": "摇滚，电吉他，鼓点强烈"})
```
**生成歌词{Generate lyrics}::JavaScript**
```
const url = "https://api.oairoute.com/v1/music/generations/lyricsFlowMusic";
const options = {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "flowmusic",
    "prompt": "一首关于坚持的摇滚歌曲"
  }),
};
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_01K8AYYM6R03TGZ3Q2P0TZVNPX" }
  ]
}
```