AI SDK 集成 fal.ai 图像生成 Provider：安装、配置与实战指南

AI SDK 集成 fal.ai 图像生成 Provider：安装、配置与实战指南

【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai

本指南以 AI SDK（The AI Toolkit for TypeScript）仓库中的@ai-sdk/fal包为对象，系统讲解如何在 TypeScript 项目中接入 fal.ai 图像生成能力：从安装、Provider 实例化、generateImage调用，到providerOptions.fal透传参数、图像编辑与尺寸控制等高级用法。读完本文，你将能基于 fal 提供的 Flux、Recraft、Ideogram、Sana 等模型，快速搭建可运行的图像生成与编辑流水线，并理解其在 AI SDK 中的底层实现原理。

一、fal Provider 是什么

@ai-sdk/fal是 AI SDK 官方提供的一个 Provider 封装，它为 TypeScript 开发者屏蔽了 fal.ai REST API 的细节，以统一的 AI SDK 模型接口暴露图像生成能力。该包位于仓库 packages/fal，模块名为@ai-sdk/fal，当前仓库中版本为3.0.40（见 package.json），基于@ai-sdk/provider与@ai-sdk/provider-utils构建，遵循 Apache-2.0 许可。

从源码看，@ai-sdk/fal并不只支持图像生成。其 Provider 接口（见 fal-provider.ts）声明了四类模型工厂方法：

• image(modelId)/imageModel(modelId)：图像生成与编辑，返回ImageModelV4；
• video(modelId)/videoModel(modelId)：视频生成（实验性），返回Experimental_VideoModelV4；
• speech(modelId)：语音合成，返回SpeechModelV4；
• transcription(modelId)：语音转写，返回TranscriptionModelV4。

其中图像生成是 README 的主线，也是本文重点；视频、语音与转写作为同一 Provider 的扩展能力，将在后文一并介绍。

二、安装与前置准备

在任意支持 ESM 的 Node.js 项目（要求 Node.js >= 22，见 package.json）中安装：

npm i @ai-sdk/fal

同时需要安装 AI SDK 核心包ai（用于generateImage等高层 API）与 zod 校验库：

npm i ai zod

提示：如果你使用 Claude Code、Cursor 等编码 Agent，README 建议在仓库中引入官方 AI SDK skill 以提升智能体对 SDK 的理解：

npx skills add vercel/ai

API Key 配置

fal.ai 的 API Key 有两条读取路径，按优先级排列（源码见 fal-provider.ts 中的loadFalApiKey）：

1. 创建 Provider 时显式传入apiKey选项；
2. 读取环境变量FAL_API_KEY，若未设置则回退到FAL_KEY。

export FAL_API_KEY="your-fal-api-key"

若两者均缺失，运行时会抛出明确错误提示。需要特别注意的是：在process不存在的环境（如部分 Edge Runtime）中，环境变量方案不可用，必须在createFal中显式传apiKey，源码对此有专门的分支判断（fal-provider.ts）。

三、创建 Provider 实例

README 展示的是最简用法——直接导入默认实例：

import { fal } from '@ai-sdk/fal';

fal是仓库导出的默认 Provider 实例（fal-provider.ts），等价于无参数调用createFal()。

当需要自定义配置时，使用createFal工厂函数。其FalProviderSettings（fal-provider.ts）支持以下选项：

import { createFal } from '@ai-sdk/fal'; const fal = createFal({ apiKey: process.env.FAL_API_KEY, baseURL: 'https://fal.run', headers: { 'X-Custom-Header': 'value' }, });

请求头构造逻辑在源码中清晰可见：每个请求都会携带Authorization: Key <apiKey>头，并自动追加ai-sdk/fal/<版本号>的 User-Agent 后缀（fal-provider.ts）。

四、图像生成实战：一个完整示例

README 给出了最小可运行的图像生成示例，通过 AI SDK 的generateImage高层 API 调用 Flux schnell 模型：

import { fal } from '@ai-sdk/fal'; import { generateImage } from 'ai'; import fs from 'fs'; const { image } = await generateImage({ model: fal.image('fal-ai/flux/schnell'), prompt: 'A cat wearing a intricate robe', }); const filename = `image-${Date.now()}.png`; fs.writeFileSync(filename, image.uint8Array); console.log(`Image saved to ${filename}`);

执行流程说明：

1. fal.image('fal-ai/flux/schnell')创建一个FalImageModel实例，modelId 用于拼接请求地址https://fal.run/fal-ai/flux/schnell（见 fal-image-model.ts）；
2. generateImage内部触发doGenerate：POST JSON 到 fal API，随后自动下载返回的图片 URL 为二进制Uint8Array（见 fal-image-model.ts 与downloadImage方法）；
3. 因此image.uint8Array可以直接用fs.writeFileSync落盘，无需再手动请求图片 URL。

FalImageModel的maxImagesPerCall固定为 1（fal-image-model.ts），即单次调用最多生成一张图。

内置模型 ID

FalImageModelId类型（fal-image-settings.ts）预置了大量模型 ID，覆盖文生图、图生图、修复、超分等场景，例如：

• Flux 系列：fal-ai/flux/schnell、fal-ai/flux/dev、fal-ai/flux-pro/v1.1、fal-ai/flux-pro/v1.1-ultra、fal-ai/flux-lora、fal-ai/flux-general（含image-to-image、inpainting子路由）；
• Recraft：fal-ai/recraft/v3/text-to-image、fal-ai/recraft/v3/image-to-image；
• 其他：fal-ai/ideogram/character、fal-ai/imagen4/preview、fal-ai/luma-photon、fal-ai/sana/v1.5/4.8b、fal-ai/qwen-image、fal-ai/aura-sr、fal-ai/bria/background/remove等。

类型定义以(string & {})收尾，因此也允许传入类型表中尚未枚举的新模型 ID（如 README 示例中的fal-ai/recraft-v3）。

五、providerOptions.fal：透传模型专属参数

不同 fal 模型除了 prompt 之外往往还有专属输入（风格、步数、引导系数等）。README 指出：将这类参数放入generateImage的providerOptions.fal属性即可原样透传：

const { image } = await generateImage({ model: fal.image('fal-ai/recraft-v3'), prompt: 'A cat wearing a intricate robe', size: '1920x1080', providerOptions: { fal: { style: 'digital_illustration', }, }, });

源码中，providerOptions.fal会先经falImageModelOptionsSchema（fal-image-model-options.ts）校验与归一化，再与prompt、size、seed、n等标准参数合并成最终请求体（fal-image-model.ts）。

已声明的内建参数

schema 中明确声明的 camelCase 参数及其约束：

此外 schema 使用z.looseObject，因此未枚举的任意自定义键（如示例中的style）也会被保留并透传给 fal API。

关于 snake_case 的兼容与弃用警告

schema 同时兼容历史 snake_case 写法（如guidance_scale、num_inference_steps、output_format、safety_tolerance、image_url、mask_url等），但会在 transform 阶段将其归一化为 camelCase，并收集进__deprecatedKeys列表（fal-image-model-options.ts）。

运行时若检测到__deprecatedKeys非空，doGenerate会向warnings追加提示，例如'guidance_scale' (use 'guidanceScale')，并注明这些写法将在@ai-sdk/falv2.0 移除（fal-image-model.ts）。因此新代码应统一使用 camelCase。

六、尺寸与宽高比的处理细节

README 示例中直接传了size: '1920x1080'。源码对size的解析遵循固定约定：

• size形如"宽x高"的字符串，会被拆分为{ width, height }对象传给 API 的image_size字段（fal-image-model.ts）；
• 若未传size而传了aspectRatio，则会按映射表转换为 fal 识别的枚举值（fal-image-model.ts）：

FalImageSize类型本身也允许直接使用'square'、'square_hd'、'landscape_16_9'等字符串枚举或{ width, height }对象（fal-image-settings.ts）。

七、图像编辑、inpainting 与多图输入

除了纯文生图，FalImageModel还实现了 AI SDK v4 的图像编辑接口。generateImage支持传入files（参考图）与mask（蒙版），源码会将其转为 Data URI 后写入请求体（fal-image-model.ts）：

• 单图编辑：files[0]转为image_url字段；若files传了多张但未开启useMultipleImages，只会使用第一张，并产生一条 warning 提示；
• 多图编辑：设置providerOptions.fal.useMultipleImages: true后，所有文件转为image_urls数组——适配fal-ai/flux-2/edit这类支持多图输入的模型；
• Inpainting：mask转为mask_url字段，可配合fal-ai/flux-general/inpainting等修复模型使用。

import { generateImage } from 'ai'; import fs from 'fs'; const { image } = await generateImage({ model: fal.image('fal-ai/flux-general/inpainting'), prompt: 'Replace the sky with a starry night', files: [await fs.promises.readFile('./photo.jpg')], mask: await fs.promises.readFile('./mask.png'), providerOptions: { fal: { strength: 0.8, numInferenceSteps: 30, }, }, });

注意：旧式的providerOptions.fal.imageUrl/maskUrl字符串参数仍被兼容，但已被标记为废弃，官方建议改用files/mask标准参数。

八、结果元数据与错误处理

providerMetadata.fal

doGenerate返回时会附带providerMetadata.fal元数据（fal-image-model.ts），包含每张图的width、height、contentType、fileName、fileData、fileSize，以及归一化后的 NSFW 标记nsfw（合并自响应中的has_nsfw_concepts与nsfw_content_detected数组）。响应中的timings（推理耗时）、seed、num_inference_steps等也会原样透传。

错误响应解析

fal API 的错误分为两类，源码用 zod schema 分别建模后合并解析（fal-image-model.ts）：

• 校验错误：响应体含detail数组，每个元素含loc（字段路径）、msg（消息）、type；错误信息会拼接为字段路径: 消息的多行文本；
• 普通 HTTP 错误：响应体含message字段。

这使得开发者在 prompt 或参数不合法时，能拿到指明具体字段的错误信息，便于快速定位。

九、同一 Provider 的扩展能力：视频、语音与转写

虽然 README 聚焦图像生成，但@ai-sdk/fal在仓库中还实现了三类模型，均复用同一个falProvider 实例。

视频生成（队列机制）

FalVideoModel（fal-video-model.ts）实现了 AI SDK v4 的实验性视频接口，采用 fal 的队列式工作流：

1. doStart向https://queue.fal.run/fal-ai/<modelId>提交任务，若配置了 webhook 则追加?fal_webhook=<url>参数，响应中取得response_url与submit_url；
2. doStatus轮询response_url；若 fal 返回"Request is still in progress"则返回status: 'pending'；
3. 完成后返回status: 'completed'及视频 URL、mediaType（默认video/mp4）。

支持的模型 ID 包括luma-dream-machine、luma-ray-2、minimax-video、hunyuan-video等（fal-video-settings.ts）。请求体支持prompt、image_url（图生视频）、aspect_ratio、duration（如"5s"）、seed，以及providerOptions.fal中的loop、motionStrength（映射motion_strength）、resolution、negativePrompt（映射negative_prompt）、promptOptimizer（映射prompt_optimizer）等参数。

语音合成

FalSpeechModel（fal-speech-model.ts）请求体包含text、voice、speed与output_format（url或hex），响应中的音频 URL 会被自动下载为二进制。其专属选项voice_setting（speed、vol、voice_id、pitch、english_normalization、emotion）、audio_setting、language_boost、pronunciation_dict定义在 fal-speech-model-options.ts。需要注意两个行为：

• fal 语音模型不直接支持language标准参数，传入会触发unsupportedwarning，官方建议改用providerOptions.fal.language_boost；
• 不支持的outputFormat值会回退为url并产生 warning。

支持模型见 fal-speech-settings.ts：fal-ai/minimax/speech-02-hd、fal-ai/minimax/speech-02-turbo、fal-ai/minimax/voice-clone、fal-ai/dia-tts等。

语音转写

FalTranscriptionModel（fal-transcription-model.ts）将音频转为 base64 Data URI 后提交到队列端点，轮询直至完成。默认请求体为task: 'transcribe'、diarize: true、chunk_level: 'word'，可通过providerOptions.fal覆盖language、version、batchSize（映射batch_size）、numSpeakers（映射num_speakers）、diarize、chunkLevel（映射chunk_level）等字段。模型 ID 目前为whisper与wizper（fal-transcription-options.ts）。

十、如何验证与深入阅读

仓库为@ai-sdk/fal提供了完整的单元测试与快照测试，是理解各模型行为边界的首选材料：

• fal-image-model.test.ts：图像生成的请求体构造、尺寸/宽高比解析、NSFW 元数据归一化、废弃 snake_case 警告等；
• fal-speech-model.test.ts、fal-video-model.test.ts、fal-transcription-model.test.ts：分别覆盖三类模型的参数映射与流程；
• fal-provider.test.ts：Provider 实例与 API Key 加载逻辑；
• snapshots与fixtures：记录真实请求/响应样例（含转写队列的 JSON fixture）。

运行测试的命令在 package.json 中定义：pnpm test会同时执行 Node 与 Edge 两套 vitest 配置（vitest.node.config.js、vitest.edge.config.js）。

结语

@ai-sdk/fal以极小的学习成本将 fal.ai 的图像生成、编辑、视频、语音与转写能力统一收编进 AI SDK 的模型抽象体系。核心用法只需三件事：安装@ai-sdk/fal、配置 API Key、用fal.image('<model-id>')搭配generateImage调用；进阶能力则集中在providerOptions.fal的透传参数、size/aspectRatio尺寸控制以及files/mask编辑输入上。借助仓库源码，你可以精确把握每个参数如何映射到 fal API、哪些写法已被标记废弃，从而写出更健壮、更易维护的多模态生成应用。

【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai