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

# Laravel AI SDK 연동 - VOICEVOX for Laravel

> VOICEVOX for Laravel을 Laravel AI SDK의 Audio 파사드에서 사용하기 위한 설정과 사용법을 설명합니다.

## Laravel AI SDK 연동

VOICEVOX for Laravel은 [Laravel AI SDK](https://github.com/laravel/ai)와 통합되어 있어, `Audio` 파사드에서 음성 생성을 할 수 있습니다.

사용 가능한 드라이버는 다음 두 가지입니다.

* `voicevox-client` (클라이언트 모드)
* `voicevox` (네이티브 모드)

## 클라이언트 드라이버 (`voicevox-client`)

공식 VOICEVOX 엔진에 HTTP 요청을 보내는 모드입니다. FFI가 필요 없습니다.

### 사전 준비

```shell theme={null}
docker pull voicevox/voicevox_engine:cpu-latest
docker run --rm -p '127.0.0.1:50021:50021' voicevox/voicevox_engine:cpu-latest
```

### 설정

`config/ai.php`에 `voicevox-client` 프로바이더를 추가합니다.

```php theme={null}
'providers' => [
    'voicevox-client' => [
        'driver' => 'voicevox-client',
        'key' => env('VOICEVOX_URL', 'http://127.0.0.1:50021'),
    ],
],
```

### 사용법

```php theme={null}
use Laravel\Ai\Audio;

$response = Audio::of('Laravel이 좋다이다')
    ->voice('ずんだもん')
    ->generate('voicevox-client');

Storage::put('talk.wav', $response->content());
```

## 네이티브 드라이버 (`voicevox`)

VOICEVOX CORE를 직접 호출하는 모드입니다. FFI가 필요합니다.

`config/voicevox.php`의 `core.vvms`에 로드된 모델만 사용할 수 있습니다.

### 설정

```php theme={null}
'providers' => [
    'voicevox' => [
        'driver' => 'voicevox',
    ],
],
```

### 사용법

```php theme={null}
use Laravel\Ai\Audio;

$response = Audio::of('네이티브로 말하는 것이다')
    ->voice('ずんだもん')
    ->generate('voicevox');

Storage::put('talk.wav', $response->content());
```

## `voice()`에 지정할 수 있는 값

`voice()`에는 다음을 지정할 수 있습니다.

* VOICEVOX의 스타일 ID (숫자 문자열)
* 캐릭터명 별칭 (예: `ずんだもん`, `四国めたん/ノーマル`)

### 별칭 목록

| 별칭               | 스타일 ID | 캐릭터          |
| ---------------- | ------ | ------------ |
| `ずんだもん`          | 1      | ずんだもん(あまあま)  |
| `ずんだもん/あまあま`     | 1      | ずんだもん(あまあま)  |
| `ずんだもん/ノーマル`     | 3      | ずんだもん(ノーマル)  |
| `ずんだもん/セクシー`     | 5      | ずんだもん(セクシー)  |
| `ずんだもん/ツンツン`     | 7      | ずんだもん(ツンツン)  |
| `ずんだもん/ささやき`     | 22     | ずんだもん(ささやき)  |
| `ずんだもん/ヒソヒソ`     | 38     | ずんだもん(ヒソヒソ)  |
| `四国めたん/あまあま`     | 0      | 四国めたん(あまあま)  |
| `四国めたん`          | 2      | 四国めたん(ノーマル)  |
| `四国めたん/ノーマル`     | 2      | 四国めたん(ノーマル)  |
| `四国めたん/セクシー`     | 4      | 四国めたん(セクシー)  |
| `四国めたん/ツンツン`     | 6      | 四国めたん(ツンツン)  |
| `四国めたん/ヒソヒソ`     | 37     | 四国めたん(ヒソヒソ)  |
| `春日部つむぎ`         | 8      | 春日部つむぎ(ノーマル) |
| `波音リツ`           | 9      | 波音リツ(ノーマル)   |
| `雨晴はう`           | 10     | 雨晴はう(ノーマル)   |
| `玄野武宏`           | 11     | 玄野武宏(ノーマル)   |
| `白上虎太郎`          | 12     | 白上虎太郎(ノーマル)  |
| `青山龍星`           | 13     | 青山龍星(ノーマル)   |
| `冥鳴ひまり`          | 14     | 冥鳴ひまり(ノーマル)  |
| `九州そら`           | 16     | 九州そら(ノーマル)   |
| `default-female` | 10     | 雨晴はう(ノーマル)   |
| `default-male`   | 12     | 白上虎太郎(ノーマル)  |

`voice()`를 생략한 경우에는 `default-female` (ID: 10)이 사용됩니다.

```php theme={null}
use Laravel\Ai\Audio;

Audio::of('테스트')->voice('3')->generate('voicevox-client');
```

사용 가능한 스피커 목록은 `Voicevox::speakers()`에서도 확인할 수 있습니다.

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

$speakers = Voicevox::speakers();
```

## 에이전트 (KanalizerAgent)

네이티브 모드에서는 `enable_katakana_english`가 없기 때문에, 영어를 사전에 카타카나로 변환하는 `KanalizerAgent`를 사용할 수 있습니다.

```php theme={null}
use Revolution\Voicevox\Ai\Agents\KanalizerAgent;
use function Revolution\Voicevox\talk;

$kana = KanalizerAgent::make()->prompt('KanalizerAgent로 영어를 카타카나로 변환하는 것이다');

$response = talk($kana['kana'] ?? $kana->text, id: 1)->generate(id: 1);

$response->storeAs('native', 'kanalizer.wav');
```

<Tip>
  AI에 의한 카타카나 변환은 항상 정확하다고는 할 수 없습니다. 실제 운영에서는 생성 텍스트를 사람이 확인한 뒤 합성하세요.
</Tip>

## 다음에 읽어볼 페이지

<Columns cols={2}>
  <Card title="클라이언트: 토크" href="/ko/packages/laravel-voicevox/client-talk" icon="message-circle">
    클라이언트 모드의 일반 API 흐름을 확인합니다.
  </Card>

  <Card title="네이티브: 토크" href="/ko/packages/laravel-voicevox/native-talk" icon="cpu">
    FFI로 직접 합성하는 모드의 사용법을 확인합니다.
  </Card>
</Columns>


## Related topics

- [Laravel AI SDK 연동](/ko/packages/laravel-copilot-sdk/ai-sdk.md)
- [엔진 API 연동 앱 개발 가이드 - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/app-guide.md)
- [Laravel AI SDK](/ko/ai-sdk.md)
- [Laravel AI SDK용 Amazon Bedrock 드라이버](/ko/packages/laravel-amazon-bedrock.md)
- [시작하기 - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/getting-started.md)