메인 콘텐츠로 건너뛰기

​
엔진 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를 사용하는 설정을 확인합니다.
마지막 수정일 2026년 7월 13일

관련 항목

클라이언트 모드: 토크 (텍스트 음성 합성) - VOICEVOX for Laravel네이티브 모드: 토크 (텍스트 음성 합성) - VOICEVOX for Laravel엔진 API 모드: 송 (노래 음성 합성) - VOICEVOX for LaravelVOICEVOX for Laravel클라이언트 모드: 송 (노래 음성 합성) - VOICEVOX for Laravel