跳转到主要内容

​
什么是引擎 API 模式

引擎 API 模式在 Laravel 应用内提供与官方 VOICEVOX 引擎兼容的 HTTP API。 只需通过 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 就是其中一个例子。

​
生成 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 客户端使用

可以将 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 的启用/禁用与 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 等未实现的端点，可以 fallback 到官方引擎。
使用 fallback 时，请在 VOICEVOX_ENGINE_FALLBACK_URL 侧启动官方引擎。

​
Talk 相关端点的支持情况

端点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 端点

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 字符）
voiceStyle ID（数值）、别名（ずんだもん、四国めたん 等）或 OpenAI 音色名（alloy、shimmer 等）
speed播放速度。作为 speedScale 应用（0.25～4.0，省略时为 1.0）
response_format始终以 wav 返回。指定的值会被忽略
其他参数会被忽略
OpenAI 音色名（alloy、shimmer 等）是临时映射。由于 OpenAI 各音色的声音特质与 VOICEVOX 角色之间不存在正式对应定义，这里只是为了兼容性做了权宜映射。建议使用 VOICEVOX 角色的别名（如 ずんだもん、四国めたん/ノーマル 等）。

​
下一步阅读

引擎 API：Song

了解 sing_frame_audio_query 与 frame_synthesis 的用法。

Laravel AI SDK 集成

了解从 Audio Facade 使用 VOICEVOX 的配置。
最后修改于 2026年7月13日

相关主题

客户端模式：Talk（文本语音合成） - VOICEVOX for Laravel原生模式：Talk（文本语音合成） - VOICEVOX for Laravel引擎 API 模式：Song（歌声合成） - VOICEVOX for LaravelVOICEVOX for Laravel安装与配置 - VOICEVOX for Laravel