Music generation

Status: Preview. The endpoints are callable and may still evolve before GA.

Use music generation for creator tools, campaign variations, branded audio sketches, loops, and background tracks.

Billing

Music is prepaid: the cost is debited from your wallet when the task is created, and refunded if the task fails or is canceled. Each model has a flat per-task price in credits.

Model	Price	USD reference (default rate `1000 cr/$`)
`suno-5.5`	`80.0000` credits	`≈ $0.0800`
`minimax-music-2.6`	`50.0000` credits	`≈ $0.0500`

Both models are live and callable. suno-5.5 returns two clips per task; minimax-music-2.6 returns a single clip per task. Both follow the async task model — poll GET /v1/tasks/{task_id} for the final output.

The task envelope carries the charge under billing.charged_credits and billing.charged_credits_usd_reference while the task runs, and refunded_* fields if the task fails. USD references are display-only.

Endpoints

Endpoint	Use it for
`POST /v1/music/text-to-music`	Generate music from a prompt, optional lyrics, and model options.
`POST /v1/music/reference-audio-to-music`	Generate a new music task from reference audio plus prompt guidance.
`GET /v1/tasks/{task_id}`	Poll the async task until it succeeds, fails, or is canceled.
`POST /v1/uploads`	Upload reference audio first when you want to reuse it by `artifact_id`.

Text to music

POST /v1/music/text-to-music
Authorization: Bearer <api_key>
Content-Type: application/json
Idempotency-Key: <uuid>

{
  "model": "suno-5.5",
  "prompt": "dream pop, warm analog drums, bright chorus",
  "lyrics": "[Verse]\nCity lights are waking",
  "instrumental": false,
  "model_options": {
    "suno": {
      "custom_mode": true,
      "style_weight": 0.6
    }
  }
}

The response is 202 Accepted with a task_id.

Reference audio to music

Upload a local audio file when you own the source material:

curl "$BEATRA_BASE_URL/uploads" \
  -H "Authorization: Bearer $BEATRA_API_KEY" \
  -F "purpose=reference_audio" \
  -F "file=@reference.mp3;type=audio/mpeg"

Then create a music task:

{
  "model": "suno-5.5",
  "prompt": "turn this into polished synth pop",
  "reference_audio": {
    "type": "artifact",
    "artifact_id": "artifact_01J..."
  }
}

External HTTPS URLs are downloaded and re-hosted before execution. Large or reusable source files should go through uploads first.

Model options

Shared fields stay at the top level: model, prompt, lyrics, instrumental, title, and metadata.

Model-specific knobs live under model_options:

model_options.suno for suno-5.5.
model_options.minimax for minimax-music-2.6.

Unknown option namespaces are rejected so client bugs are caught early.

Delivery

Music tasks follow the async task model. Poll GET /v1/tasks/{task_id} and store the final audio URL plus artifact_id from output.clips[].

Customer callbacks are Planned, so polling is the current delivery path.