# 查询歌词生成任务状态

> 音频生成

查询歌词生成任务的当前状态和结果。

**cURL 示例：**

```bash
curl --request GET \
  --url 'https://api.modelverse.cn/v1/tasks/status?task_id=YOUR_TASK_ID' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

## 请求地址

`GET https://api.modelverse.cn/v1/tasks/status`

## 请求参数

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| task_id | query | string | Yes | 提交任务返回的 task_id |

## 响应

- **200** — 查询成功
- **default** — 错误响应

## OpenAPI 定义

```json
{
  "openapi": "3.1.0",
  "x-language": "zh-CN",
  "info": {
    "title": "Suno 生成歌词接口文档",
    "version": "1.0.0",
    "description": "使用 Suno AI 生成歌词内容，不生成音频轨道。一次请求返回多个歌词变体供选择。\n提交接口：`POST /v1/tasks/submit`\n查询接口：`GET /v1/tasks/status`\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API 端点"
    }
  ],
  "tags": [
    {
      "name": "Suno 生成歌词",
      "description": "Suno 歌词生成操作"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/tasks/submit": {
      "post": {
        "tags": [
          "Suno 生成歌词"
        ],
        "operationId": "submitSunoGenerateLyricsTask",
        "summary": "提交歌词生成任务",
        "description": "使用 Suno AI 生成歌词内容，不生成音频轨道。一次请求返回多个歌词变体供选择。\n\n**cURL 示例：**\n\n```bash\ncurl --request POST \\\n  --url 'https://api.modelverse.cn/v1/tasks/submit' \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n    \"model\": \"suno-generate-lyrics\",\n    \"input\": {\n      \"prompt\": \"一首关于青春的歌\"\n    }\n  }'\n```\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubmitSunoGenerateLyricsTaskRequest"
              },
              "examples": {
                "basic": {
                  "summary": "基础请求",
                  "value": {
                    "model": "suno-generate-lyrics",
                    "input": {
                      "prompt": "一首关于青春的歌"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "任务提交成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubmitSunoGenerateLyricsTaskResponse"
                },
                "examples": {
                  "success": {
                    "summary": "成功响应",
                    "value": {
                      "output": {
                        "task_id": "5c79****be8e"
                      },
                      "request_id": "request_id"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "错误响应",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tasks/status": {
      "get": {
        "tags": [
          "Suno 生成歌词"
        ],
        "operationId": "getSunoGenerateLyricsTaskStatus",
        "summary": "查询歌词生成任务状态",
        "description": "查询歌词生成任务的当前状态和结果。\n\n**cURL 示例：**\n\n```bash\ncurl --request GET \\\n  --url 'https://api.modelverse.cn/v1/tasks/status?task_id=YOUR_TASK_ID' \\\n  --header 'Authorization: Bearer YOUR_API_KEY'\n```\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "提交任务返回的 task_id",
            "example": "5c79****be8e"
          }
        ],
        "responses": {
          "200": {
            "description": "查询成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetSunoGenerateLyricsTaskStatusResponse"
                },
                "examples": {
                  "pending": {
                    "summary": "处理中",
                    "value": {
                      "output": {
                        "task_id": "5c79****be8e",
                        "task_status": "Pending",
                        "submit_time": 1786410000
                      },
                      "request_id": "request_id"
                    }
                  },
                  "success": {
                    "summary": "成功",
                    "value": {
                      "output": {
                        "task_id": "5c79****be8e",
                        "task_status": "Success",
                        "submit_time": 1786410000,
                        "finish_time": 1786410100,
                        "data": [
                          {
                            "text": "[Verse]\n青春的我们\n奔跑在阳光下",
                            "title": "青春之歌",
                            "status": "complete"
                          },
                          {
                            "text": "[Verse]\n风在呼唤我名字\n梦想在前方",
                            "title": "青春之歌",
                            "status": "complete"
                          }
                        ]
                      },
                      "usage": {
                        "request_count": 1
                      },
                      "request_id": "request_id"
                    }
                  },
                  "failure": {
                    "summary": "失败",
                    "value": {
                      "output": {
                        "task_id": "5c79****be8e",
                        "task_status": "Failure",
                        "submit_time": 1786410000,
                        "finish_time": 1786410010,
                        "error_message": "Content contains sensitive words"
                      },
                      "request_id": "request_id"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "错误响应",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "ModelVerse API 密钥，通过 `Authorization: Bearer <API_KEY>` 请求头传递\n"
      }
    },
    "schemas": {
      "SubmitSunoGenerateLyricsTaskRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model",
          "input"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "固定值 `suno-generate-lyrics`",
            "example": "suno-generate-lyrics"
          },
          "input": {
            "type": "object",
            "description": "歌词生成输入参数",
            "required": [
              "prompt"
            ],
            "properties": {
              "prompt": {
                "type": "string",
                "description": "歌词描述，英文字符最多200字符，中文字符或UTF-8字符需少于200字符",
                "example": "一首关于青春的歌",
                "maxLength": 200
              }
            }
          }
        }
      },
      "SubmitSunoGenerateLyricsTaskResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "output",
          "request_id"
        ],
        "properties": {
          "output": {
            "type": "object",
            "required": [
              "task_id"
            ],
            "properties": {
              "task_id": {
                "type": "string",
                "description": "任务ID，用于后续查询",
                "example": "5c79****be8e"
              }
            }
          },
          "request_id": {
            "type": "string",
            "description": "请求追踪ID",
            "example": "request_id"
          }
        }
      },
      "GetSunoGenerateLyricsTaskStatusResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "output",
          "request_id"
        ],
        "properties": {
          "output": {
            "type": "object",
            "required": [
              "task_id",
              "task_status",
              "submit_time"
            ],
            "properties": {
              "task_id": {
                "type": "string",
                "description": "任务ID",
                "example": "5c79****be8e"
              },
              "task_status": {
                "type": "string",
                "description": "任务状态，可选值：Pending / Success / Failure",
                "enum": [
                  "Pending",
                  "Success",
                  "Failure"
                ],
                "example": "Success"
              },
              "submit_time": {
                "type": "integer",
                "format": "int64",
                "description": "提交时间戳",
                "example": 1786410000
              },
              "finish_time": {
                "type": "integer",
                "format": "int64",
                "description": "完成时间戳（终态返回）",
                "example": 1786410100
              },
              "data": {
                "type": "array",
                "description": "歌词变体数组（成功时返回）",
                "items": {
                  "$ref": "#/components/schemas/LyricsVariant"
                }
              },
              "error_message": {
                "type": "string",
                "description": "错误信息（失败时返回）",
                "example": "Content contains sensitive words"
              }
            }
          },
          "usage": {
            "type": "object",
            "description": "用量统计",
            "properties": {
              "request_count": {
                "type": "integer",
                "description": "请求次数",
                "example": 1
              }
            }
          },
          "request_id": {
            "type": "string",
            "description": "请求追踪ID",
            "example": "request_id"
          }
        }
      },
      "LyricsVariant": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "text",
          "title",
          "status"
        ],
        "properties": {
          "text": {
            "type": "string",
            "description": "歌词内容，包含结构标记 [Verse] / [Chorus] 等",
            "example": "[Verse]\n青春的我们\n奔跑在阳光下"
          },
          "title": {
            "type": "string",
            "description": "歌曲标题",
            "example": "青春之歌"
          },
          "status": {
            "type": "string",
            "description": "歌词状态，可选值：complete / failed",
            "enum": [
              "complete",
              "failed"
            ],
            "example": "complete"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "code",
          "msg"
        ],
        "properties": {
          "code": {
            "type": "integer",
            "description": "错误状态码",
            "example": 400
          },
          "msg": {
            "type": "string",
            "description": "错误信息",
            "example": "Invalid request"
          }
        }
      }
    }
  }
}
```