Vai al contenuto principale

​
Cos’è la modalità API Engine

La modalità API Engine fornisce all’interno dell’applicazione Laravel un’API HTTP compatibile con il VOICEVOX Engine ufficiale. Basta avviare l’applicazione con php artisan serve --port=50513 per poter usare direttamente /audio_query o /synthesis.

​
Preparazione

1

Configurare VOICEVOX Core for PHP

Segui la procedura in Installazione e configurazione per preparare voicevox-core-php e la libreria core.
2

Abilitare le variabili d'ambiente e FFI

VOICEVOX_CORE_PATH=/path/to/voicevox_core/

ffi.enable=true
3

Installare le risorse delle informazioni sui personaggi

php artisan voicevox:install

​
Avviare l’engine versione Laravel

php artisan serve --port=50513
Per impostazione predefinita si avvia su http://127.0.0.1:50513.

​
Informazioni sulla porta 50513

La porta predefinita del VOICEVOX Engine ufficiale è la 50021. Per poter avviare contemporaneamente l’engine versione Laravel e quello ufficiale, la porta predefinita è impostata a 50513. Poiché si sta semplicemente avviando con --port=50513, puoi usare anche altre porte come --port=8000.
Quando la porta è già in uso, l’engine ufficiale si regola automaticamente su una porta libera a partire dalla 50022. Anche php artisan serve, se non viene specificato --port, si regola automaticamente a partire dalla 8001, ma se specifichi --port e la porta è occupata l’avvio fallisce. È consigliato indicare una porta fissa che difficilmente entri in conflitto con altri servizi. La 50513 ne è un esempio.

​
Generare audio di talk

​
1. Creare l’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. Sintetizzare l’audio con 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

​
Usare dal client Laravel

Puoi usare l’engine versione Laravel come destinazione della connessione in modalità 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');

​
Abilitazione/disabilitazione dell’API Engine e fallback

'engine' => [
    'disabled' => env('VOICEVOX_ENGINE_DISABLED', false),
    'fallback_url' => env('VOICEVOX_ENGINE_FALLBACK_URL', 'http://127.0.0.1:50021'),
],
Gli endpoint non implementati, come cancellable_synthesis o multi_synthesis, possono ricadere sull’engine ufficiale tramite fallback.
Quando usi il fallback, avvia l’engine ufficiale al VOICEVOX_ENGINE_FALLBACK_URL.

​
Stato di supporto relativo al talk

EndpointVersione LaravelFallbackNote
POST /audio_query✅✅enable_katakana_english non supportato
POST /accent_phrases✅✅enable_katakana_english non supportato
POST /synthesis✅✅
POST /mora_data✅✅
POST /mora_length✅✅
POST /mora_pitch✅✅
GET /speakers✅✅
GET /speaker_info✅✅Richiede l’installazione delle risorse
POST /cancellable_synthesis❌✅Solo fallback
POST /multi_synthesis❌✅Solo fallback

​
Endpoint TTS compatibile con OpenAI

POST /v1/audio/speech accetta lo stesso formato di richiesta dell’API di sintesi vocale di OpenAI. Basta cambiare il Base URL per poterlo utilizzare da Laravel AI SDK e da molti altri strumenti compatibili con le API OpenAI. 
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

​
Parametri

ParametroDescrizione
inputTesto da leggere (massimo 4096 caratteri)
voiceID di stile (numerico), alias (ずんだもん, 四国めたん, ecc.) o nome voce OpenAI (alloy, shimmer, ecc.)
speedVelocità di riproduzione. Applicata come speedScale (da 0.25 a 4.0, 1.0 se omesso)
response_formatViene sempre restituito in wav. Il valore specificato è ignorato
Altri parametriIgnorati
I nomi delle voci OpenAI (alloy, shimmer, ecc.) sono assegnazioni provvisorie. Non esiste una definizione ufficiale che associ la qualità vocale di ciascuna voce OpenAI ai personaggi VOICEVOX, per cui la mappatura è puramente di comodo per garantire compatibilità. Si consiglia di usare gli alias dei personaggi VOICEVOX (ずんだもん, 四国めたん/ノーマル, ecc.).

​
Pagine successive da leggere

API Engine: Song

Consulta come usare sing_frame_audio_query e frame_synthesis.

Integrazione con Laravel AI SDK

Consulta la configurazione per usare VOICEVOX tramite la facade Audio.
Ultima modifica il 13 luglio 2026

Argomenti correlati

Modalità nativa: Talk (sintesi vocale da testo) - VOICEVOX for LaravelModalità Engine API: Song (sintesi vocale cantata) - VOICEVOX for LaravelModalità client: Talk (sintesi vocale da testo) - VOICEVOX for LaravelVOICEVOX for LaravelInstallazione e configurazione - VOICEVOX for Laravel