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

# 音乐与音效

> 使用 Venice 的异步音频 API 生成音乐和音效：选择模型、获取费用报价、将任务加入队列，并下载完成的音频。

音乐和音效的生成是异步的。选择一个模型，请求价格报价，将生成任务加入队列，然后轮询直到 Venice 返回完成的音频文件。

## 选择模型

请浏览 [音乐与音效模型](/models/music)，获取当前的模型 ID、价格、时长限制以及支持的功能。

你也可以在运行时探测模型能力：

```bash theme={"system"}
curl "https://api.venice.ai/api/v1/models?type=music" \
  -H "Authorization: Bearer $VENICE_API_KEY"
```

在设置 `duration_seconds`、`lyrics_prompt`、`force_instrumental` 或 `loop` 等可选字段前，请先检查每个模型的元数据。不受支持的字段将返回 HTTP `400` 响应。

## 生成流程

| 端点                                                               | 用途           |
| ---------------------------------------------------------------- | ------------ |
| [`POST /audio/quote`](/api-reference/endpoint/audio/quote)       | 估算生成成本（美元）   |
| [`POST /audio/queue`](/api-reference/endpoint/audio/queue)       | 启动一次音乐或音效生成  |
| [`POST /audio/retrieve`](/api-reference/endpoint/audio/retrieve) | 轮询任务并下载完成的音频 |
| [`POST /audio/complete`](/api-reference/endpoint/audio/complete) | 下载完成后删除存储的媒体 |

## 1. 获取价格报价

在生成媒体前先对请求进行报价。请使用与你打算发送到队列端点相同的模型和时长。

```bash theme={"system"}
curl https://api.venice.ai/api/v1/audio/quote \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs-music",
    "duration_seconds": 30
  }'
```

响应包含以美元计价的预估成本：

```json theme={"system"}
{
  "quote": 0.75
}
```

## 2. 将生成任务加入队列

<CodeGroup>
  ```bash 音乐 theme={"system"}
  curl https://api.venice.ai/api/v1/audio/queue \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "elevenlabs-music",
      "prompt": "Warm cinematic strings with a gentle piano melody, hopeful and spacious",
      "duration_seconds": 30,
      "force_instrumental": true
    }'
  ```

  ```bash 音效 theme={"system"}
  curl https://api.venice.ai/api/v1/audio/queue \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "elevenlabs-sound-effects-v2",
      "prompt": "Ocean waves rolling onto a pebble beach at night",
      "duration_seconds": 10
    }'
  ```
</CodeGroup>

成功的请求会返回模型和一个队列 ID：

```json theme={"system"}
{
  "model": "elevenlabs-music",
  "queue_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "QUEUED"
}
```

请同时保存 `model` 和 `queue_id`；retrieve 和 complete 端点都需要它们。

## 3. 轮询并下载

使用队列响应中的值调用 `/audio/retrieve`：

```bash theme={"system"}
curl https://api.venice.ai/api/v1/audio/retrieve \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs-music",
    "queue_id": "123e4567-e89b-12d3-a456-426614174000"
  }' \
  --output response.bin
```

检查响应的 `Content-Type`：

| Content-Type                            | 含义      | 操作              |
| --------------------------------------- | ------- | --------------- |
| `application/json`                      | 生成仍在处理中 | 读取时间字段，等待后再次轮询  |
| `audio/mpeg`、`audio/wav` 或 `audio/flac` | 生成已完成   | 使用对应扩展名保存二进制响应体 |

处理中的响应形如：

```json theme={"system"}
{
  "status": "PROCESSING",
  "average_execution_time": 20000,
  "execution_duration": 5200
}
```

两个时间字段的单位均为毫秒。

## 完整示例

以下 Python 示例将一段器乐音乐加入队列，每五秒轮询一次，并根据响应的内容类型使用相应的扩展名保存结果。

```python theme={"system"}
import os
import time
from pathlib import Path

import requests

BASE_URL = "https://api.venice.ai/api/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['VENICE_API_KEY']}",
    "Content-Type": "application/json",
}

generation = {
    "model": "elevenlabs-music",
    "prompt": "Warm cinematic strings with a gentle piano melody, hopeful and spacious",
    "duration_seconds": 30,
    "force_instrumental": True,
}

quote = requests.post(f"{BASE_URL}/audio/quote", json={
    "model": generation["model"],
    "duration_seconds": generation["duration_seconds"],
})
quote.raise_for_status()
print(f"Estimated cost: ${quote.json()['quote']:.2f}")

queued = requests.post(f"{BASE_URL}/audio/queue", headers=HEADERS, json=generation)
queued.raise_for_status()
job = queued.json()

content_type_to_extension = {
    "audio/mpeg": ".mp3",
    "audio/wav": ".wav",
    "audio/flac": ".flac",
}

while True:
    result = requests.post(
        f"{BASE_URL}/audio/retrieve",
        headers=HEADERS,
        json={"model": job["model"], "queue_id": job["queue_id"]},
    )
    result.raise_for_status()
    content_type = result.headers.get("Content-Type", "").split(";")[0]

    if content_type in content_type_to_extension:
        output = Path("generated-audio" + content_type_to_extension[content_type])
        output.write_bytes(result.content)
        print(f"Saved {output}")
        break

    status = result.json()
    print(f"Status: {status['status']}")
    time.sleep(5)

requests.post(
    f"{BASE_URL}/audio/complete",
    headers=HEADERS,
    json={"model": job["model"], "queue_id": job["queue_id"]},
).raise_for_status()
```

<Note>
  quote 端点无需鉴权，但 queue、retrieve 和 complete 请求都需要鉴权。
</Note>

## Prompt 编写建议

* 对于音乐，请描述流派、乐器、情绪、节奏、结构，以及是否需要人声。
* 对于音效，请描述声源、环境、强度、时序和聆听视角。
* 仅在所选模型支持歌词时才使用 `lyrics_prompt`。
* 仅在模型元数据显示支持时才使用 `force_instrumental` 或 `loop`。

## 相关资源

* [音乐与音效模型](/models/music)
* [Queue Audio Generation API](/api-reference/endpoint/audio/queue)
* [Retrieve Audio API](/api-reference/endpoint/audio/retrieve)