> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 音效快速入门

本指南将介绍如何使用 Sound Effects API 生成音效。

> **Tip**
>
> 使用 [ElevenLabs sound-effects skill](https://github.com/elevenlabs/skills/tree/main/sound-effects)，通过 AI 编程助手生成音效：
>
> ```bash
> npx skills add elevenlabs/skills --skill sound-effects
> ```

## 使用 Sound Effects API

#### 创建 API 密钥

[在控制台中创建 API 密钥](https://elevenlabs.io/app/api/api-keys)，用于安全地[访问 API](/docs/zh/api-reference/authentication)。

将密钥作为受管理的机密信息存储，并根据偏好，通过 `.env` 文件将其作为环境变量传递给 SDK，或直接写入应用配置。

**`.env`**

```js title=".env"
ELEVENLABS_API_KEY=<your_api_key_here>
```

#### 安装 SDK

#### SDK

我们还会使用 `dotenv` 库从环境变量加载 API 密钥。

```python
pip install elevenlabs
pip install python-dotenv
```

```typescript
npm install @elevenlabs/elevenlabs-js
npm install dotenv
```

#### CLI

安装 ElevenLabs CLI。推荐使用 Homebrew（macOS）和 Scoop（Windows）。

**`Homebrew（macOS）`**

```bash title="Homebrew（macOS）"
brew install elevenlabs/tap/elevenlabs
```

**`Scoop（Windows）`**

```powershell title="Scoop（Windows）"
scoop bucket add elevenlabs https://github.com/elevenlabs/scoop-bucket
scoop install elevenlabs
```

**`npm`**

```bash title="npm"
npm install -g @elevenlabs/cli
```

**`curl`**

```bash title="curl"
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/elevenlabs/cli/releases/latest/download/elevenlabs-cli-installer.sh | sh
```

> **Tip**
>
> 正在使用 AI 编程助手？在项目中运行 `elevenlabs generate-skills`，即可将每个命令组的
> `SKILL.md` 写入 `skills/`，无需粘贴文档，助手就能了解 CLI 的完整功能。使用 `--output-dir`
> 可将其放到其他位置。该命令会读取 CLI 内置的 API 定义，因此无需 API 密钥且可离线运行——还能始终与已安装的 CLI 版本保持同步。

然后进行身份验证——这会打开浏览器以授权 CLI：

```bash
elevenlabs auth login
```

> **Note**
>
> 如需通过扬声器播放音频，系统可能会提示你安装 [MPV](https://mpv.io/)
> 和/或 [ffmpeg](https://ffmpeg.org/)。

#### 发起 API 请求

#### SDK

根据所选语言，新建名为 `example.py` 或 `example.mts` 的文件，并添加以下代码：

```python maxLines=0
# example.py
import os
from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs
from elevenlabs.play import play

load_dotenv()

elevenlabs = ElevenLabs(
  api_key=os.getenv("ELEVENLABS_API_KEY"),
)
audio = elevenlabs.text_to_sound_effects.convert(text="Cinematic Braam, Horror")

play(audio)
```

```typescript
// example.mts
import { ElevenLabsClient, play } from "@elevenlabs/elevenlabs-js";
import "dotenv/config";

const elevenlabs = new ElevenLabsClient();

const audio = await elevenlabs.textToSoundEffects.convert({
  text: "Cinematic Braam, Horror",
});

await play(audio);
```

然后运行：

```python
python example.py
```

```typescript
npx tsx example.mts
```

你应该会听到生成的音效通过扬声器播放。

#### CLI

生成音效并保存到文件：

```bash
elevenlabs text-to-sound-effects convert \
  --text "Cinematic Braam, Horror" \
  --output sound-effect.mp3
```

打开 `sound-effect.mp3` 即可试听结果。

## 后续步骤

#### [音效概览](/docs/zh/overview/capabilities/sound-effects)

了解音效生成、支持的格式和使用场景

#### [文本转语音](/docs/zh/eleven-api/quickstart)

使用文本转语音 API 根据文本生成语音音频

#### [API 参考文档](/docs/zh/api-reference/text-to-sound-effects/convert)

查看所有 Sound Effects 参数和响应格式