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

# Engine API 模式:Talk(文字語音合成)- VOICEVOX for Laravel

> 說明如何在 Laravel 應用中內建 VOICEVOX Engine 相容 HTTP API,使用與官方引擎相同的 Talk endpoint。

## 什麼是 Engine API 模式

Engine API 模式會在 Laravel 應用內提供官方 VOICEVOX 引擎相容的 HTTP API。

只要以 `php artisan serve --port=50513` 啟動應用,就能直接使用 `/audio_query` 或 `/synthesis`。

## 事前準備

<Steps>
  <Step title="設定 VOICEVOX Core for PHP">
    依 [安裝與設定](/zh-TW/packages/laravel-voicevox/installation) 準備好 `voicevox-core-php` 與核心 library。
  </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` 啟動。

### 關於 port 50513

官方 VOICEVOX 引擎的預設 port 為 50021。為了讓 Laravel 版引擎與官方引擎能同時啟動,預設 port 定為 50513。

因為只是加上 `--port=50513` 啟動,使用 `--port=8000` 等其他 port 亦可。

<Info>
  官方引擎在 port 被佔用時,會自動調整到 50022 之後的空閒 port 啟動。`php artisan serve` 若不指定 `--port` 也會自動調整到 8001 之後,但指定 `--port` 時,若該 port 被佔用會啟動失敗。建議指定不易與其他服務衝突的固定 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 Client 使用

可將 Laravel 版引擎作為 Client 模式的連線目標。

```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');
```

## Engine 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` 等未實作的 endpoint 可 fallback 至官方引擎。

<Info>
  使用 fallback 時,請於 `VOICEVOX_ENGINE_FALLBACK_URL` 端啟動官方引擎。
</Info>

## Talk 相關的對應狀況

| Endpoint                      | 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 endpoint

`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 voice 名稱(`alloy`、`shimmer` 等) |
| `speed`           | 播放速度。作為 `speedScale` 套用(0.25\~4.0,省略為 1.0)                               |
| `response_format` | 一律以 wav 回傳。指定值會被忽略                                                       |
| 其他參數              | 會被忽略                                                                     |

<Info>
  OpenAI voice 名稱(`alloy`、`shimmer` 等)為臨時對應。因為沒有定義 OpenAI 各 voice 的音色對應到哪個 VOICEVOX 角色,基於相容性目的暫時對應。建議使用 VOICEVOX 角色的別名(`ずんだもん`、`四国めたん/ノーマル` 等)。
</Info>

## 下一步閱讀

<Columns cols={2}>
  <Card title="Engine API: Song" href="/zh-TW/packages/laravel-voicevox/engine-song" icon="music">
    確認 `sing_frame_audio_query` 與 `frame_synthesis` 的用法。
  </Card>

  <Card title="Laravel AI SDK 整合" href="/zh-TW/packages/laravel-voicevox/ai-sdk" icon="sparkles">
    確認從 `Audio` Facade 使用 VOICEVOX 的設定。
  </Card>
</Columns>


## Related topics

- [Native 模式:Talk(文字語音合成)- VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/native-talk.md)
- [Client 模式:Talk(文字語音合成)- VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/client-talk.md)
- [Engine API 模式:Song(歌聲語音合成)- VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/engine-song.md)
- [Client 模式:Song(歌聲語音合成)- VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/client-song.md)
- [Native 模式:Song(歌聲語音合成)- VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/native-song.md)