엔진 API 모드: 토크 (텍스트 음성 합성) - VOICEVOX for Laravel

Laravel 앱에 VOICEVOX 엔진 호환 HTTP API를 통합하고, 공식 엔진과 동일한 토크 엔드포인트를 사용하는 방법을 설명합니다.

​

엔진 API 모드란

엔진 API 모드는 공식 VOICEVOX 엔진 호환의 HTTP API를 Laravel 앱 내에서 제공합니다.

php artisan serve --port=50513으로 앱을 실행하기만 하면 /audio_query나 /synthesis를 그대로 이용할 수 있습니다.

​

사전 준비

1. VOICEVOX Core for PHP 셋업

   설치와 설정 절차로 voicevox-core-php와 코어 라이브러리를 준비합니다.

2. 환경 변수와 FFI 활성화

   VOICEVOX_CORE_PATH=/path/to/voicevox_core/
   

   ffi.enable=true
   
3. 캐릭터 정보 리소스 설치

   php artisan voicevox:install
   

​

Laravel판 엔진 실행

php artisan serve --port=50513

기본적으로 http://127.0.0.1:50513에서 실행됩니다.

​

포트 50513에 대해

공식 VOICEVOX 엔진의 기본 포트는 50021입니다. Laravel판 엔진과 공식 엔진을 동시에 실행할 수 있도록 기본 포트를 50513으로 정하고 있습니다.

--port=50513을 붙여 실행할 뿐이므로, --port=8000 등 다른 포트를 사용해도 상관없습니다.

공식 엔진은 포트가 사용 중일 경우 50022 이후의 비어 있는 포트에 자동 조정하여 실행됩니다. php artisan serve에서도 --port를 지정하지 않은 경우에는 8001 이후로 자동 조정되지만, --port를 지정한 상태에서 포트가 사용 중이면 실행에 실패합니다. 다른 서비스와 충돌이 적은 포트를 고정으로 지정하는 것을 권장합니다. 50513은 그중 하나의 예입니다.

​

토크 음성 생성

​

1. audio_query 생성

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로 음성 합성

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판 엔진을 클라이언트 모드의 연결 대상으로 사용할 수 있습니다.

// config/voicevox.php
'client' => [
    'url' => env('VOICEVOX_URL', 'http://127.0.0.1:50513'),
],

use Revolution\Voicevox\Voicevox;

$response = Voicevox::talk('ララベルが好きなのだ', id: 1)
    ->generate(id: 1);

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

​

엔진 API의 유효·무효화와 폴백

'engine' => [
    'disabled' => env('VOICEVOX_ENGINE_DISABLED', false),
    'fallback_url' => env('VOICEVOX_ENGINE_FALLBACK_URL', 'http://127.0.0.1:50021'),
],

cancellable_synthesis나 multi_synthesis와 같은 미구현 엔드포인트는 공식 엔진으로 폴백할 수 있습니다.

폴백을 사용하는 경우 VOICEVOX_ENGINE_FALLBACK_URL 측에서 공식 엔진을 실행해 두세요.

​

토크 관련 대응 현황

엔드포인트	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 대응의 많은 도구에서 이용할 수 있습니다.

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로 반환합니다. 지정 값은 무시됩니다
기타 파라미터	무시됩니다

OpenAI 보이스명(alloy, shimmer 등)은 임시 할당입니다. OpenAI 각 보이스가 어떤 음질인지 VOICEVOX 캐릭터에 매핑하는 정의는 없으므로, 호환성을 위해 편의상 매핑하고 있습니다. VOICEVOX 캐릭터의 별칭 (ずんだもん, 四国めたん/ノーマル 등)의 이용을 권장합니다.

​

다음에 읽어볼 페이지

엔진 API: 송

sing_frame_audio_query와 frame_synthesis 사용법을 확인합니다.

Laravel AI SDK 연동

Audio 파사드에서 VOICEVOX를 사용하는 설정을 확인합니다.