# Get Lyrics Generation Task Status

> Audio Generation

Query the current status and results of the lyrics generation task.

**cURL Example:**

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

## Endpoint

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

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| task_id | query | string | Yes | Task ID returned from the submit task |

## Responses

- **200** — Query successful
- **default** — Error response

## OpenAPI Definition

```json
{
  "openapi": "3.1.0",
  "x-language": "en-US",
  "info": {
    "title": "Suno Generate Lyrics API",
    "version": "1.0.0",
    "description": "Generate lyrics content using Suno AI without generating audio tracks. Returns multiple lyrics variants for selection.\nSubmit endpoint: `POST /v1/tasks/submit`\nQuery endpoint: `GET /v1/tasks/status`\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API endpoint"
    }
  ],
  "tags": [
    {
      "name": "Suno Generate Lyrics",
      "description": "Suno lyrics generation operations"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/tasks/submit": {
      "post": {
        "tags": [
          "Suno Generate Lyrics"
        ],
        "operationId": "submitSunoGenerateLyricsTask",
        "summary": "Submit Lyrics Generation Task",
        "description": "Generate lyrics content using Suno AI without generating audio tracks. Returns multiple lyrics variants for selection.\n\n**cURL Example:**\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\": \"A song about youth\"\n    }\n  }'\n```\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubmitSunoGenerateLyricsTaskRequest"
              },
              "examples": {
                "basic": {
                  "summary": "Basic request",
                  "value": {
                    "model": "suno-generate-lyrics",
                    "input": {
                      "prompt": "A song about youth"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task submitted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubmitSunoGenerateLyricsTaskResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Success response",
                    "value": {
                      "output": {
                        "task_id": "5c79****be8e"
                      },
                      "request_id": "request_id"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tasks/status": {
      "get": {
        "tags": [
          "Suno Generate Lyrics"
        ],
        "operationId": "getSunoGenerateLyricsTaskStatus",
        "summary": "Get Lyrics Generation Task Status",
        "description": "Query the current status and results of the lyrics generation task.\n\n**cURL Example:**\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 returned from the submit task",
            "example": "5c79****be8e"
          }
        ],
        "responses": {
          "200": {
            "description": "Query successful",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetSunoGenerateLyricsTaskStatusResponse"
                },
                "examples": {
                  "pending": {
                    "summary": "Pending",
                    "value": {
                      "output": {
                        "task_id": "5c79****be8e",
                        "task_status": "Pending",
                        "submit_time": 1786410000
                      },
                      "request_id": "request_id"
                    }
                  },
                  "success": {
                    "summary": "Success",
                    "value": {
                      "output": {
                        "task_id": "5c79****be8e",
                        "task_status": "Success",
                        "submit_time": 1786410000,
                        "finish_time": 1786410100,
                        "data": [
                          {
                            "text": "[Verse]\nWe are young\nRunning in the sun",
                            "title": "Song of Youth",
                            "status": "complete"
                          },
                          {
                            "text": "[Verse]\nThe wind calls my name\nDreams ahead",
                            "title": "Song of Youth",
                            "status": "complete"
                          }
                        ]
                      },
                      "usage": {
                        "request_count": 1
                      },
                      "request_id": "request_id"
                    }
                  },
                  "failure": {
                    "summary": "Failure",
                    "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": "Error response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "ModelVerse API key sent in the `Authorization: Bearer <API_KEY>` header\n"
      }
    },
    "schemas": {
      "SubmitSunoGenerateLyricsTaskRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model",
          "input"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "Fixed value `suno-generate-lyrics`",
            "example": "suno-generate-lyrics"
          },
          "input": {
            "type": "object",
            "description": "Lyrics generation input parameters",
            "required": [
              "prompt"
            ],
            "properties": {
              "prompt": {
                "type": "string",
                "description": "Lyrics description, maximum 200 English characters. For Chinese or UTF-8 characters, must be less than 200 characters",
                "example": "A song about youth",
                "maxLength": 200
              }
            }
          }
        }
      },
      "SubmitSunoGenerateLyricsTaskResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "output",
          "request_id"
        ],
        "properties": {
          "output": {
            "type": "object",
            "required": [
              "task_id"
            ],
            "properties": {
              "task_id": {
                "type": "string",
                "description": "Task ID for subsequent queries",
                "example": "5c79****be8e"
              }
            }
          },
          "request_id": {
            "type": "string",
            "description": "Request tracking 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": "Task ID",
                "example": "5c79****be8e"
              },
              "task_status": {
                "type": "string",
                "description": "Task status, options: Pending / Success / Failure",
                "enum": [
                  "Pending",
                  "Success",
                  "Failure"
                ],
                "example": "Success"
              },
              "submit_time": {
                "type": "integer",
                "format": "int64",
                "description": "Submission timestamp",
                "example": 1786410000
              },
              "finish_time": {
                "type": "integer",
                "format": "int64",
                "description": "Completion timestamp (returned in final state)",
                "example": 1786410100
              },
              "data": {
                "type": "array",
                "description": "Array of lyrics variants (returned on success)",
                "items": {
                  "$ref": "#/components/schemas/LyricsVariant"
                }
              },
              "error_message": {
                "type": "string",
                "description": "Error message (returned on failure)",
                "example": "Content contains sensitive words"
              }
            }
          },
          "usage": {
            "type": "object",
            "description": "Usage statistics",
            "properties": {
              "request_count": {
                "type": "integer",
                "description": "Request count",
                "example": 1
              }
            }
          },
          "request_id": {
            "type": "string",
            "description": "Request tracking ID",
            "example": "request_id"
          }
        }
      },
      "LyricsVariant": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "text",
          "title",
          "status"
        ],
        "properties": {
          "text": {
            "type": "string",
            "description": "Lyrics content, includes structure markers like [Verse] / [Chorus]",
            "example": "[Verse]\nWe are young\nRunning in the sun"
          },
          "title": {
            "type": "string",
            "description": "Song title",
            "example": "Song of Youth"
          },
          "status": {
            "type": "string",
            "description": "Lyrics status, options: complete / failed",
            "enum": [
              "complete",
              "failed"
            ],
            "example": "complete"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "code",
          "msg"
        ],
        "properties": {
          "code": {
            "type": "integer",
            "description": "Error status code",
            "example": 400
          },
          "msg": {
            "type": "string",
            "description": "Error message",
            "example": "Invalid request"
          }
        }
      }
    }
  }
}
```