> ## 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 셋업">
    [설치와 설정](/ko/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="/ko/packages/laravel-voicevox/engine-song" icon="music">
    `sing_frame_audio_query`와 `frame_synthesis` 사용법을 확인합니다.
  </Card>

  <Card title="Laravel AI SDK 연동" href="/ko/packages/laravel-voicevox/ai-sdk" icon="sparkles">
    `Audio` 파사드에서 VOICEVOX를 사용하는 설정을 확인합니다.
  </Card>
</Columns>


## Related topics

- [클라이언트 모드: 토크 (텍스트 음성 합성) - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/client-talk.md)
- [네이티브 모드: 토크 (텍스트 음성 합성) - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/native-talk.md)
- [엔진 API 모드: 송 (노래 음성 합성) - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/engine-song.md)
- [VOICEVOX for Laravel](/ko/packages/laravel-voicevox/index.md)
- [클라이언트 모드: 송 (노래 음성 합성) - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/client-song.md)