Engine API 模式:Talk(文字語音合成)- VOICEVOX for Laravel

什麼是 Engine API 模式

Engine API 模式會在 Laravel 應用內提供官方 VOICEVOX 引擎相容的 HTTP API。只要以 php artisan serve --port=50513 啟動應用,就能直接使用 /audio_query 或 /synthesis。

事前準備

設定 VOICEVOX Core for PHP

依安裝與設定準備好 voicevox-core-php 與核心 library。

設定環境變數並啟用 FFI

VOICEVOX_CORE_PATH=/path/to/voicevox_core/

ffi.enable=true

安裝角色資訊資源

php artisan voicevox:install

啟動 Laravel 版引擎

php artisan serve --port=50513

預設會以 http://127.0.0.1:50513 啟動。

關於 port 50513

官方 VOICEVOX 引擎的預設 port 為 50021。為了讓 Laravel 版引擎與官方引擎能同時啟動,預設 port 定為 50513。因為只是加上 --port=50513 啟動,使用 --port=8000 等其他 port 亦可。

官方引擎在 port 被佔用時,會自動調整到 50022 之後的空閒 port 啟動。php artisan serve 若不指定 --port 也會自動調整到 8001 之後,但指定 --port 時,若該 port 被佔用會啟動失敗。建議指定不易與其他服務衝突的固定 port。50513 是其中一例。

產生 Talk 語音

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 Client 使用

可將 Laravel 版引擎作為 Client 模式的連線目標。

// 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');

Engine API 的啟用/停用與 fallback

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

cancellable_synthesis 或 multi_synthesis 等未實作的 endpoint 可 fallback 至官方引擎。

使用 fallback 時,請於 VOICEVOX_ENGINE_FALLBACK_URL 端啟動官方引擎。

Talk 相關的對應狀況

Endpoint	Laravel 版	Fallback	備註
`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`	❌	✅	僅 fallback
`POST /multi_synthesis`	❌	✅	僅 fallback

OpenAI 相容 TTS endpoint

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`	Style ID(數字)、別名(`ずんだもん`、`四国めたん` 等)或 OpenAI voice 名稱(`alloy`、`shimmer` 等)
`speed`	播放速度。作為 `speedScale` 套用(0.25~4.0,省略為 1.0)
`response_format`	一律以 wav 回傳。指定值會被忽略
其他參數	會被忽略

OpenAI voice 名稱(alloy、shimmer 等)為臨時對應。因為沒有定義 OpenAI 各 voice 的音色對應到哪個 VOICEVOX 角色,基於相容性目的暫時對應。建議使用 VOICEVOX 角色的別名(ずんだもん、四国めたん/ノーマル 等)。

下一步閱讀

Engine API: Song

確認 sing_frame_audio_query 與 frame_synthesis 的用法。

Laravel AI SDK 整合

確認從 Audio Facade 使用 VOICEVOX 的設定。

GitHub Copilot

SDK

AI SDK

VOICEVOX

入門套件

Feed 與 RSS

中介層

Engine API 模式:Talk(文字語音合成)- VOICEVOX for Laravel

什麼是 Engine API 模式

事前準備

啟動 Laravel 版引擎

關於 port 50513

產生 Talk 語音

1. 建立 `audio_query`

2. 以 `synthesis` 合成語音

從 Laravel Client 使用

Engine API 的啟用/停用與 fallback

Talk 相關的對應狀況

OpenAI 相容 TTS endpoint

參數

下一步閱讀

Engine API: Song

Laravel AI SDK 整合

​什麼是 Engine API 模式

​事前準備

​啟動 Laravel 版引擎

​關於 port 50513

​產生 Talk 語音

​1. 建立 audio_query

​2. 以 synthesis 合成語音

​從 Laravel Client 使用

​Engine API 的啟用/停用與 fallback

​Talk 相關的對應狀況

​OpenAI 相容 TTS endpoint

​參數

​下一步閱讀

Engine API: Song

Laravel AI SDK 整合

什麼是 Engine API 模式

事前準備

啟動 Laravel 版引擎

關於 port 50513

產生 Talk 語音

1. 建立 `audio_query`

2. 以 `synthesis` 合成語音

從 Laravel Client 使用

Engine API 的啟用/停用與 fallback

Talk 相關的對應狀況

OpenAI 相容 TTS endpoint

參數

下一步閱讀