# Music, sound effects and audio tools

> Generate songs, instrumentals and sound effects, or extract audio from a video, with async POST /v1/audio/generations tasks on BigModel.io.

Web version: https://bigmodel.io/docs/audio-generation · Updated 2026-10-18

Music, sound-effect and audio-tool models run as asynchronous tasks on `POST /v1/audio/generations`. Create a task, poll it, then download the file. Music and sound effects are priced per call; audio extraction per second of input video. Failed tasks are not charged. Models are listed under [Models → Audio](https://bigmodel.io/models?type=Audio).

| Step | Request |
|---|---|
| Create a task | `POST /v1/audio/generations` |
| Check status | `GET /v1/audio/generations/{id}` |
| Download | `GET /v1/audio/generations/{id}/content` |

## Create a song

```bash [cURL]
curl https://bigmodel.io/v1/audio/generations \
  -H "Authorization: Bearer $BIGMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rain-song-1" \
  -d '{
    "model": "minimax-music-3",
    "prompt": "Warm acoustic folk, slow tempo, female vocal",
    "lyrics": "[verse]\nRain on the window, tea on the stove\n[chorus]\nStay a little longer"
  }'
```

```python [Python]
import os, time, requests

BASE = "https://bigmodel.io/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['BIGMODEL_API_KEY']}"}

task = requests.post(f"{BASE}/audio/generations", headers=HEADERS, json={
    "model": "minimax-music-3",
    "prompt": "Calm lo-fi beat for studying",
    "instrumental": True,
}).json()

while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{BASE}/audio/generations/{task['id']}", headers=HEADERS).json()

if task["status"] == "succeeded":
    audio = requests.get(f"{BASE}/audio/generations/{task['id']}/content", headers=HEADERS)
    open("song.mp3", "wb").write(audio.content)
```

An accepted task returns `202` with a `Location` header and `{"id": "...", "object": "audio.generation", "status": "queued", "estimated_cost_usd": ...}`.

## Fields by model type

| Type | Fields |
|---|---|
| Music | `prompt` (style and mood) and/or `lyrics`; `instrumental: true` for no vocals |
| Sound effects | `prompt` (required); `seconds` for the length where the model supports it |
| Audio extract (`audio-extract`) | `video` (required); `isolate_voice: true` to keep only the voice; `transcribe: true` for a transcript |
| Speech | the same fields as [`/v1/audio/speech`](https://bigmodel.io/docs/text-to-speech), returned as a task |

Inputs such as `video` are public `https://` URLs or base64 data URIs, up to 50 MB each.

Add `"dry_run": true` to any body to get a price quote without starting work. Send an `Idempotency-Key` header (up to 200 characters) so a retried request returns the original task instead of a second one.

## Status and download

`status` is `queued`, `running`, `succeeded`, `failed` or `canceled`. A succeeded task has `output: {"type": "audio", "url": "...", "expires_in": 86400}` and `cost_usd`. The link works without an API key for 24 hours. `/content` redirects (`302`) to the same file; with `curl` use `-L`. Tasks that do not finish within 3 hours end as `failed` and are not charged.

## Verify the setup

Create the instrumental example, poll until `succeeded`, then open the downloaded file. The charge appears in [Usage](https://bigmodel.io/usage).

## Troubleshooting

**400 "prompt or lyrics is required".** Music needs a style prompt, lyrics, or both.

**400 "video is required for this model".** Audio tools work on a video input.

**402 `insufficient_balance`.** Your balance, minus tasks still running, does not cover the estimate. Top up in [Billing](https://bigmodel.io/purchase).

**404 `model_not_available`.** The model is not offered to this key, or it belongs on another endpoint (video models use `/v1/videos`).

**409 `not_ready`** on `/content`. The task has not succeeded yet. Keep polling.

**`failed` with `error.message`.** The model could not produce the audio, often because of the prompt or lyrics. You are not charged.

## Related

- [Text to speech](https://bigmodel.io/docs/text-to-speech).
- [Video generation](https://bigmodel.io/docs/video-generation): music can drive `latentsync-music`.
- [Pricing](https://bigmodel.io/pricing).