引擎 API 模式：Talk（文本语音合成） - VOICEVOX for Laravel

什么是引擎 API 模式

引擎 API 模式在 Laravel 应用内提供与官方 VOICEVOX 引擎兼容的 HTTP API。只需通过 php artisan serve --port=50513 启动应用，就可以直接使用 /audio_query、/synthesis 等端点。

前置准备

配置 VOICEVOX Core for PHP

按照安装与配置的步骤准备好 voicevox-core-php 与核心库。

配置环境变量并启用 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 启动。

关于端口 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 字符）
`voice`	Style 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 的配置。

GitHub Copilot

SDK

AI SDK

VOICEVOX

启动套件

Feed 与 RSS

中间件

引擎 API 模式：Talk（文本语音合成） - VOICEVOX for Laravel

什么是引擎 API 模式

前置准备

启动 Laravel 版引擎

关于端口 50513

生成 Talk 音频

1. 创建 `audio_query`

2. 通过 `synthesis` 合成音频

从 Laravel 客户端使用

引擎 API 的启用/禁用与 Fallback

Talk 相关端点的支持情况

OpenAI 兼容的 TTS 端点

参数

下一步阅读

引擎 API：Song

Laravel AI SDK 集成

​什么是引擎 API 模式

​前置准备

​启动 Laravel 版引擎

​关于端口 50513

​生成 Talk 音频

​1. 创建 audio_query

​2. 通过 synthesis 合成音频

​从 Laravel 客户端使用

​引擎 API 的启用/禁用与 Fallback

​Talk 相关端点的支持情况

​OpenAI 兼容的 TTS 端点

​参数

​下一步阅读

引擎 API：Song

Laravel AI SDK 集成

什么是引擎 API 模式

前置准备

启动 Laravel 版引擎

关于端口 50513

生成 Talk 音频

1. 创建 `audio_query`

2. 通过 `synthesis` 合成音频

从 Laravel 客户端使用

引擎 API 的启用/禁用与 Fallback

Talk 相关端点的支持情况

OpenAI 兼容的 TTS 端点

参数

下一步阅读