# Suno 获取带时间戳歌词

> 音频生成

根据已生成的 Suno 任务 ID（`taskId`）和音频 ID（`audioId`）获取带时间戳歌词。

`alignedWords[].startS` 和 `alignedWords[].endS` 的单位为秒。

**cURL 示例：**

```bash
curl --request POST 'https://api.modelverse.cn/v1/sunoapi/get-timestamped-lyrics' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "taskId": "<suno-task-id>",
    "audioId": "<suno-audio-id>"
  }'
```

## 请求地址

`POST https://api.modelverse.cn/v1/sunoapi/get-timestamped-lyrics`

## 请求体

## 响应

- **200** — 获取歌词成功。
- **400** — 请求参数无效，例如缺少或传入空的 `taskId`、`audioId`。
- **default** — 上游或服务端错误响应。

## OpenAPI 定义

```json
{
  "openapi": "3.1.0",
  "x-language": "zh-CN",
  "info": {
    "title": "Suno 获取带时间戳歌词接口文档",
    "version": "1.0.0",
    "description": "这是 Suno 获取带时间戳歌词的同步接口文档。\n接口根据 Suno 音乐任务 ID 和音频 ID 返回对齐歌词及波形数据。\n该接口不需要 `model` 字段，不计费且不写入模型用量记录。\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API 端点。"
    }
  ],
  "tags": [
    {
      "name": "Suno",
      "description": "Suno 音频信息查询。"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/sunoapi/get-timestamped-lyrics": {
      "post": {
        "tags": [
          "Suno"
        ],
        "operationId": "getSunoTimestampedLyrics",
        "summary": "Suno 获取带时间戳歌词",
        "description": "根据已生成的 Suno 任务 ID（`taskId`）和音频 ID（`audioId`）获取带时间戳歌词。\n\n`alignedWords[].startS` 和 `alignedWords[].endS` 的单位为秒。\n\n**cURL 示例：**\n\n```bash\ncurl --request POST 'https://api.modelverse.cn/v1/sunoapi/get-timestamped-lyrics' \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n    \"taskId\": \"<suno-task-id>\",\n    \"audioId\": \"<suno-audio-id>\"\n  }'\n```\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SunoTimestampedLyricsRequest"
              },
              "example": {
                "taskId": "<suno-task-id>",
                "audioId": "<suno-audio-id>"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "获取歌词成功。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SunoTimestampedLyricsResponse"
                },
                "example": {
                  "code": 200,
                  "msg": "success",
                  "data": {
                    "alignedWords": [
                      {
                        "word": "[Verse]\\nWaggin'",
                        "success": true,
                        "startS": 1.36,
                        "endS": 1.79,
                        "palign": 0
                      }
                    ],
                    "waveformData": [
                      0,
                      1,
                      0.5,
                      0.75
                    ],
                    "hootCer": 0.3803191489361702,
                    "isStreamed": false
                  }
                }
              }
            }
          },
          "400": {
            "description": "请求参数无效，例如缺少或传入空的 `taskId`、`audioId`。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SunoTimestampedLyricsErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "上游或服务端错误响应。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SunoTimestampedLyricsErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "ModelVerse API Key。"
      }
    },
    "schemas": {
      "SunoTimestampedLyricsRequest": {
        "type": "object",
        "description": "仅需传入以下两个字段；服务端对额外字段会忽略，不作为接口参数使用。",
        "required": [
          "taskId",
          "audioId"
        ],
        "properties": {
          "taskId": {
            "type": "string",
            "minLength": 1,
            "description": "已成功生成的 Suno 音乐任务 ID。",
            "example": "234dde9c8914e77e4d4fae0a1742a644"
          },
          "audioId": {
            "type": "string",
            "minLength": 1,
            "description": "Suno 任务中对应音轨的音频 ID。",
            "example": "cd508659-ecd2-402b-ac8d-54bbb1c4805e"
          }
        }
      },
      "SunoTimestampedLyricsResponse": {
        "type": "object",
        "description": "成功响应中的字段与 Suno 返回结构一致。",
        "properties": {
          "code": {
            "type": "integer",
            "description": "响应码。"
          },
          "msg": {
            "type": "string",
            "description": "响应消息。"
          },
          "data": {
            "$ref": "#/components/schemas/SunoTimestampedLyricsData"
          }
        }
      },
      "SunoTimestampedLyricsData": {
        "type": "object",
        "properties": {
          "alignedWords": {
            "type": "array",
            "description": "对齐的歌词单词列表。",
            "items": {
              "$ref": "#/components/schemas/SunoAlignedWord"
            }
          },
          "waveformData": {
            "type": "array",
            "description": "音频波形数据。",
            "items": {
              "type": "number"
            }
          },
          "hootCer": {
            "type": "number",
            "description": "歌词对齐准确度评分。"
          },
          "isStreamed": {
            "type": "boolean",
            "description": "是否为流式音频。"
          }
        }
      },
      "SunoAlignedWord": {
        "type": "object",
        "properties": {
          "word": {
            "type": "string",
            "description": "歌词单词。"
          },
          "success": {
            "type": "boolean",
            "description": "该歌词片段是否成功对齐。"
          },
          "startS": {
            "type": "number",
            "description": "歌词片段开始时间，单位为秒。"
          },
          "endS": {
            "type": "number",
            "description": "歌词片段结束时间，单位为秒。"
          },
          "palign": {
            "type": "integer",
            "description": "对齐参数。"
          }
        }
      },
      "SunoTimestampedLyricsErrorResponse": {
        "type": "object",
        "description": "返回的错误对象，具体字段以实际响应为准。",
        "properties": {
          "code": {
            "type": "integer",
            "description": "错误码。"
          },
          "msg": {
            "type": "string",
            "description": "错误信息。"
          }
        }
      }
    }
  }
}
```