Reference audio to music

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

Tool arguments

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