> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aisonar.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 音乐生成

> 创建音乐或歌词任务，轮询最终音频，并安全存储用户可见的音乐输出。

音乐生成是异步的。 `POST /v1/music/generations` 创建一个公共的 AI Sonar 任务并返回 `id` / `task_id`、`status`，通常还有 `poll_url`。您的应用程序应存储该任务标识，显示进度，并轮询直到达到终态。

## 选择工作流程

| 工作流程    | 关键字段                                                      | 备注                    |
| ------- | --------------------------------------------------------- | --------------------- |
| 完整歌曲或伴奏 | `model`、`mv`、`prompt`、可选 `title`、`tags`、`action: "MUSIC"` | 当用户期望最终音频时使用          |
| 仅歌词     | `model`、`prompt`、`action: "LYRICS"`                       | 仅与公开提供歌词生成的模型一起使用     |
| 继续现有片段  | `continue_clip_id`、可选 `continue_at`                       | 在提供继续之前存储之前的公共片段/任务标识 |

在发布硬编码模型列表之前查询当前模型目录：

```bash theme={null}
curl "https://api.aisonar.dev/v1/models?recommended_for=music" \
  -H "Authorization: Bearer sk-your-api-key"
```

当前公共示例使用 `suno_music` 进行音乐生成，并在 `mv` 中传入 `chirp-v4` 等官方 Suno 模型版本。对于仅歌词的流程，发送 `action: "LYRICS"` 与模型说明文档中包含歌词生成的模型，并省略 `mv`。将模型 ID 视为公共 AI Sonar ID，而不是保证供应商特定字段是公共契约字段。

## 创建音乐任务

```bash theme={null}
curl https://api.aisonar.dev/v1/music/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno_music",
    "mv": "chirp-v4",
    "prompt": "一首充满活力的合成流行曲，伴有温暖的声乐和干净的合唱",
    "title": "晨间静电",
    "tags": "合成流行，充满活力",
    "action": "MUSIC"
  }'
```

保持提示、标题和标签对用户可见且安全存储。不要在任何提示字段中放置 API 密钥、私有 URL 或私有调试信息。

## 轮询完成状态

首先使用 `poll_url`。如果您的客户端需要固定路由，请使用返回的 `id` 或 `task_id` 调用 `GET /v1/tasks/{id}`。

```bash theme={null}
curl "https://api.aisonar.dev/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"
```

### 响应结构

创建接口返回的是可轮询的任务记录，不是最终音频：

```json theme={null}
{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "created": 1706000000,
  "model": "suno_music"
}
```

轮询到完成后，响应可以包含最终媒体字段：

```json theme={null}
{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "completed",
  "audio_url": "https://cdn.example.com/music/abc123.mp3",
  "video_url": "https://cdn.example.com/music/abc123.mp4",
  "stream_audio_url": "https://cdn.example.com/music/abc123-stream.mp3",
  "image_url": "https://cdn.example.com/music/cover.jpg",
  "title": "晨间静电",
  "lyrics": "[Verse 1]\n..."
}
```

最终媒体字段只会在 `status` 为 `completed` 后出现。失败任务会返回 `status: "failed"`，并携带 `error`。

预期的公共状态为 `pending`、`processing`、`completed` 和 `failed`。完成的音乐任务可以包括 `audio_url`、`video_url`、`title`、`lyrics` 和标准化元数据。将最终 URL 存储在您自己的数据库中，以便用户可以在不重新生成的情况下重新打开结果。

## 用户界面和状态处理

* 在任务创建后立即显示待处理状态。
* 对于长任务每 `5-10s` 轮询一次，然后在 `completed` 或 `failed` 时停止。
* 在任务 `completed` 且存在 `audio_url` 之前，不要显示最终播放器。
* 对于仅歌词的任务，将文本输出与音频任务分开渲染，以便用户理解他们所购买的内容。
* 刷新时，从存储的 `task_id` 恢复，而不是创建新任务。

## 计费和对账

音乐任务可以在创建时保留估计金额，并在知道终态后结算。请保存 `request_id`、`task_id`、模型、端点和可能出现的 `billing_transaction_id`，便于支持团队追踪请求，而不是依赖供应商任务 ID。

## 常见错误

| 症状         | 可能原因                      | 修复                         |
| ---------- | ------------------------- | -------------------------- |
| 任务创建但没有播放器 | 任务仍在待处理或完成但没有 `audio_url` | 持续轮询直到终态，然后将缺失输出处理为失败的用户任务 |
| 刷新后重复歌曲    | 用户界面重新创建了任务而不是恢复          | 持久化并重用 `task_id`           |
| 歌词任务返回没有音频 | `action: "LYRICS"` 仅为文本   | 将歌词和音乐用户界面路径分开             |
| 不支持的参数     | 字段不在模型公共契约中               | 删除供应商特定字段或选择文档中包含它们的模型     |

## API 参考

| 主题     | 参考                                                 |
| ------ | -------------------------------------------------- |
| 创建音乐   | [创建音乐](/zh/api-reference/music/create-music)       |
| 获取音乐状态 | [获取音乐状态](/zh/api-reference/music/get-music-status) |
| 获取任务状态 | [获取任务状态](/zh/api-reference/tasks/get-task-status)  |
| 列出模型   | [列出模型](/zh/api-reference/models/list-models)       |
| 计费与定价  | [计费与定价](/zh/guides/billing)                        |