---
name: sunoma-music
description: Create AI music (generate, cover, sample, mashup, extend) through the SunoMA gateway REST API using a personal API key. Also save/recall reusable styles & lyrics (memory) and send feedback.
---

# SunoMA Music Skill

You can create AI-generated music for the user through the **SunoMA** gateway.
Every request is authenticated with the user's personal API key and is billed 1
credit per generation (each generation returns 2 variations).

## Configuration

- Base URL: `{{BASE_URL}}`
- Auth header on every request: `Authorization: Bearer {{API_KEY}}`
- Content type for POST bodies: `application/json`

> Replace `{{API_KEY}}` with your own key from the SunoMA site → **API Keys**
> (or the **Connect / Install** page). Keys can carry a credit budget; when a
> key's budget is exhausted the API returns HTTP 402 with `code: "key_budget"`.

A song id may be a bare UUID **or** a full Suno link like
`https://suno.com/song/<uuid>` — both are accepted anywhere a clip id is expected.

## Endpoints

### Get list of available model versions
`GET /api/models`
Returns available default models (e.g. v5.5, v3.5) and custom models (e.g. skimi) with their `external_key` values.

### Create a song from a description or lyrics
`POST /api/generate`
```json
{ "mode": "simple", "desc": "a dreamy lofi track for studying", "tags": "lofi, chill", "make_instrumental": false, "mv": "chirp-fenix" }
```
- Use `"mode": "custom"` with `"prompt": "<your lyrics>"` to sing exact lyrics.
- Pass `"mv"` to select the model version (e.g. `"mv": "chirp-custom:..."` for a custom model).

### Create multiple songs in bulk (sequential queue)
`POST /api/generate-bulk`
```json
{
  "songs": [
    { "mode": "simple", "desc": "lofi track", "tags": "lofi", "mv": "chirp-custom:d057bc96-ab0c-48c1-bfc0-43df2bb35684" },
    { "mode": "custom", "prompt": "My custom lyrics...", "style": "acoustic guitar", "mv": "chirp-fenix" }
  ],
  "stagger_ms": 2000
}
```
Submits up to 10 generations sequentially with a delay (`stagger_ms`, default 2000ms) between them.

### Cover — restyle an existing song (keeps melody, optional custom lyrics)
`POST /api/cover`
```json
{ "clip_id": "https://suno.com/song/<uuid>", "style": "acoustic, piano", "lyrics": "[Verse]\nCustom new lyrics...", "make_instrumental": false, "mv": "chirp-goose" }
```
You can pass `lyrics` (or `prompt`) to replace/customize the lyrics of the cover, or `description` for restyling hints.


### Sample — chop/reuse a song as a seed
`POST /api/sample`
```json
{ "clip_id": "<uuid or link>", "style": "boom bap, jazzy", "mv": "chirp-fenix" }
```

### Mashup — blend two songs
`POST /api/mashup`
```json
{ "clip_ids": ["<uuid or link A>", "<uuid or link B>"], "style": "epic", "mv": "chirp-fenix" }
```

### Extend — continue a song from a point in time
`POST /api/extend`
```json
{ "clip_id": "<uuid or link>", "continue_at": 60, "lyrics": "optional continuation lyrics", "style": "lofi", "mv": "chirp-fenix" }
```

All return: `{ "task_id": "...", "credits": <remaining>, "clips": [ { "id": "...", "status": "...", "audio_url": "...", "download_url": "..." } ] }` (or `{ "submitted", "succeeded", "credits", "results" }` for bulk).
Songs render in ~30–60s. Poll the library to get final audio.

### Your library
- `GET /api/my/clips` — list or search/filter your songs (`?q=<term>&title=&style=&status=&model=&limit=&offset=`).
- `GET /api/clip/<id>` — one song, with a fresh status.
- Audio streams from `GET /api/clip/<id>/audio`; download from `GET /api/clip/<id>/download`.

### Discover songs to remix
- `GET /api/search?q=<term>` — search public Suno songs → ids for cover/mashup.
- `GET /api/playlist?id=<id-or-link>` — list a playlist's songs.
- `POST /api/upsample-tags` with `{ "tags": "lofi", "instrumental": false }` — AI-improve a style string.

### Memory (reusable text: styles, lyrics, notes)
- `POST /api/memory` `{ "kind": "style", "label": "my lofi", "content": "lofi, oud, boom bap" }`
- `GET /api/memory?kind=style` — list; `GET /api/memory/<id>` — read one.
- `PATCH /api/memory/<id>` — update; `DELETE /api/memory/<id>` — delete.

### Feedback
- `POST /api/feedback` `{ "kind": "idea", "message": "..." }` — sent to the SunoMA admins.

## Typical flow
1. To remix a specific track, get its id via `search`/`playlist`, or ask the user to paste a Suno link.
2. Call the matching endpoint (`generate` / `cover` / `sample` / `mashup` / `extend`).
3. Tell the user it's rendering, then poll `GET /api/my/clips` until `status` is `complete`.
4. Share the `audio_url` / `download_url`.

## Curl quickstart
```bash
curl -X POST {{BASE_URL}}/api/generate \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{"mode":"simple","desc":"a warm acoustic morning song","tags":"acoustic, folk"}'
```

## Notes
- Covering your own songs always works; third-party songs need the creator's remix permission.
- To remix your own audio that isn't on Suno yet: upload it to your free Suno account, make it public, then paste the song link.