> ## 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 モード：トーク（テキスト音声合成） - VOICEVOX for Laravel

> Laravel アプリに VOICEVOX エンジン互換 HTTP API を組み込み、公式エンジンと同じトークエンドポイントを使う方法を説明します。

## エンジン API モードとは

エンジン API モードは、公式 VOICEVOX エンジン互換の HTTP API を Laravel アプリ内で提供します。

`php artisan serve --port=50513` でアプリを起動するだけで、`/audio_query` や `/synthesis` をそのまま利用できます。

## 事前準備

<Steps>
  <Step title="VOICEVOX Core for PHP をセットアップする">
    [インストールと設定](/jp/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>

## トーク音声を生成する

### 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 の有効・無効とフォールバック

```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` のような未実装エンドポイントは、公式エンジンへフォールバックできます。

<Info>
  フォールバックを使う場合は、`VOICEVOX_ENGINE_FALLBACK_URL` 側で公式エンジンを起動してください。
</Info>

## トーク関連の対応状況

| エンドポイント                       | Laravel 版 | フォールバック | 備考                            |
| ----------------------------- | --------- | ------- | ----------------------------- |
| `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` | ❌         | ✅       | フォールバックのみ                     |
| `POST /multi_synthesis`       | ❌         | ✅       | フォールバックのみ                     |

## 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`           | スタイル 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: ソング" href="/jp/packages/laravel-voicevox/engine-song" icon="music">
    `sing_frame_audio_query` と `frame_synthesis` の使い方を確認します。
  </Card>

  <Card title="Laravel AI SDK連携" href="/jp/packages/laravel-voicevox/ai-sdk" icon="sparkles">
    `Audio` ファサードから VOICEVOX を使う設定を確認します。
  </Card>
</Columns>