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

# Suno Music Generation

> Use the `/suno/*` routes to submit asynchronous music tasks, and query lyrics or audio generation results.

# Suno Music Generation

The Suno routes use a separate asynchronous task protocol; both submission and querying do not go through `/v1/audio/*`.

* One entry point covers automatic composition, lyric generation, and custom-lyric music generation.
* Asynchronous processing mode; a task ID is returned after submission.
* Supports single-task queries and batch queries.
* Query results are wrapped with `code`, `message`, and `data`.

## Route List

| Method | Path                    | Description         |
| ------ | ----------------------- | ------------------- |
| `POST` | `/suno/submit/{action}` | Submit a music task |
| `GET`  | `/suno/fetch/{id}`      | Query a single task |
| `POST` | `/suno/fetch`           | Batch query         |

## Authentication

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Path Parameters

<ParamField body="action" type="string" required>
  The operation type. Common values are `music`, `lyrics`, and `custom`.
</ParamField>

## Body

<ParamField body="prompt" type="string" required>
  In `music` mode, this indicates the music description; in `custom` mode, it is usually the lyrics content directly.
</ParamField>

<ParamField body="tags" type="string">
  Style tags, separated by commas.
</ParamField>

<ParamField body="title" type="string">
  Song title.
</ParamField>

<ParamField body="mv" type="string">
  Model version, such as `chirp-v3-5` or `chirp-v4`.
</ParamField>

<ParamField body="continue_clip_id" type="string">
  The clip ID used when continuing an existing music segment.
</ParamField>

## Request Example

```bash theme={null}
curl -X POST https://octopusx.ai/suno/submit/music \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A catchy pop song about a summer night by the sea",
    "tags": "pop, summer, beach",
    "title": "Summer Night by the Sea",
    "mv": "chirp-v3-5"
  }'
```

## Response Example

<ResponseExample>
  ```json 200 - Submission successful theme={null}
  {
    "code": "success",
    "message": "",
    "data": "task-suno-abc123"
  }
  ```

  ```json 200 - Query successful theme={null}
  {
    "code": "success",
    "message": "",
    "data": {
      "task_id": "task-suno-abc123",
      "status": "SUCCESS",
      "progress": "100%",
      "result_url": "https://.../audio/abc123.mp3"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "code": "task_not_exist",
    "message": "task_not_exist",
    "data": null
  }
  ```
</ResponseExample>

## Use Cases

### Automatic Composition

```bash theme={null}
curl -X POST https://octopusx.ai/suno/submit/music \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "An electronic pop track suitable for the opening of a product launch event",
    "tags": "electronic, upbeat"
  }'
```

### Batch Query

```bash theme={null}
curl -X POST https://octopusx.ai/suno/fetch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["task-suno-abc123", "task-suno-def456"]
  }'
```

## Related APIs

* [OpenAI Audio Compatible API](./audio)
* [Task Management Overview](../tasks/overview)