---
name: musicai
description: Make a full AI song (sung vocals) plus a lyric music video from a one-line idea, for free, over a keyless HTTP API. Use when the user wants an original song, jingle, theme tune, birthday song, lyric video, or synced lyrics (LRC) — no browser needed. Returns MP3, MP4, LRC, per-word timeline JSON, cover image and a "how it was made" sheet.
---

# musicai — songs + music videos over HTTP

Base URL `https://musicai.broke2builtai.com` · no key · JSON · CORS open.
Models: ACE-Step 1.5 (open source, MIT) sings, GPT-OSS 120B (Groq free tier) writes lyrics, Whisper times the words, and the video is drawn in code (JavaScript canvas). No image or video generation models.

## When to use

- The user asks for a song, jingle, anthem, lullaby, diss track, theme tune or birthday song, with or without a video.
- The user has lyrics and wants them sung, or wants a lyric video or an LRC file.
- The user needs free background music right now: search the public library first (`GET /api/library?q=<mood or genre>`). It's instant, and there's no queue.
- Don't use it for real artists' songs or lyrics the user doesn't own.

## Procedure

1. **Optional: draft lyrics first** if the user wants to review them:
   `POST /api/lyrics` `{"prompt": "<idea>", "style": "<sound>", "duration": 120}` → `{title, style, bpm, key, lyrics, model}`.
   Show them; apply edits.
2. **Queue the song:** `POST /api/songs`
   ```json
   {"prompt": "<idea>", "style": "<genre, instruments, vocal type, mood>", "duration": 120, "takes": 2,
    "lyrics": "<optional, with [Verse 1]/[Chorus] tags>", "title": "<optional>", "lyrics_model": "<model from step 1, if used>"}
   ```
   Response 202 → keep `id`. Tell the user the job is queued and give its `page` link.
3. **Poll** `GET /api/songs/{id}` every 20–30 s. `status`: `queued` (check `position`, `node.online`) → `running` (`stage` says what's happening) → `done` | `failed`.
   - Typical time: ~2 min of GPU per take + 2–5 min drawing the video, plus any queue.
   - If `node.online` is false the GPU is off. The job is still safe in the queue, so don't resubmit. Tell the user it'll start when the GPU is back, and give them the `page` link to check later.
4. **Deliver** `files` when it's done:
   - `video.mp4`: music video (1280×720, H.264/AAC)
   - `song.mp3`: the song
   - `song.lrc` / `timeline.json`: synced lyrics / per-word timestamps
   - `lyrics.txt`, `cover.jpg`, `how-it-was-made.md`
   - Add `?dl=1` to a URL for a download with a nice filename. `page` is a shareable player.

## The public library (free to use)

`GET /api/library?q=<words>&offset=0&limit=24` → `{total, next, license, songs}`. This is every song anyone has made here, searchable by title, idea, style and lyrics. Each song has `files` (mp3/mp4/...), a `page`, and a `credit` string. All songs are free to use, commercial too, and we claim no copyright. **When you give a user a song, include its `credit` line and ask them to link https://musicai.broke2builtai.com in their description.** Browse it at https://musicai.broke2builtai.com/library

## Writing good inputs

- `style` is a production caption, not a sentence. Good: `"liquid drum and bass, fast breakbeats, deep sub bass, lush pads, soulful female vocal, uplifting"`. Never put real artist names in it.
- Lyrics: short singable lines (4–10 words), each section tag on its own line, and a chorus that repeats. Plan about 2 lines per 10 s of sung time.
- `takes`: 1 is fastest, 2 is the default, up to 6 gives the clearest vocals (we keep the take whose words Whisper hears best).
- `instrumental: true` gives no vocals and skips the lyrics.

## Limits & errors

- 3 songs/day/IP, 30 lyric drafts/day/IP, the queue holds 25 jobs.
- `429`: daily limit hit, so tell the user and stop.
- `503`: queue full, retry in ~15 min.
- `502` on lyrics: the free LLM is busy, so retry once or send your own `lyrics`.
- `400`: bad input, and the `error` field says why.

## Self-hosting

Want no limits? Run the same stack on any 8 GB+ NVIDIA GPU:
- ACE-Step 1.5: https://github.com/ACE-Step/ACE-Step-1.5
- The video renderer is a single ES module: https://musicai.broke2builtai.com/render-core.js, with `createScene({W,H,timeline,meta,makeCanvas}).draw(ctx, t)`. It works in the browser and in node with `@napi-rs/canvas`. The `timeline.json` from any finished song is a working example input.

Full reference: https://musicai.broke2builtai.com/llms.txt · OpenAPI: https://musicai.broke2builtai.com/openapi.json