如何快速上手 Laravel AI 多模态：图片生成、文字转语音、语音转写完整指南

Laravel AI SDK 是 Laravel 官方的 AI 开发包，一套统一的、富有表现力的 API 即可调用 OpenAI、Anthropic、Gemini 等 18 家 AI 服务商。它的多模态能力尤其亮眼：图片生成、文字转语音（TTS）、语音转写（STT）三大能力开箱即用，本文带你一步到位掌握。

为什么选择 Laravel AI 处理多模态？

很多新手接入 AI 时都要面对一个头疼的问题：不同服务商的 API 格式五花八门，换一家就要重写一遍代码。Laravel AI 用统一门面（Facade）+ 网关抽象解决了这件事：

• 🎯一套 API 覆盖 18 家服务商：Image、Audio、Transcription三个入口类统一调度，换服务商只需改配置
• 🔄自动故障转移（Failover）：主服务商挂了自动切换备用，无需自己写重试逻辑
• 📦响应对象即文件：图片、音频响应都实现了Stringable，可直接store()到 Laravel Storage
• 🧪Fake 测试支持：Image::fake()、Audio::fake()让单元测试不发真实请求

一键安装与配置多模态默认服务商

安装 Laravel AI SDK

composer require laravel/ai

也可以从镜像仓库克隆体验：

git clone https://gitcode.com/gh_mirrors/ai89/ai

配置 API 密钥与默认服务商

安装后修改 config/ai.php，填入你要用的服务商 API Key。这里的关键设计是按能力分别指定默认服务商：

也就是说，每个多模态能力都可以用最擅长它的那个服务商，而不是被单一服务商绑死。比如你可以让图片走 Gemini（免费额度大）、语音走 ElevenLabs（音色最自然）、转写走 OpenAI（识别精度高）。

哪些服务商支持哪些能力？

完整实现见 src/Providers/ 目录，每个 Provider 都实现了 Contracts/Providers/ 中对应的能力接口，能力边界一目了然。

图片生成：一句话出图的完整教程

最快出图方法：三行代码

use Laravel\Ai\Image; $response = Image::of('一只在月球上喝咖啡的柴犬，插画风格')->generate(); // 直接保存到 Storage $response->store('generated/dog-on-moon'); // 或在 Blade 中直接渲染 <img> 标签 echo $response->toHtml(alt: '月球柴犬');

入口类是 src/Image.php，of()返回一个延迟执行对象 PendingImageGeneration，链式配置后调用generate()才真正发起请求。

控制图片比例与质量

PendingImageGeneration提供了非常贴心的链式方法：

Image::of('日落时分的海边城市') ->landscape() // 横版 3:2 ->quality('high') // low / medium / high ->timeout(60) ->generate();

• square()— 正方形 1:1
• portrait()— 竖版 2:3
• landscape()— 横版 3:2
• size('1:1')— 也可以直接指定任意比例字符串

以图修图：参考图附件

生成时可以通过attachments()传入参考图（如产品图、风格参考图），让 AI 基于已有画面做延展：

use Laravel\Ai\Files\LocalImage; Image::of('把背景换成雪山') ->attachments([LocalImage::fromPath('/tmp/product.jpg')]) ->generate();

指定服务商与模型

不指定服务商时使用default_for_images配置，也可以显式指定，甚至传入服务商列表实现故障转移：

// 指定 Gemini 的某个模型 Image::of('...')->generate(Lab::Gemini, 'gemini-2.5-flash-image'); // 主用 OpenAI，失败自动转移到 Gemini Image::of('...')->generate([Lab::OpenAi, Lab::Gemini]);

服务商枚举定义在 src/Enums/Lab.php，共 18 个。

异步生成：放入队列

图片生成耗时较长，适合丢进 Laravel Queue 异步处理：

Image::of('一张科幻城市海报')->queue();

队列由 src/Jobs/GenerateImage.php 执行，完成后触发 src/Events/ImageGenerated.php 事件，你可以监听它把图片 URL 写回数据库。

文字转语音：让应用开口说话的简单方法

快速生成语音

use Laravel\Ai\Audio; $response = Audio::of('欢迎来到 Laravel AI 多模态指南')->generate(); // 保存为音频文件（自动根据 MIME 推断扩展名） $response->store('audio/welcome'); // 直接获取二进制内容 $binary = $response->content();

入口类 src/Audio.php 与图片入口结构完全一致，链式对象 PendingAudioGeneration 默认使用 30 秒超时和default-female音色。

选择音色与发音风格

Audio::of('今天天气真好') ->male() // 男声 ->instructions('语速稍慢，语气亲切') // 自由指令引导发音风格 ->generate(); // 或使用具体音色 Audio::of('Hello!')->voice('shimmer')->generate(Lab::OpenAi);

• male()/female()— 快捷选择默认男声/女声
• voice('shimmer')— 指定具体音色名（不同服务商音色名不同，ElevenLabs 默认模型为eleven_multilingual_v2，见 src/Providers/ElevenLabsProvider.php）
• instructions()— 用自然语言描述想要的语气、节奏、情绪

用 ElevenLabs 获得更自然的声音

文字转语音是 ElevenLabs 的招牌能力，只需在配置里启用eleven服务商（设置ELEVENLABS_API_KEY），调用时指定即可：

Audio::of('这段播客开场白')->generate(Lab::ElevenLabs);

响应对象 AudioResponse 支持store()、storePublicly()、storeAs()等标准 Laravel 存储方法，MIME 类型会自动映射为.mp3、.wav、.opus等扩展名。

语音转写：把录音变成文字的实用技巧

支持四种音频来源

与"只收 base64"的 API 不同，src/Transcription.php 提供了覆盖真实场景的入口：

use Laravel\Ai\Transcription; // 1. 本地文件路径 Transcription::fromPath('/tmp/meeting.mp3')->generate(); // 2. Laravel Storage 中的文件 Transcription::fromStorage('recordings/call.wav')->generate(); // 3. 用户上传文件（控制器中直接传 $request->file('audio')） Transcription::fromUpload($request->file('audio'))->generate(); // 4. Base64 字符串 Transcription::fromBase64($base64, 'audio/mpeg')->generate();

指定语言与说话人分离

Transcription::fromPath('interview.wav') ->language('zh') // ISO-639-1 语言代码，可显著提升识别精度 ->diarize() // 说话人分离：区分"谁在说" ->generate();

响应对象 TranscriptionResponse 包含：

• text— 完整转写文本（对象实现了Stringable，echo $response直接输出）
• segments— 分段结果（含时间戳，说话人分离后还带说话人标识）
• usage/meta— 用量与元数据

长录音？交给队列

转写大文件建议走队列，且只接受本地文件 / Storage 文件（保证 Job 可序列化）：

Transcription::fromPath('/var/long-interview.wav')->queue();

由 src/Jobs/GenerateTranscription.php 执行，完成后触发 TranscriptionGenerated 事件。

故障转移与 Fake 测试：新手也能写健壮代码

自动故障转移原理

三个能力的generate()内部都遵循同一模式（见 PendingImageGeneration）：

1. 依次尝试服务商列表
2. 捕获FailoverableException（限流、过载、连接失败等）
3. 派发 ProviderFailedOver 事件，切换到下一家

// OpenAI 挂了？自动用 Gemini 顶上，业务代码零改动 Image::of('一只猫')->generate([Lab::OpenAi, Lab::Gemini]);

不发真实请求的单元测试

多模态调用涉及文件与音频，真实请求测试成本高。SDK 内置 Fake 网关：

use Laravel\Ai\Audio; use Laravel\Ai\Image; Image::fake()->images('fake-image-data'); Audio::fake()->audio('fake-audio-data'); // 断言 Image::assertGenerated(fn ($prompt) => str_contains($prompt->prompt, '柴犬'));

Fake 实现位于 src/Gateway/FakeImageGateway.php、FakeAudioGateway.php、FakeTranscriptionGateway.php，与真实网关完全同构。

核心文件导航

常见问题 FAQ

Q1：调用报错"provider not configured"怎么办？检查 config/ai.php 中对应服务商的key是否已配置环境变量，并确认该服务商支持对应能力（见上文能力矩阵）。

Q2：生成的图片如何直接展示在页面上？ImageResponse实现了Htmlable，在 Blade 模板中输出即得到<img>标签（base64 内嵌）：{{ $response->toHtml(alt: '生成图') }}。

Q3：可以同时指定多家服务商做主备吗？可以。generate()接受数组形式的服务商列表，例如generate([Lab::OpenAi, Lab::ElevenLabs])，前一家抛出可转移异常时自动切换，并派发ProviderFailedOver事件便于监控。

Q4：转写中文需要特别配置吗？建议显式调用->language('zh')，明确语言可显著提升识别准确率；多人对话场景加->diarize()区分说话人。

小结

Laravel AI SDK 把图片生成、文字转语音、语音转写三大多模态能力压缩成了三个入口类、一致的链式 API 和统一的响应对象。按本文步骤走一遍：装包 → 配 config/ai.php → 按能力选服务商 → 用generate()或queue()发起调用，你的 Laravel 应用今天就具备了完整的"看、说、听"能力。🚀