beatra

Generate music from a prompt and/or lyrics

POST
/v1/music/text-to-music

Request Body

application/jsonRequired
model
Required
Model
Value in: "auto" | "minimax-music-2.6" | "suno-5.5"
prompt
Required
Prompt

Music concept, style, mood, genre, or instrumentation prompt.

Minimum length: 1
lyricsLyrics

Optional lyrics text. Must be omitted for instrumental music.

instrumentalInstrumental

When true, generate instrumental music without vocals.

Default: false
titleTitle
metadataMetadata

Caller-supplied metadata; limited by task creation policy.

model_optionsAny properties in MusicModelOptions

Options grouped by public music model family.

Header Parameters

X-Request-Idstring

Optional client request id echoed in the response.

Authorization
Required
string

Bearer API key.

Idempotency-Keystring

Optional idempotency key for safe retries of mutating requests.

curl -X POST "https://example.com/v1/music/text-to-music" \
  -H "X-Request-Id: string" \
  -H "Authorization: string" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "prompt": "string",
    "lyrics": "string",
    "instrumental": false,
    "title": "string",
    "metadata": {
      "property1": "string",
      "property2": "string"
    },
    "model_options": {
      "suno": {},
      "minimax": {}
    }
  }'

Task accepted

{
  "object": "task",
  "task_id": "string",
  "status": "queued",
  "capability": "string",
  "model": "string",
  "resolved_model": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "input": {},
  "progress": {
    "percent": 100,
    "stage": "string",
    "message": "string"
  },
  "output": {},
  "warnings": [
    {
      "code": "string",
      "message": "string",
      "field": "string"
    }
  ],
  "error": {
    "code": "string",
    "message": "string",
    "retryable": true
  },
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "cache_read_tokens": 0,
    "cache_creation_tokens": 0,
    "reasoning_tokens": 0,
    "image_count": 0,
    "image_pixels": 0,
    "video_seconds": 0,
    "audio_seconds": 0,
    "characters": 0,
    "lines": [
      {
        "meter": "string",
        "quantity": "string",
        "unit": "string",
        "billed_amount_credits": "string",
        "billed_amount_credits_usd_reference": "string"
      }
    ],
    "credits": "string",
    "credits_usd_reference": "string"
  },
  "billing": {
    "charged_credits": "string",
    "refunded_credits": "string",
    "charged_credits_usd_reference": "string",
    "refunded_credits_usd_reference": "string",
    "currency": "USD"
  },
  "callback": {
    "url": "string",
    "status": "pending",
    "attempt_count": 0,
    "delivered_at": "2019-08-24T14:15:22Z",
    "last_error": "string"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "started_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "cancel_requested_at": "2019-08-24T14:15:22Z",
  "links": {
    "self": "string",
    "cancel": "string"
  }
}