# Reference audio to music
> Generate new music based on the style of a reference audio clip.

Generate new music based on the style of a reference audio clip.

## Primary agent path

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

1. Upload local reference audio with `beatra.assets.upload` and use its
   artifact ID; an artifact from any successful Beatra music task also works
   directly.
2. If a model, reference constraint, or price matters, call
   `beatra.models.list` with `capability: "reference_audio_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-reference-audio-to-music.md

## Tool arguments

```json
{
  "prompt": "Keep the groove of the reference track, shift it to a festive mood",
  "reference_audio": { "type": "artifact", "artifact_id": "artifact_01JX..." },
  "client_request_id": "music-cover-opaque-1"
}
```

`reference_audio` accepts an artifact, HTTPS URL, or data URI.

## Models, controls, and cost

Common controls are `prompt`, `reference_audio`, `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, reference
duration/size/format limits (`constraints.reference_audio`), prompt and lyrics
limits, and the per-task price. Do not copy a model catalog or price
table into an agent prompt.

Not every control is available on every model — an instrumental
reference-audio request, for example, requires a model that supports it.
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 the same `clips[]` structure as
[text to music](https://docs.beatra.ai/en/docs/capabilities/music/text-to-music) (`output.type` is
`reference_audio_to_music`). Artifact URLs are CDN addresses — copy them to
your own storage promptly.

## REST API

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