---
title: "Generate music from a reference audio"
method: POST
path: "/v1/music/reference-audio-to-music"
tags: ["music"]
---

# Generate music from a reference audio

`POST /v1/music/reference-audio-to-music`

## Request

- Base URL: `https://api.beatra.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.beatra.ai/v1/music/reference-audio-to-music`
- Auth: none declared. Required headers: `Idempotency-Key`

## Headers

- `x-request-id` string, nullable
- `Idempotency-Key` string, required
- `authorization` string, nullable

## Request body

- ReferenceAudioToMusicRequest: Generate music from a prompt, optional lyrics, and reference audio.
  - `metadata` object, nullable: Caller-supplied metadata; limited by task creation policy.
  - `callback_url` string, nullable: HTTPS URL beatra will POST the final Task envelope to when the Task reaches a terminal state
  - `callback_signing_key_id` string, nullable: Optional standalone callback signing key. Omit for unsigned callback delivery; requires callback_url when provided.
  - `model` 'auto' | 'minimax-music-3.0' | 'suno-6', required
  - `prompt` string, required: Style, mood, genre, and instrumentation. When lyrics are supplied (or Suno custom mode is on) this maps to the provider's style-conditioning field; otherwise it is the song description the model writes the song from. Either way it is not an instruction field: execution directives written here (for example "do not omit anything", "sing it verbatim", "make chapter three differ from chapter one") are not read as instructions and will not be obeyed. Put the words to be sung in `lyrics`, or set `instrumental` to true for a track with no vocals.
  - `lyrics` string, nullable: Optional lyrics text. Must be omitted for instrumental music.
  - `instrumental` boolean: When true, generate instrumental music without vocals.
  - `title` string, nullable
  - `model_options` MusicModelOptions: Model-family scoped public options for music generation.
    - `suno` SunoMusicOptions
      - `custom_mode` boolean, nullable
      - `negative_tags` string, nullable: Suno traits to exclude; limited independently from prompt, lyrics, and title.
      - `vocal_gender` 'm' | 'f', nullable
      - `style_weight` number, nullable
      - `weirdness_constraint` number, nullable
      - `audio_weight` number, nullable
    - `minimax` MiniMaxMusicOptions
      - `lyrics_optimizer` boolean, nullable
      - `aigc_watermark` boolean, nullable
      - `audio_setting` MiniMaxMusicAudioSetting
        - `sample_rate` 16000 | 24000 | 32000 | 44100, nullable
        - `bitrate` 32000 | 64000 | 128000 | 256000, nullable
        - `format` 'mp3', nullable
  - `reference_audio` union, required
    - MediaInputUrl
      - `type` 'url', required
      - `url` string, required: HTTPS URL. External URLs are downloaded and re-hosted to beatra CDN.
    - MediaInputArtifact
      - `type` 'artifact', required
      - `artifact_id` string, required: ULID of a previously-uploaded artifact
    - MediaInputDataUri
      - `type` 'data_uri', required
      - `data` string, required: Data URI (e.g. data:image/png;base64,...) — max 256KB encoded

## Response `202`

Task accepted

- TaskEnvelope: Standard Task envelope. Returned by every async-creation endpoint, GET /v1/tasks/{id}, and the body of customer callback POSTs.
  - `object` 'task'
  - `task_id` string, required
  - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled', required
  - `capability` string, required
  - `workload_type` 'model' | 'social_operation'
  - `model` string, nullable: Caller-requested model verbatim (may be 'auto'). Null for social_operation tasks.
  - `resolved_model` string, nullable: Actual model that ran (null until execution starts; equals model for explicit-model calls)
  - `model_selection_reason` unknown
  - `social` SocialTaskIdentity
    - `platform` string, required
    - `operation_key` string, required
    - `operation_name` string, required
    - `schema_hash` string, required
  - `metadata` object, nullable
  - `input` object, nullable
  - `progress` AppApiV1SchemasCommonTaskProgress
    - `percent` integer, nullable
    - `stage` string, nullable
    - `message` string, nullable
  - `output` object, nullable
  - `warnings` TaskWarning[]
    - `code` string, required: e.g. option_clamped / auto_routed
    - `message` string, required
    - `field` string, nullable
  - `error` AppApiV1SchemasCommonTaskError
    - `code` string, required: Stable machine-readable public error code.
    - `type` string, required: Stable public error family.
    - `message` string, required: Human-readable safe failure reason.
    - `retryable` boolean, required: Whether the same logical request may succeed when retried unchanged.
    - `param` string, nullable: JSON Pointer to the relevant request or output field.
    - `details` object, nullable: Provider-neutral expected, received, supported, or candidate failure facts.
    - `request_id` string, required: Request trace identifier for support and correlation.
  - `usage` UsageObject
    - `input_tokens` integer, nullable
    - `output_tokens` integer, nullable
    - `cache_read_tokens` integer, nullable
    - `cache_creation_tokens` integer, nullable
    - `reasoning_tokens` integer, nullable
    - `image_count` integer, nullable
    - `image_pixels` integer, nullable
    - `video_seconds` number, nullable
    - `input_video_seconds` number, nullable: Authoritative input-video seconds included in settled video usage.
    - `output_video_seconds` number, nullable: Authoritative generated/output-video seconds included in settled video usage.
    - `audio_seconds` number, nullable
    - `characters` integer, nullable
    - `lines` UsageLine[]
      - `meter` string, required: e.g. input_token / output_token / image_count / input_video_second / output_video_second
      - `quantity` string, required: Decimal — number of meter units consumed
      - `unit` string, required: Display unit, e.g. 'token' / 'image' / 'second'
      - `billed_amount_credits` string, nullable: Credits charged for this usage line. Populated by PR-2/3.
    - `credits` string, nullable: Credits charged for this Task. Populated by PR-2 / PR-3.
  - `billing` TaskBilling
    - `charged_credits` string, nullable: Credits charged to wallet for this Task. Populated by PR-2/3.
    - `refunded_credits` string, nullable: Credits refunded for this Task. Populated by PR-3.
    - `granted_credits` string, nullable: Credits on this Task covered by a directed grant rather than by the wallet, net of any revocation. Absent when no grant applied.
    - `grant_source` string, nullable: Which grant covered it. Present exactly when granted_credits is.
    - `net_charged_credits` string, nullable: Final customer charge: charged_credits minus refunded_credits minus granted_credits. This is the number to report as what the Task cost.
  - `callback` TaskCallback
    - `url` string, required
    - `status` 'pending' | 'dispatching' | 'delivered' | 'retrying' | 'failed', required
    - `attempt_count` integer, required
    - `delivered_at` string, date-time, nullable
    - `last_error` string, nullable: Stable Beatra-owned callback delivery failure summary.
  - `created_at` string, date-time, required
  - `started_at` string, date-time, nullable
  - `deadline_at` string, date-time, nullable
  - `completed_at` string, date-time, nullable
  - `cancel_requested_at` string, date-time, nullable
  - `links` TaskLinks, required
    - `self` string, required
    - `cancel` string, nullable
    - `assets` string, nullable: Absolute customer-console URL for viewing and managing the generated artifacts.

## Other responses

- `422`: Unprocessable Entity

---

[API](https://skmtc.dev/beatra/apis/agent-service-api.md) · [All operations](https://skmtc.dev/beatra/apis/agent-service-api/llms.txt) · [OpenAPI document](https://skmtc.dev/beatra/apis/agent-service-api/revisions/58e440556498?raw)