# suno

Music Generation Model

## Submit Task (Asynchronous)

### Endpoint

`https://api-us-ca.umodelverse.ai/v1/tasks/submit`

### Input

| Parameter                       | Type   | Required | Description |
| :------------------------------ | :----- | :------- | :---------- |
| model                           | string | Yes      | Model name. Corresponds to Suno model versions:<br/>`suno-v4`<br/>`suno-v4.5`<br/>`suno-v4.5+`<br/>`suno-v4.5-all`<br/>`suno-v5`<br/>`suno-v5.5` |
| input.prompt                    | string | No       | Lyrics (for custom mode only) |
| input.gpt_description_prompt    | string | No       | Inspiration prompt (for inspiration mode only) |
| parameters.tags                 | string | No       | Style tags (for custom mode only) |
| parameters.title                | string | No       | Title (for custom mode only) |
| parameters.make_instrumental    | bool   | No       | Whether to generate instrumental-only music. `true` = instrumental |

### Request Examples

⚠️ If you are using Windows, it is recommended to use Postman or other API tools.

<!-- tabs:start -->

#### ** Inspiration Mode **
```bash
curl --location --globoff 'https://api-us-ca.umodelverse.ai/v1/tasks/submit' \
--header 'Authorization: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
        "model": "suno/chirp-bluejay",
        "input": {
            "gpt_description_prompt": "A song about homesickness"
        }
    }'
```

#### ** Instrumental Inspiration Mode **

```bash
curl --location --globoff 'https://api-us-ca.umodelverse.ai/v1/tasks/submit' \
--header 'Authorization: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
        "model": "suno/chirp-bluejay",
        "input": {
            "gpt_description_prompt": "A song about homesickness"
        },
        "parameters": {
            "make_instrumental": true
        }
    }'
```

#### ** Custom Lyrics & Title **

```bash
curl --location --globoff 'https://api-us-ca.umodelverse.ai/v1/tasks/submit' \
--header 'Authorization: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "model": "suno/chirp-bluejay",
  "input": {
    "prompt": "[Verse]\nBusy days keep repeating\nEndless piles of files\nDreams hidden deep in a drawer\nThe coffee cup has gone cold\n\n[Verse 2]\nClocking in at eight each morning\nTired eyes without spirit\nIdle chats feel meaningless\nJust waiting for time to pass\n\n[Chorus]\nWork, work, the boss keeps calling\nFinish, finish to stay safe\nOvertime, overtime just to earn a bit\nDreams, dreams, when will they come true\n\n[Verse 3]\nLunch with a simple meal\nSunlight shines outside the window\nLife feels far from dreams\nOnly desks and chairs ahead\n\n[Bridge]\nThe boss’s footsteps like thunder\nHeartbeat racing with the rhythm\nA pile of files on the desk\nComplaints slowly fade away\n\n[Chorus]\nWork, work, the boss keeps calling\nFinish, finish to stay safe\nOvertime, overtime just to earn a bit\nDreams, dreams, when will they come true"
  },
  "parameters": {
    "tags": "pop, ballad",
    "title": "Returning Home"
  }
}'
```

#### ** Custom Instrumental **

```bash
curl --location --globoff 'https://api-us-ca.umodelverse.ai/v1/tasks/submit' \
--header 'Authorization: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "model": "suno/chirp-bluejay",
  "input": {
    "prompt": ""
  },
  "parameters": {
    "tags": "pop, ballad",
    "title": "Returning Home"
  }
}'
```

<!-- tabs:end -->

### Output

| Parameter      | Type   | Description                         |
| :------------- | :----- | :---------------------------------- |
| output.task_id | string | Unique identifier of the async task |
| request_id     | string | Unique identifier of the request    |

### Response Example

```json
{
  "output": {
    "task_id": "task_id"
  },
  "request_id": "request_id"
}
```

## Query Task Status

### Endpoint

`https://api-us-ca.umodelverse.ai/v1/tasks/status?task_id=<task_id>`

### Request Example

```shell
curl --location 'https://api-us-ca.umodelverse.ai/v1/tasks/status?task_id=<task_id>' \
--header 'Authorization: <YOUR_API_KEY>'
```

### Output

| Parameter            | Type    | Description                                             |
| :------------------- | :------ | :------------------------------------------------------ |
| output.task_id       | string  | Unique identifier of the async task                     |
| output.task_status   | string  | Task status: `Pending`, `Running`, `Success`, `Failure` |
| output.urls          | array   | List of result URLs (audio files)                       |
| output.submit_time   | integer | Task submission timestamp                               |
| output.finish_time   | integer | Task completion timestamp                               |
| output.error_message | string  | Error message returned when failed                      |
| request_id           | string  | Unique identifier of the request                        |

### Response Example (Success)

```json
{
  "output": {
    "task_id": "task_id",
    "task_status": "Success",
    "urls": ["https://xxxxx/xxxx.mp3"],
    "submit_time": 1756959000,
    "finish_time": 1756959050
  },
  "usage": {
  },
  "request_id": ""
}
```

### Response Example (Failure)

```json
{
  "output": {
    "task_id": "task_id",
    "task_status": "Failure",
    "submit_time": 1756959000,
    "finish_time": 1756959019,
    "error_message": "error_message"
  },
  "request_id": ""
}
```