---
name: neume
description: Make songs with vocals and music videos with Neume, on your own. Sign up for an API key, buy credits over MPP (HTTP 402), then call Neume's MCP tools. Use it when a user wants a song, a jingle, new lyrics for one of their songs, or a music video.
---

# Neume

Neume makes full songs with vocals from a title, a style and lyrics (about a minute each), changes the words of one part of a song in the same voice, remakes a song in a new style, and makes music videos set to a song. Everything works over HTTP with no browser.

API base: `https://api.neume.io`. Human guide: https://neume.io/agents

## 1. Sign up (once)

```bash
curl -X POST https://api.neume.io/v1/agents/signup \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent"}'
```

The answer has `apiKey` (`neu_sk_...`). It is shown once: store it as a secret. New accounts have 0 credits.

## 2. Buy credits

- `GET https://api.neume.io/v1/agents/credits` lists the credit packs: `productId`, `credits`, `price` (USD).
- `POST https://api.neume.io/v1/agents/credits/{productId}` with the key in the `X-API-Key` header (not `Authorization`) answers `402 Payment Required` with an MPP challenge in `WWW-Authenticate`. Pay it and send the same request again with `Authorization: Payment ...`. The answer is `{"added", "credits", "reference"}` with a `Payment-Receipt` header.
- Payment method: a card through a shared payment token (Stripe). With Link's agent wallet (`npm i -g @stripe/link-cli`):

```bash
link-cli spend-request create \
  --credential-type shared_payment_token \
  --network-id profile_61Vf6kfEOu5n9kPtbA6Vf6kf6ySQSZlbgxdy025k0I0e \
  --amount 499 \
  --context "10 Neume credits so I can make a song the user asked for (a jingle for their bakery)." \
  --request-approval

link-cli mpp pay https://api.neume.io/v1/agents/credits/5 \
  --spend-request-id lsrq_... \
  --method POST \
  --header "X-API-Key: neu_sk_..."
```

`--amount` is in cents and must match the pack's price. Any MPP client works (for example `mppx`).

Only spend what the user asked for or agreed to. Tell them the price before buying.

## 3. Make songs and videos (MCP)

MCP server: `https://api.neume.io/v1/mcp`, Streamable HTTP, header `Authorization: Bearer neu_sk_...`.

MCP client config:

```json
{ "mcpServers": { "neume": { "url": "https://api.neume.io/v1/mcp", "headers": { "Authorization": "Bearer neu_sk_..." } } } }
```

Without an MCP client, call a tool with plain JSON-RPC:

```bash
curl -X POST https://api.neume.io/v1/mcp \
  -H "Authorization: Bearer neu_sk_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_balance","arguments":{}}}'
```

The answer is a server-sent event: read the `data:` line. The tool's result is JSON in `result.content[0].text`; `result.isError` is true when it failed.

### Tools

| Tool | What it does | Credits |
|---|---|---|
| `generate_song` | A song from `title`, `style` (genre, mood, instruments, voice) and `lyrics` with part tags (`[Verse]`, `[Chorus]`, `[Bridge]`). No lyrics makes an instrumental. Returns `songIds`. | 1 |
| `get_song_details` | `songId` → status, title, cover, lyrics with times, audio link. | 0 |
| `get_my_songs` | The account's songs, newest first (`page`, `limit`). | 0 |
| `get_song_parts` | A song's parts (`verse#1`, `chorus#2`...) with their lines and times. Call before `change_lyrics`. | 0 |
| `change_lyrics` | New words for one part (5 to 30 seconds), sung in the same voice. Makes a new song; the original is kept. | 1 |
| `reimagine_song` | The whole song again in a new `style`, with its own words unless new `lyrics` are given. Makes a new song. | 2 |
| `make_video` | A music video for one of the account's songs: `songId`, `prompt` (the scene, in English), `seconds` 4 to 30 (default 10), `part` `chorus` or `start`, `hd`. Returns `videoId`. | seconds + 1 (11 for 10 s); HD costs more |
| `get_video_details` | `videoId` → `making`, `done` (with `videoUrl` and `posterUrl`, valid 6 hours) or `failed` (refunded). | 0 |
| `get_balance` | The account's credits. | 0 |
| `list_topup_packages` | The credit packs and prices. | 0 |

### How to work

- Write the lyrics yourself unless the user gave them. Use part tags and keep lines singable. Show the user the lyrics before making the song when they're around to see them.
- A song takes 30 to 120 seconds: poll `get_song_details` every 15 to 20 seconds until `status` is `completed`. A video takes a few minutes: poll `get_video_details` every 30 seconds.
- Audio and video links expire: download the file, or call the details tool again for a fresh link.
- Videos: describe made-up people only, never real, famous or named people.
- To fix how a word is sung, write it as it sounds in the lyrics (Eroica → Ih-ROH-ih-kuh). Everything in the lyrics is sung, so never add notes in brackets.

## Errors

- `401` on `/v1/agents/*` or the MCP server: missing or wrong key. Sign up if you have none.
- `402` on the credits route: the payment challenge (expected before paying), or a payment that failed verification. Make a new payment; one payment can't be used twice.
- `Insufficient balance` or `INSUFFICIENT_CREDITS` from a tool: not enough credits. Buy a pack, then call the tool again.
- `429`: too many requests in a minute; wait and retry.

## Rights

Original songs made with Neume belong to the account that made them, including for commercial use. Changing or remixing audio someone else made doesn't give rights to it.