Text to music

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

Tool arguments

{
  "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 customer 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.

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. Skill + MCP is the recommended integration; use REST for custom, non-agent applications.