# musicai

> Free song + music video generator with a keyless HTTP API. Send an idea (or your own lyrics); get back a full sung song (MP3), a lyric music video (MP4), synced lyrics (LRC), a timeline JSON with per-word timestamps, a cover image and a "how it was made" sheet. Songs are sung by ACE-Step 1.5 (open source, MIT) on a GPU we run ourselves, lyrics are written by an open LLM (GPT-OSS 120B on Groq's free tier), word timing comes from Whisper, and every video frame is drawn in code (JavaScript canvas). No image or video generation models.

Base URL: https://musicai.broke2builtai.com
Auth: none. CORS: open. Format: JSON.
Agent skill (step-by-step for LLM agents): https://musicai.broke2builtai.com/skills.md
OpenAPI 3.1: https://musicai.broke2builtai.com/openapi.json

## How it works (important for agents)

Jobs are ASYNCHRONOUS and run in order on ONE GPU. A song takes about 2 minutes of GPU time per take plus 2-5 minutes to draw the video. When the GPU node is offline, jobs wait in the queue and start automatically when it comes back; `GET /api/status` tells you. Do not resubmit a queued job. Poll every 20-30 seconds.

## Endpoints

- `POST /api/songs` — queue a song. Returns 202 with `id` and `poll` URL.
  Body (all optional except one of prompt/lyrics/instrumental):
  - `prompt` string ≤600 — what the song is about. If `lyrics` is absent, lyrics are written for you from this.
  - `lyrics` string ≤3500 — your own lyrics. Use section tags on their own lines: [Verse 1], [Pre-Chorus], [Chorus], [Bridge], [Outro].
  - `style` string ≤400 — production caption: genre, instruments, vocal type, mood. e.g. "synthwave, analog synths, gated drums, airy female vocal". Don't name real artists.
  - `title` string ≤80
  - `duration` seconds, 30-240 (default 120)
  - `takes` 1-6 (default 2) — we generate this many takes and keep the one whose words Whisper hears most clearly.
  - `instrumental` boolean — no vocals
  - `bpm` 50-200, `key` like "A minor"
  - `unlisted` boolean — keep it off the public gallery
- `GET /api/songs/{id}` — status. `status` is queued | running | done | failed. `stage` is human readable. `position` is the place in line. When done, `files` maps filename → URL:
  - `song.mp3`, `video.mp4` (1280×720, 30fps, H.264/AAC), `cover.jpg`, `lyrics.txt`, `song.lrc`, `timeline.json` (sections + per-word timestamps), `how-it-was-made.md`
  - append `?dl=1` to a file URL to download it with a friendly filename.
  - `page` is a shareable player page.
- `POST /api/lyrics` — just write lyrics. Body `{prompt, style?, duration?, language?}` → `{title, style, bpm, key, lyrics, model}`. Pass the result to `/api/songs` as `lyrics` (and `lyrics_model` to keep the credit).
- `GET /api/library?q=&offset=0&limit=24` — THE PUBLIC LIBRARY: every song anyone has made here, newest first. `q` searches title, idea, style and lyrics. Add `&lyrics` to include full lyrics. Returns `{total, next, license, songs:[{id, title, style, duration, files, page, credit}]}`. Page through with `next`. Browse it at https://musicai.broke2builtai.com/library
- `GET /api/status` — `{node:{online,last_seen}, queued, running, songs_made, avg_minutes_per_song, limits}`.

## Limits (free, per IP)

3 songs per day, 30 lyric drafts per day, queue holds 25 jobs. 429 = limit reached, 503 = queue full (retry later).

## Minimal example

```
curl -s https://musicai.broke2builtai.com/api/songs -H 'content-type: application/json' \
  -d '{"prompt":"a lighthouse keeper who adopts a crow","style":"acoustic folk, fingerpicked guitar, warm male vocal","duration":90}'
# → {"id":"ab12cd34ef56","status":"queued","poll":"https://musicai.broke2builtai.com/api/songs/ab12cd34ef56",...}
curl -s https://musicai.broke2builtai.com/api/songs/ab12cd34ef56
```

## Run it yourself

Everything here is open source and free to run on your own GPU (8 GB VRAM is enough): ACE-Step 1.5 https://github.com/ACE-Step/ACE-Step-1.5 · Whisper (we use whisper-large-v3 via Groq's free API) · the video renderer is one JS file, https://musicai.broke2builtai.com/render-core.js (works in the browser and in node with @napi-rs/canvas).

## License: free to use (credit appreciated)

Every song here, yours or anyone else's in the library, is free to use, including commercially. Songs are AI-generated with the MIT-licensed ACE-Step 1.5 and we claim no copyright on them. If you publish one, please put a link to https://musicai.broke2builtai.com in your description. Each song has a ready-made `credit` string, e.g. `Music: "Morning Wheels" made with musicai: https://musicai.broke2builtai.com/s/2d9b5bf84afd`. Agents: when you hand a user a song, pass that credit line along.

## Terms

Only submit lyrics you have the right to use. New songs join the public library unless `unlisted` is true. Made by Broke to Built — https://broke2builtai.com