> ## Documentation Index
> Fetch the complete documentation index at: https://docs.musicmint.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate Lyrics

> Generate song lyrics using AI from a prompt, topics, or keywords

## Endpoint

```http theme={null}
POST /api/v1/lyrics/generate
```

**Asynchronous.** Returns a `task_id`. Poll [Get Task](/api-reference/tasks/get) for results.

Generates song lyrics based on a text prompt, topic, mood, or keyword. The result is a completed lyrics text (not an audio file). Supports Chinese and English.

## Request body

| Field            | Type    | Required | Description                                                                                |
| ---------------- | ------- | -------- | ------------------------------------------------------------------------------------------ |
| `prompt`         | string  | See note | Free-form description of the song or desired lyrics content. Supports Chinese and English. |
| `topics`         | string  | See note | Topic(s) for the song (e.g. `"love, summer"` or `"爱情, 思念"`).                               |
| `moods`          | string  | No       | Emotional tone (e.g. `"happy, nostalgic"` or `"悲伤, 治愈"`).                                  |
| `style`          | string  | No       | Musical style (e.g. `"country ballad"` or `"流行抒情"`).                                       |
| `keyword`        | string  | See note | Key words or phrases to include in the lyrics.                                             |
| `callback_url`   | string  | No       | Webhook URL for completion notification. See [Webhooks](/api-reference/webhooks).          |
| `retention_days` | integer | No       | Days to retain result. Default `7`.                                                        |

<Note>
  At least one of `prompt`, `topics`, or `keyword` is required.
</Note>

## Response

The task result contains generated lyrics in the music result's `prompt` field.

```json theme={null}
{
  "code": 0,
  "message": "ok",
  "request_id": "req-1710000000000",
  "data": {
    "task_id": "64f3a1b2c8d9e0f1a2b3c4d5",
    "status": "queuing"
  }
}
```

## Examples

**English:**

```bash theme={null}
curl -X POST https://api.example.com/api/v1/lyrics/generate \
  -H "Authorization: Bearer sk-mm-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "topics": "heartbreak, rain, moving on",
    "moods": "melancholic, hopeful",
    "style": "indie folk"
  }'
```

**Chinese:**

```bash theme={null}
curl -X POST https://api.example.com/api/v1/lyrics/generate \
  -H "Authorization: Bearer sk-mm-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "topics": "思念, 离别, 重逢",
    "moods": "感伤, 温暖",
    "style": "流行抒情"
  }'
```