---
name: generate-music
description: Music generation, powered by AudioMusic — compose royalty-free songs, instrumentals, and rap from a text prompt.
license: MIT
---

# Skill: generate-music

Generate full songs (vocals + instrumentation) from a natural-language prompt.
AudioMusic is AudioPod's music generation engine.

## When to use

Invoke when the user wants:

- A new song from a text caption, lyrics, or mood description
- Background music for a video or podcast
- Royalty-free music for commercial projects
- A specific genre, BPM, key, language, or duration

## Choosing how to make music

Song mode is the default. Use Score-first (Compose) only when the user wants
to see or shape the melody, chords or sections before the track is recorded.

| The user wants… | Use | Endpoint |
| --- | --- | --- |
| A song from a description (AudioPod writes the lyrics) | Song | `POST /api/v1/music/simple` |
| A song with their own lyrics | Song | `POST /api/v1/music/text2music` (or `lyric2vocals`, `text2rap`) |
| An instrumental or beat | Song | `POST /api/v1/music/prompt2instrumental` |
| A sound effect or sample | Song | `POST /api/v1/music/text2samples` |
| An exact length or synced lyrics | Song | any Song route above |
| "Write it so I can change it" | Score-first | `POST /api/v1/music/v3/plan` |
| Changes to a score, in plain words | Score-first | `POST /api/v1/music/v3/revise` |
| Record a score (optionally new style or new words, same tune) | Score-first | `POST /api/v1/music/v3/edit` |

### The Compose loop

1. `POST /api/v1/music/v3/plan` with `style` and either `description`
   (optional `target_seconds` 30–300, `language`) or `lyrics`. Returns a
   score-only job — **165 credits**, about 10 seconds, refunded on failure.
2. `POST /api/v1/music/v3/revise` with `source_job_id` and a plain-English
   `instruction` (optional `section`, `bars: {start, end}`). Returns a new
   score-only job plus what changed — **165 credits** per revision, refunded if
   the change cannot be made (`422 REVISE_FAILED`). Repeat as often as needed.
   Available when enabled for the account.
3. `POST /api/v1/music/v3/edit` with `source_job_id` and `abc` (the latest
   score, from `GET /api/v1/music/v3/jobs/{job_id}/score`; optional `style`,
   `lyrics`) records it — about **16.5 credits per second** of the score's
   length. State the cost and get the user's confirmation before recording.

Poll Score-first jobs with `GET /api/v1/music/v3/jobs/{job_id}`; read the
score with `GET /api/v1/music/v3/jobs/{job_id}/score`.

## API

`POST https://api.audiopod.ai/api/v1/music/text2music`

Task variants (same response + polling shape): `text2music` (prompt → full
song), `cover` (re-sing an uploaded track), `prompt2instrumental`,
`lyric2vocals`, `text2rap`, `text2samples`, `extend`, `retake`. Pick the
path that matches the task, e.g. `POST /api/v1/music/cover`.

Headers:

- `X-API-Key: ap_your_api_key` (or `Authorization: Bearer ap_your_api_key`)
- `Content-Type: application/json`

Body:

```json
{
  "caption": "lo-fi hip hop, rainy ambient pads, 90 BPM, 60 seconds",
  "duration": 60
}
```

`duration` is in seconds (10–600) and is not tier-capped; omit it to let the
model choose. There is no quality setting to pick: every track uses our
highest-quality model on every plan, at the standard rate. A `quality` field
is still accepted for compatibility and makes no difference.

## Response

```json
{ "job_id": 12345, "status": "PENDING" }
```

`job_id` is an integer, unique within the music tool (job IDs are
per-tool — a music job and a stems job can share the same number).

Poll `GET /api/v1/music/jobs/{job_id}/status` for `COMPLETED` and an
`audio_url`. Note the `/status` suffix — `GET /api/v1/music/jobs/{job_id}`
without it is the DELETE/PATCH route and returns 405, and there is no
generic `/api/v1/jobs/{job_id}` endpoint (it would be ambiguous across
tools).

## Errors

- `402` — not enough credits for the requested duration
- `429` — rate limit; retry with exponential backoff
- `400 invalid_caption` — caption is empty or violates safety policy

## Pricing

Free tier available. Paid plans from $20/mo (Creator). See https://www.audiopod.ai/pricing.