---
title: "Generate a song"
method: POST
path: "/music"
tags: ["Music"]
---

# Generate a song

`POST /music`

Generates an original song from a text prompt using AI. Use it as the soundtrack for a music video (`POST /music-videos`), or download it once ready.

**Flow:** create the song, then poll `GET /music/{id}` until `status` is `completed` (usually 30-90 seconds). The finished track also appears in `GET /music` and can be used as `musicId` in `POST /music-videos`.

**Modes:**
- Simple (default): describe the song in `prompt` and the AI writes everything (style, and lyrics unless `instrumental`).
- Custom (`customMode: true`): you control `style`, `title`, and `lyrics` directly. `prompt` is ignored for the words.

**Cost:** a flat fee per song (see the response `creditsUsed`). Credits are refunded automatically if generation fails.

## Request body

- object
  - `prompt` string, required — What the song should be about or sound like, e.g. "an upbeat indie pop track about summer road trips". In custom mode this is optional context; the words come from `lyrics` and the sound from `style`.
  - `instrumental` boolean — Set true for a track with no vocals or lyrics.
  - `customMode` boolean — Set true to control `style`, `title`, and `lyrics` yourself instead of letting the AI decide from `prompt`.
  - `style` string — Custom mode only: the musical style, e.g. "lo-fi hip hop, mellow, jazzy piano".
  - `title` string — Custom mode only: the song title.
  - `lyrics` string — Custom mode only: the exact lyrics to sing. Ignored when `instrumental` is true.

## Response `200`

OK

- object
  - `musicId` string, uuid, required — Poll `GET /music/{id}` until completed, then use as `musicId` in `POST /music-videos`.
  - `status` 'pending', required
  - `creditsUsed` number, required — Credits reserved for this song. Refunded automatically if generation fails.

## Other responses

- `401` — 401
- `402` — 402
- `403` — 403

---

[API](https://skmtc.net/aituber/apis/aituber-api.md) · [All operations](https://skmtc.net/aituber/apis/aituber-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aituber/aituber-api/revisions/35448566f143/schema)