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

# 哼唱生成

> 从哼唱或示例音频片段生成完整歌曲

## 接口

```http theme={null}
POST /api/v1/music/sample
```

**异步接口。** 返回 `task_id`，通过 [获取任务](/zh/api-reference/tasks/get) 轮询结果。

将哼唱旋律或示例音频片段（通过 [音频上传](/zh/api-reference/music/upload) 上传）作为输入，AI 根据其旋律和节奏生成完整歌曲。

## 请求参数

| 字段               | 类型      | 是否必填   | 说明                                                                 |
| ---------------- | ------- | ------ | ------------------------------------------------------------------ |
| `clip_id`        | string  | **必填** | 哼唱/示例音频的 Clip ID（来自 [音频上传](/zh/api-reference/music/upload)）        |
| `start_s`        | float   | 否      | 使用片段的起始时间（秒）。默认 `0`。                                               |
| `end_s`          | float   | 否      | 使用片段的结束时间（秒）。默认 `0`（使用完整片段）。                                       |
| `mv`             | string  | 否      | 模型版本（如 `"chirp-v3-5"`）。省略则使用默认版本。                                  |
| `callback_url`   | string  | 否      | 任务完成时的 Webhook 回调 URL。参见 [Webhook 回调](/zh/api-reference/webhooks)。 |
| `retention_days` | integer | 否      | 音频文件保存天数。默认 `7`。                                                   |

## 响应

```json theme={null}
{
  "code": 0,
  "message": "ok",
  "request_id": "req-1710000000000",
  "data": {
    "task_id": "64f3a1b2c8d9e0f1a2b3c4d5",
    "status": "queuing"
  }
}
```

## 使用流程

1. 录制哼唱旋律或准备示例音频
2. 通过 [音频上传](/zh/api-reference/music/upload) 上传 → 获取 `clipId`
3. 调用本接口，传入 `clipId` → 获取 `task_id`
4. 轮询 [获取任务](/zh/api-reference/tasks/get) 直到 `status = "completed"`
5. 通过 `results[].audio_url` 获取生成的歌曲

## 示例

```bash theme={null}
# 1. 上传哼唱音频
CLIP_ID=$(curl -s -X POST https://api.example.com/api/v1/music/upload \
  -H "Authorization: Bearer sk-mm-your-key" \
  -H "Content-Type: application/json" \
  -d '{"audio_url":"https://example.com/my-humming.mp3"}' \
  | jq -r '.data.clipId')

# 2. 基于哼唱生成歌曲
curl -X POST https://api.example.com/api/v1/music/sample \
  -H "Authorization: Bearer sk-mm-your-key" \
  -H "Content-Type: application/json" \
  -d "{
    \"clip_id\": \"$CLIP_ID\",
    \"start_s\": 0,
    \"end_s\": 20
  }"
```