# Text to music
> Generate full songs with vocals or instrumental tracks from text prompts and lyrics.

Generate full songs with vocals or instrumental tracks from text prompts and lyrics.

## Primary agent path

Use the Universal Skill with the MCP tool `beatra.music.generate`. The tool is
billable and returns an asynchronous task.

1. Settle the outcome: vocal song or instrumental, mood, and whether the user
   supplies lyrics.
2. If a model, control, constraint, or price matters, call `beatra.models.list`
   with `capability: "text_to_music"`. Otherwise use `model: "auto"` or omit
   `model`.
3. Create one opaque `client_request_id` and submit the final arguments once.
4. Poll the returned task with `beatra.tasks.get` until it is terminal.

## AI guide

AI integration guide: https://docs.beatra.ai/llms/music-text-to-music.md

## Tool arguments

```json
{
  "prompt": "Upbeat city pop for a summer evening drive",
  "instrumental": false,
  "lyrics": "Evening wind sweeps across the rooftop\nNeon lights flicker on one by one",
  "client_request_id": "music-text-opaque-1"
}
```

`instrumental: true` generates instrumental-only music and forbids `lyrics`.

## Models, controls, and cost

Common controls are `prompt`, `lyrics`, `instrumental`, `title`, and
`model_options`. Use each only according to the selected model's metadata.

`beatra.models.list` is the current source for selectable models, prompt and
lyrics length limits, vocal-lyrics requirements, model-family options, and the
per-task price. Do not copy a model catalog or price table into an
agent prompt.

Model-family options under `model_options.*` require an explicit `model`;
unsupported combinations fail validation instead of being silently ignored.
Music is prepaid and billed per successful task at the selected model's
catalog price.

### Suno 6 & MiniMax Music 3.0

Selectable text-to-music models include **Suno 6** (`suno-v6`, `suno-v5.5`, `suno-v5`, `suno-v4.5`) and **MiniMax Music 3.0** (`minimax-music-3.0`, `minimax-music-2.6`). Both families support full vocal songs with structured section tags (`[Verse]`, `[Chorus]`, `[Bridge]`, `[Outro]`) as well as instrumental-only generation (`instrumental: true`). Check `beatra.models.list` with `capability: "text_to_music"` for live per-track credit pricing and model-specific `model_options`.

## Task status and recovery

`queued` and `running` are not failures. Keep polling the same `task_id`; never
submit a replacement because work is still running. On a lost create response,
retry the identical arguments with the same `client_request_id`. If any input
changes, use a new ID. Failed tasks automatically refund the charged credits.

A successful task returns one or more `clips[]`, each with a title, optional
lyrics, and an audio artifact. Artifact URLs are CDN addresses — copy them to
your own storage promptly.

## REST API

Direct protocol integrations may use `POST /v1/music/text-to-music` and the
shared task endpoints. Follow the generated [API operation](https://docs.beatra.ai/en/docs/api-reference/operations/music/text_to_music_v1_music_text_to_music_post).
Skill + MCP is the recommended integration; use REST for custom, non-agent
applications.