---
url: /music.md
description: >-
  简创AIGC 音乐能力文档：音乐生成接口 POST /v1/music/generations，基地址
  https://api.jcaigc.cn/v1，异步任务按次计费（0.25~1 元/次），支持 MiniMax Music 2.0 / 3.0。
---

# 音乐

[← 返回全部能力](/)

用一段风格提示词加一段歌词，生成一首完整的歌。提交是异步的：先拿任务号，再轮询取结果。

## 接口一览

| 接口 | 方法与路径 | 说明 |
|------|-----------|------|
| 提交生成任务 | `POST /v1/music/generations` | 返回任务号，此时还没有音频地址 |
| 轮询任务结果 | `GET /v1/music/generations/{task_id}` | 查询进度，完成后返回音频地址 |

基地址 `https://api.jcaigc.cn/v1`，请求头带 `Authorization: Bearer <密钥>`（也接受 `x-api-key`），密钥是[控制台](https://jcaigc.cn)里的 apiKey。

### 支持的模型

| 模型 | 说明 |
|------|------|
| `minimax-music-2.0` | MiniMax Music 2.0，成本更低的一档 |
| `minimax-music-3.0` | MiniMax Music 3.0，更新的编曲与演唱效果，支持采样率与码率设置 |

两款模型都由 MiniMaxMusic 承接，一次任务生成一首完整的歌。调用 `GET /v1/models` 可以拿到当前账号可用的准确清单。

### 请求参数

| 参数 | 必填 | 说明 |
|------|------|------|
| `model` | 是 | 模型名，取值见上表 |
| `prompt` | 是 | 风格提示词，描述曲风、乐器、人声音色与情绪 |
| `lyrics` | 否 | 歌词；可用 `[Verse]` / `[Chorus]` 标注段落，留空则由模型按风格自行发挥 |
| `output_format` | 否 | 输出格式，`mp3` / `wav` / `flac`，缺省 `mp3`；别名 `format` 同样接受 |
| `sample_rate` | 否 | 采样率（Hz），仅 `minimax-music-3.0` 支持 |
| `bitrate` | 否 | 码率（bps），仅 `minimax-music-3.0` 支持 |

::: tip 音频地址有效期
生成结果保存在临时存储里，音频地址**7 天**后失效。需要长期保存时，请在拿到地址后及时下载。
:::

### 提交响应

提交成功即刻返回（HTTP 200），此时歌还没生成好：

```json
{
  "id": "task_...",
  "task_id": "task_...",
  "object": "music.generation",
  "created": 1699999999,
  "model": "minimax-music-3.0",
  "status": "queued",
  "progress": 0
}
```

`id` 与 `task_id` 是同一个值的两个别名，按客户端习惯取用即可。

### 轮询响应

```json
{
  "id": "task_...",
  "status": "succeeded",
  "progress": 100,
  "data": [{ "url": "https://..." }],
  "audio_url": "https://..."
}
```

| `status` | 含义 |
|----------|------|
| `queued` | 排队中 |
| `processing` | 生成中 |
| `succeeded` | 已完成，读 `audio_url` 或 `data[0].url` |
| `failed` | 失败，读 `error.message` |
| `expired` | 超时未取走结果 |

::: tip 轮询规则
轮询**不计费**。网关对上游的查询最多每 2 秒一次，更密的请求会由网关直接返回缓存状态，不会真的打到上游。
任务超过 **30 分钟**没有轮询到终态会转为 `expired`，此时预扣的费用**不退还**，所以提交后请及时轮询。
:::

::: warning 任务只对提交它的账号可见
轮询要带**提交时用的那把密钥**。换了密钥或换了账号来查，网关一律返回 `404`（错误码 `task_not_found`），
既查不到别人的任务，也不会泄漏任务是否存在。
:::

### 请求示例

```bash
# 1. 提交任务
curl -X POST https://api.jcaigc.cn/v1/music/generations \
  -H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-music-3.0",
    "prompt": "轻快的民谣流行歌曲，温暖的木吉他扫弦，钢琴点缀，男声温柔治愈，节奏舒缓",
    "lyrics": "[Verse]\n晨光落在安静的窗台\n风把昨天轻轻吹开\n\n[Chorus]\n就让阳光铺满肩膀\n让脚步跟着节拍摇晃",
    "output_format": "mp3"
  }'

# 2. 轮询结果，拿到 status=succeeded 即结束
curl https://api.jcaigc.cn/v1/music/generations/task_你的任务号 \
  -H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000"
```

## 计费说明

音乐生成**按次计费**：一次任务固定收一次价，音频时长与歌词长度都不影响金额。

| 模型 | 单价 |
|------|------|
| `minimax-music-2.0` | **0.25 元/次** |
| `minimax-music-3.0` | **1 元/次** |

* **失败任务全额退还**；`expired` 任务不退还。
* 提交时按所选模型的一次价预扣，任务完成结算时金额不变，不产生时长或字符数补差。
* 上表是网关的出厂价目表，**线上实际生效的单价以控制台「模型与定价」展示的为准**；
  价目表里没有条目的模型一律拒绝调用（HTTP 503，`error.type = model_not_priced`），不会回落到任何默认价。

## 相关模块

* [语音](/voice/) — 语音识别与语音合成
* [视频](/video/) — 文生视频与图生视频
* [大语言模型](/llm/) — 用模型批量生成歌词与风格提示词
