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

# 引擎 API 模式：Talk（文本语音合成） - VOICEVOX for Laravel

> 介绍如何在 Laravel 应用中嵌入 VOICEVOX 引擎兼容的 HTTP API，并使用与官方引擎相同的 Talk 端点。

## 什么是引擎 API 模式

引擎 API 模式在 Laravel 应用内提供与官方 VOICEVOX 引擎兼容的 HTTP API。

只需通过 `php artisan serve --port=50513` 启动应用，就可以直接使用 `/audio_query`、`/synthesis` 等端点。

## 前置准备

<Steps>
  <Step title="配置 VOICEVOX Core for PHP">
    按照 [安装与配置](/zh/packages/laravel-voicevox/installation) 的步骤准备好 `voicevox-core-php` 与核心库。
  </Step>

  <Step title="配置环境变量并启用 FFI">
    ```dotenv theme={null}
    VOICEVOX_CORE_PATH=/path/to/voicevox_core/
    ```

    ```ini theme={null}
    ffi.enable=true
    ```
  </Step>

  <Step title="安装角色信息资源">
    ```shell theme={null}
    php artisan voicevox:install
    ```
  </Step>
</Steps>

## 启动 Laravel 版引擎

```shell theme={null}
php artisan serve --port=50513
```

默认会在 `http://127.0.0.1:50513` 启动。

### 关于端口 50513

官方 VOICEVOX 引擎的默认端口是 50021。为了让 Laravel 版引擎与官方引擎能够同时运行，我们将默认端口定为 50513。

我们只是通过 `--port=50513` 启动，因此使用 `--port=8000` 等其他端口也没问题。

<Info>
  官方引擎在端口被占用时会自动调整到 50022 之后的空闲端口再启动。`php artisan serve` 不指定 `--port` 时也会自动调整到 8001 之后，但一旦指定了 `--port` 而该端口被占用则会启动失败。建议固定使用与其他服务不易冲突的端口，50513 就是其中一个例子。
</Info>

## 生成 Talk 音频

### 1. 创建 `audio_query`

```shell theme={null}
curl -s -X POST "http://127.0.0.1:50513/audio_query?speaker=1&text=ララベルが好きなのだ" \
  -H "Content-Type: application/json" \
  > audio_query.json
```

### 2. 通过 `synthesis` 合成音频

```shell theme={null}
curl -s -X POST "http://127.0.0.1:50513/synthesis?speaker=1" \
  -H "Content-Type: application/json" \
  -d @audio_query.json \
  > talk.wav
```

## 从 Laravel 客户端使用

可以将 Laravel 版引擎作为客户端模式的连接目标。

```php theme={null}
// config/voicevox.php
'client' => [
    'url' => env('VOICEVOX_URL', 'http://127.0.0.1:50513'),
],
```

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

$response = Voicevox::talk('ララベルが好きなのだ', id: 1)
    ->generate(id: 1);

$response->storeAs('engine', 'talk.wav');
```

## 引擎 API 的启用/禁用与 Fallback

```php theme={null}
'engine' => [
    'disabled' => env('VOICEVOX_ENGINE_DISABLED', false),
    'fallback_url' => env('VOICEVOX_ENGINE_FALLBACK_URL', 'http://127.0.0.1:50021'),
],
```

对于 `cancellable_synthesis`、`multi_synthesis` 等未实现的端点，可以 fallback 到官方引擎。

<Info>
  使用 fallback 时，请在 `VOICEVOX_ENGINE_FALLBACK_URL` 侧启动官方引擎。
</Info>

## Talk 相关端点的支持情况

| 端点                            | Laravel 版 | Fallback | 备注                            |
| ----------------------------- | --------- | -------- | ----------------------------- |
| `POST /audio_query`           | ✅         | ✅        | 不支持 `enable_katakana_english` |
| `POST /accent_phrases`        | ✅         | ✅        | 不支持 `enable_katakana_english` |
| `POST /synthesis`             | ✅         | ✅        |                               |
| `POST /mora_data`             | ✅         | ✅        |                               |
| `POST /mora_length`           | ✅         | ✅        |                               |
| `POST /mora_pitch`            | ✅         | ✅        |                               |
| `GET /speakers`               | ✅         | ✅        |                               |
| `GET /speaker_info`           | ✅         | ✅        | 需要安装资源                        |
| `POST /cancellable_synthesis` | ❌         | ✅        | 仅 fallback                    |
| `POST /multi_synthesis`       | ❌         | ✅        | 仅 fallback                    |

## OpenAI 兼容的 TTS 端点

`POST /v1/audio/speech` 接受与 OpenAI 语音合成 API 相同格式的请求。只需更改 Base URL，即可从 Laravel AI SDK 以及众多兼容 OpenAI API 的工具调用。

```shell theme={null}
curl -s -X POST "http://127.0.0.1:50513/v1/audio/speech" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "voicevox",
    "input": "ララベルが好きなのだ",
    "voice": "ずんだもん"
  }' \
  > talk.wav
```

### 参数

| 参数                | 说明                                                                  |
| ----------------- | ------------------------------------------------------------------- |
| `input`           | 要朗读的文本（最多 4096 字符）                                                  |
| `voice`           | Style ID（数值）、别名（`ずんだもん`、`四国めたん` 等）或 OpenAI 音色名（`alloy`、`shimmer` 等） |
| `speed`           | 播放速度。作为 `speedScale` 应用（0.25～4.0，省略时为 1.0）                          |
| `response_format` | 始终以 wav 返回。指定的值会被忽略                                                 |
| 其他参数              | 会被忽略                                                                |

<Info>
  OpenAI 音色名（`alloy`、`shimmer` 等）是临时映射。由于 OpenAI 各音色的声音特质与 VOICEVOX 角色之间不存在正式对应定义，这里只是为了兼容性做了权宜映射。建议使用 VOICEVOX 角色的别名（如 `ずんだもん`、`四国めたん/ノーマル` 等）。
</Info>

## 下一步阅读

<Columns cols={2}>
  <Card title="引擎 API：Song" href="/zh/packages/laravel-voicevox/engine-song" icon="music">
    了解 `sing_frame_audio_query` 与 `frame_synthesis` 的用法。
  </Card>

  <Card title="Laravel AI SDK 集成" href="/zh/packages/laravel-voicevox/ai-sdk" icon="sparkles">
    了解从 `Audio` Facade 使用 VOICEVOX 的配置。
  </Card>
</Columns>


## Related topics

- [客户端模式：Talk（文本语音合成） - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/client-talk.md)
- [原生模式：Talk（文本语音合成） - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/native-talk.md)
- [引擎 API 模式：Song（歌声合成） - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/engine-song.md)
- [VOICEVOX for Laravel](/zh/packages/laravel-voicevox/index.md)
- [安装与配置 - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/installation.md)