# 音乐、音效与音频工具

> 通过 BigModel.io 的异步 POST /v1/audio/generations 任务生成歌曲、纯音乐和音效，或从视频中提取音频。

网页版: https://bigmodel.io/zh-cn/docs/audio-generation · 更新于 2026-10-18

音乐、音效和音频工具模型通过 `POST /v1/audio/generations` 以异步任务运行：创建任务、查询状态、下载文件。音乐和音效按次计费，音频提取按输入视频秒数计费。失败的任务不收费。模型见[模型目录 → 音频](https://bigmodel.io/zh-cn/models?type=Audio)。

| 步骤 | 请求 |
|---|---|
| 创建任务 | `POST /v1/audio/generations` |
| 查询状态 | `GET /v1/audio/generations/{id}` |
| 下载 | `GET /v1/audio/generations/{id}/content` |

## 生成一首歌

```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": "温暖的原声民谣，慢节奏，女声",
    "lyrics": "[verse]\n雨落在窗上，茶在炉上\n[chorus]\n再多留一会儿"
  }'
```

```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": "适合学习时听的舒缓 lo-fi",
    "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)
```

任务受理后返回 `202`、`Location` 响应头和 `{"id": "...", "object": "audio.generation", "status": "queued", "estimated_cost_usd": ...}`。

## 各类模型的字段

| 类型 | 字段 |
|---|---|
| 音乐 | `prompt`（风格与情绪）和/或 `lyrics`；`instrumental: true` 生成纯音乐 |
| 音效 | `prompt`（必填）；模型支持时可用 `seconds` 指定时长 |
| 音频提取（`audio-extract`） | `video`（必填）；`isolate_voice: true` 只保留人声；`transcribe: true` 同时返回文字稿 |
| 语音 | 与 [`/v1/audio/speech`](https://bigmodel.io/zh-cn/docs/text-to-speech) 字段相同，以任务形式返回 |

`video` 等输入可以是公开的 `https://` 链接或 base64 data URI，单个不超过 50 MB。

任何请求体加上 `"dry_run": true` 都会只返回报价、不开始生成。带上 `Idempotency-Key` 请求头（最多 200 个字符），重试时会拿回原任务而不是再建一个。

## 状态与下载

`status` 依次为 `queued`、`running`，最终为 `succeeded`、`failed` 或 `canceled`。成功的任务带有 `output: {"type": "audio", "url": "...", "expires_in": 86400}` 和 `cost_usd`。链接无需 API Key 即可访问，有效期 24 小时。`/content` 会 `302` 跳转到同一文件，`curl` 需加 `-L`。3 小时内未完成的任务会以 `failed` 结束，不收费。

## 验证配置

创建上面的纯音乐示例，查询到 `succeeded` 后打开下载的文件。扣费记录在[用量](https://bigmodel.io/usage)中。

## 常见问题排查

**400 “prompt or lyrics is required”。** 音乐需要风格描述、歌词或两者兼有。

**400 “video is required for this model”。** 音频工具需要输入视频。

**402 `insufficient_balance`。** 余额扣除运行中任务后不足以覆盖预估，请到[充值](https://bigmodel.io/purchase)页面充值。

**404 `model_not_available`。** 该模型不对这个 Key 开放，或应调用其他接口（视频模型使用 `/v1/videos`）。

**`/content` 返回 409 `not_ready`。** 任务尚未成功，请继续查询。

**任务 `failed` 并带有 `error.message`。** 模型未能生成音频，常见原因是提示词或歌词。不收费。

## 相关文档

- [语音合成](https://bigmodel.io/zh-cn/docs/text-to-speech)。
- [视频生成](https://bigmodel.io/zh-cn/docs/video-generation)：音乐可用于 `latentsync-music` 对口型。
- [定价](https://bigmodel.io/zh-cn/pricing)。