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

# Laravel AI SDK 集成 - VOICEVOX for Laravel

> 介绍如何通过 Laravel AI SDK 的 Audio Facade 使用 VOICEVOX for Laravel 的配置与用法。

## Laravel AI SDK 集成

VOICEVOX for Laravel 与 [Laravel AI SDK](https://github.com/laravel/ai) 已完成集成，可通过 `Audio` Facade 生成语音。

可用的驱动有以下两种：

* `voicevox-client`（客户端模式）
* `voicevox`（原生模式）

## 客户端驱动（`voicevox-client`）

向官方 VOICEVOX 引擎发送 HTTP 请求的模式。无需 FFI。

### 前置准备

```shell theme={null}
docker pull voicevox/voicevox_engine:cpu-latest
docker run --rm -p '127.0.0.1:50021:50021' voicevox/voicevox_engine:cpu-latest
```

### 配置

在 `config/ai.php` 中添加 `voicevox-client` provider。

```php theme={null}
'providers' => [
    'voicevox-client' => [
        'driver' => 'voicevox-client',
        'key' => env('VOICEVOX_URL', 'http://127.0.0.1:50021'),
    ],
],
```

### 使用方法

```php theme={null}
use Laravel\Ai\Audio;

$response = Audio::of('Laravelが好きなのだ')
    ->voice('ずんだもん')
    ->generate('voicevox-client');

Storage::put('talk.wav', $response->content());
```

## 原生驱动（`voicevox`）

直接调用 VOICEVOX CORE 的模式。需要 FFI。

仅能使用 `config/voicevox.php` 中 `core.vvms` 已加载的模型。

### 配置

```php theme={null}
'providers' => [
    'voicevox' => [
        'driver' => 'voicevox',
    ],
],
```

### 使用方法

```php theme={null}
use Laravel\Ai\Audio;

$response = Audio::of('ネイティブで話すのだ')
    ->voice('ずんだもん')
    ->generate('voicevox');

Storage::put('talk.wav', $response->content());
```

## 可传给 `voice()` 的值

`voice()` 可以指定以下内容：

* VOICEVOX 的 Style ID（数字字符串）
* 角色名别名（例如 `ずんだもん`、`四国めたん/ノーマル`）

### 别名列表

| 别名               | Style ID | 角色           |
| ---------------- | -------- | ------------ |
| `ずんだもん`          | 1        | ずんだもん(あまあま)  |
| `ずんだもん/あまあま`     | 1        | ずんだもん(あまあま)  |
| `ずんだもん/ノーマル`     | 3        | ずんだもん(ノーマル)  |
| `ずんだもん/セクシー`     | 5        | ずんだもん(セクシー)  |
| `ずんだもん/ツンツン`     | 7        | ずんだもん(ツンツン)  |
| `ずんだもん/ささやき`     | 22       | ずんだもん(ささやき)  |
| `ずんだもん/ヒソヒソ`     | 38       | ずんだもん(ヒソヒソ)  |
| `四国めたん/あまあま`     | 0        | 四国めたん(あまあま)  |
| `四国めたん`          | 2        | 四国めたん(ノーマル)  |
| `四国めたん/ノーマル`     | 2        | 四国めたん(ノーマル)  |
| `四国めたん/セクシー`     | 4        | 四国めたん(セクシー)  |
| `四国めたん/ツンツン`     | 6        | 四国めたん(ツンツン)  |
| `四国めたん/ヒソヒソ`     | 37       | 四国めたん(ヒソヒソ)  |
| `春日部つむぎ`         | 8        | 春日部つむぎ(ノーマル) |
| `波音リツ`           | 9        | 波音リツ(ノーマル)   |
| `雨晴はう`           | 10       | 雨晴はう(ノーマル)   |
| `玄野武宏`           | 11       | 玄野武宏(ノーマル)   |
| `白上虎太郎`          | 12       | 白上虎太郎(ノーマル)  |
| `青山龍星`           | 13       | 青山龍星(ノーマル)   |
| `冥鳴ひまり`          | 14       | 冥鳴ひまり(ノーマル)  |
| `九州そら`           | 16       | 九州そら(ノーマル)   |
| `default-female` | 10       | 雨晴はう(ノーマル)   |
| `default-male`   | 12       | 白上虎太郎(ノーマル)  |

如果省略 `voice()`，将使用 `default-female`（ID：10）。

```php theme={null}
use Laravel\Ai\Audio;

Audio::of('テスト')->voice('3')->generate('voicevox-client');
```

可用的说话人列表也可以通过 `Voicevox::speakers()` 查看。

```php theme={null}
use Revolution\Voicevox\Voicevox;

$speakers = Voicevox::speakers();
```

## Agent（KanalizerAgent）

由于原生模式没有 `enable_katakana_english`，你可以使用将英语提前转换为片假名的 `KanalizerAgent`。

```php theme={null}
use Revolution\Voicevox\Ai\Agents\KanalizerAgent;
use function Revolution\Voicevox\talk;

$kana = KanalizerAgent::make()->prompt('KanalizerAgentで英語をカタカナに変換するのだ');

$response = talk($kana['kana'] ?? $kana->text, id: 1)->generate(id: 1);

$response->storeAs('native', 'kanalizer.wav');
```

<Tip>
  基于 AI 的片假名转换并非总是准确。在实际使用中，请让人工确认生成的文本后再进行合成。
</Tip>

## 下一步阅读

<Columns cols={2}>
  <Card title="客户端：Talk" href="/zh/packages/laravel-voicevox/client-talk" icon="message-circle">
    了解客户端模式下常规 API 的调用流程。
  </Card>

  <Card title="原生：Talk" href="/zh/packages/laravel-voicevox/native-talk" icon="cpu">
    了解通过 FFI 直接合成的模式的用法。
  </Card>
</Columns>


## Related topics

- [Laravel AI SDK 集成](/zh/packages/laravel-copilot-sdk/ai-sdk.md)
- [引擎 API 集成应用开发指南 - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/app-guide.md)
- [2026 年 3 月 Laravel 更新](/zh/blog/changelog/202603.md)
- [Laravel 13 新功能汇总](/zh/blog/laravel-13-new-features.md)
- [用于 Laravel AI SDK 的 Amazon Bedrock 驱动](/zh/packages/laravel-amazon-bedrock.md)