> ## 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 Mode: Talk (Text-to-Speech) - VOICEVOX for Laravel

> Embed a VOICEVOX-engine-compatible HTTP API in your Laravel app and use standard talk endpoints.

## What is engine API mode

Engine API mode provides a VOICEVOX Engine-compatible HTTP API inside your Laravel app.

Start your app with `php artisan serve --port=50513`, then use endpoints like `/audio_query` and `/synthesis` directly.

## Prerequisites

<Steps>
  <Step title="Set up VOICEVOX Core for PHP">
    Follow [Installation and Configuration](/en/packages/laravel-voicevox/installation) to prepare `voicevox-core-php` and core libraries.
  </Step>

  <Step title="Configure environment and enable FFI">
    ```dotenv theme={null}
    VOICEVOX_CORE_PATH=/path/to/voicevox_core/
    ```

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

  <Step title="Install character resources">
    ```shell theme={null}
    php artisan voicevox:install
    ```
  </Step>
</Steps>

## Start Laravel engine

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

Default URL is `http://127.0.0.1:50513`.

### About port 50513

The official VOICEVOX engine uses port 50021 by default. Port 50513 is chosen so you can run the Laravel engine and the official engine at the same time.

You are free to use any other port — just pass a different `--port` value, such as `--port=8000`.

<Info>
  The official engine automatically picks the next available port (50022, 50023, …) when 50021 is busy. `php artisan serve` does the same when no `--port` is given (8001, 8002, …), but it fails to start if the specified port is already in use. Choose a fixed port that is unlikely to conflict with other services. Port 50513 is one example chosen to avoid collisions with both the official VOICEVOX engine (50021) and common Laravel ports.
</Info>

## Generate talk audio

### 1. Create `audio_query`

```shell theme={null}
curl -s -X POST "http://127.0.0.1:50513/audio_query?speaker=1&text=I%20love%20Laravel" \
  -H "Content-Type: application/json" \
  > audio_query.json
```

### 2. Synthesize with `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
```

## Use from Laravel client mode

Point client-mode URL to the Laravel engine API.

```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('I love Laravel', id: 1)
    ->generate(id: 1);

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

## Enable/disable and fallback

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

Unsupported endpoints like `cancellable_synthesis` and `multi_synthesis` can fall back to official engine.

<Info>
  If you rely on fallback, run official VOICEVOX engine at `VOICEVOX_ENGINE_FALLBACK_URL`.
</Info>

## Talk endpoint support

| Endpoint                      | Laravel engine | Fallback | Notes                                 |
| ----------------------------- | -------------- | -------- | ------------------------------------- |
| `POST /audio_query`           | ✅              | ✅        | `enable_katakana_english` unsupported |
| `POST /accent_phrases`        | ✅              | ✅        | `enable_katakana_english` unsupported |
| `POST /synthesis`             | ✅              | ✅        |                                       |
| `POST /mora_data`             | ✅              | ✅        |                                       |
| `POST /mora_length`           | ✅              | ✅        |                                       |
| `POST /mora_pitch`            | ✅              | ✅        |                                       |
| `GET /speakers`               | ✅              | ✅        |                                       |
| `GET /speaker_info`           | ✅              | ✅        | Requires resource install             |
| `POST /cancellable_synthesis` | ❌              | ✅        | Fallback only                         |
| `POST /multi_synthesis`       | ❌              | ✅        | Fallback only                         |

## OpenAI-compatible TTS endpoint

`POST /v1/audio/speech` accepts the same request format as the OpenAI speech API. Changing the Base URL is all you need to connect any OpenAI-compatible tool — including Laravel AI SDK.

```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": "I love Laravel",
    "voice": "shimmer"
  }' \
  > talk.wav
```

### Parameters

| Parameter         | Description                                                                                                   |
| ----------------- | ------------------------------------------------------------------------------------------------------------- |
| `input`           | Text to synthesize (max 4096 characters)                                                                      |
| `voice`           | Style ID (integer), character alias (`ずんだもん`, `四国めたん`, etc.), or OpenAI voice name (`alloy`, `shimmer`, etc.) |
| `speed`           | Playback speed applied as `speedScale` (0.25–4.0, default 1.0)                                                |
| `response_format` | Always returns wav. The value is ignored                                                                      |
| Other parameters  | Ignored                                                                                                       |

<Info>
  OpenAI voice names (`alloy`, `shimmer`, etc.) are provisional mappings. There is no authoritative definition of how each OpenAI voice should correspond to a VOICEVOX character, so these are convenience assignments for compatibility. Using VOICEVOX character aliases (`ずんだもん`, `四国めたん/ノーマル`, etc.) is recommended.
</Info>

## Next pages

<Columns cols={2}>
  <Card title="Engine API: Song" href="/en/packages/laravel-voicevox/engine-song" icon="music">
    Use `sing_frame_audio_query` and `frame_synthesis` endpoints.
  </Card>

  <Card title="Laravel AI SDK Integration" href="/en/packages/laravel-voicevox/ai-sdk" icon="sparkles">
    Configure VOICEVOX with `Audio` facade workflows.
  </Card>
</Columns>