OpenClaw fal 生成 Provider 完全指南图片、视频与音乐一站式生成【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw本文围绕 OpenClaw 内置的fal生成 Provider 展开系统讲解如何通过FAL_KEY完成认证接入并利用同一套 provider 配置调用 fal 托管的图片Flux、GPT Image 2.5、Krea 2 等、视频MiniMax、HeyGen、Kling、Wan、Seedance 2.0与音乐MiniMax Music、ACE-Step、Stable Audio生成能力。读完本文你将掌握openclaw infer image/video/music系列命令、agents.defaults.mediaModels的模型默认值配置以及不同模型家族之间在尺寸、宽高比、分辨率、参考图数量上的差异与限制。fal Provider 概览OpenClaw 内置bundled了fal生成 provider用于托管式图片、视频与音乐生成。它通过统一的 plugin 机制注册了三个生成能力入口见 extensions/fal/index.tscreateFalProvider()注册 provider 本体其余三个构建函数分别注册图片、视频、音乐生成 provider。属性值ProviderfalAuthFAL_KEY规范命名FAL_API_KEY也可作为后备APIfal 模型端点https://fal.run视频任务使用https://queue.fal.runBase URL可通过models.providers.fal.baseUrl覆盖从源码看provider 注册时声明了envVars: [FAL_KEY]并在 HTTP 层使用Authorization: Key apiKey请求头见 extensions/fal/http-config.ts。默认 Base URL 常量为https://fal.run视频的队列端点则是通过resolveFalQueueBaseUrl将fal.run主机替换为queue.fal.run得到见 extensions/fal/video-generation-provider.ts。快速开始1. 获取 API Key在 fal 控制台的 Keys 页面创建 API key。2. 设置 API Keyopenclaw onboard --auth-choice fal-api-key非交互式环境可以直接传--fal-api-key key或导出环境变量FAL_KEY。引导流程onboarding在用户尚未配置图片模型时会顺带把fal/fal-ai/flux/dev写为默认图片模型。从源码看认证方法通过createProviderApiKeyAuthMethod定义见 extensions/fal/provider-registration.ts关键参数包括flagName: --fal-api-keyCLI 标志名envVar: FAL_KEY环境变量名optionKey: falApiKey配置文件中的选项键wizard.choiceId: fal-api-key引导向导的选项 IDonboardingScopes: [image-generation, music-generation]覆盖图片与音乐生成范围。对应的测试用例 extensions/fal/onboard.test.ts 验证了两点引导会写入mediaModels.image.primary fal/fal-ai/flux/dev且不会覆盖用户已配置的图片模型默认值。3. 设置默认图片模型引导完成后也可以手动在配置中指定默认图片模型{ agents: { defaults: { mediaModels: { image: { primary: fal/fal-ai/flux/dev, }, }, }, }, }mediaModels下同时支持image、video、music三个键分别对应三种生成的默认模型选择具体可参考文档中的 配置参考。图片生成内置 fal 图片生成 provider 的默认模型为fal/fal-ai/flux/dev源码常量DEFAULT_FAL_IMAGE_MODEL见 extensions/fal/image-generation-provider.ts。能力值最大图片数每请求 4 张Krea 2 每请求 1 张尺寸覆盖1024x1024、1024x1536、1536x1024、1024x1792、1792x1024宽高比除 Flux 图生图image-to-image外均支持分辨率1K、2K、4K各模型限制不同见下文输出格式png默认或jpegGPT Image 2.5 额外支持webpKrea 2 拒绝覆盖输出格式编辑请求与各模型参考图限制带参考图通过共享的image/images参数传入的编辑请求会路由到每个模型对应的编辑端点参考图数量按模型族各有上限模型家族fal/后的模型引用编辑端点最大参考图数Flux 及其他 fal 模型fal-ai/flux/dev默认/image-to-image1GPT Image 2.5openai/gpt-image-2.5/{flare,sunburst}/text-to-image同级的/edit16旧版 GPT Imageopenai/gpt-image-*/edit10Grok Imaginexai/grok-imagine-image/edit3Nano Banana旧版fal-ai/nano-banana/edit3Nano Banana 2fal-ai/nano-banana-*/edit14Nano Banana 2 Litegoogle/nano-banana-2-lite/edit14Krea 2krea/v2/{medium,large}/text-to-image无样式参考10 张样式参考图⚠️ 限制说明Flux 图生图请求不支持aspectRatio覆盖源码中会直接抛出 fal flux image edit endpoint does not support aspectRatio overrides。GPT Image 与 Nano Banana 2 的编辑请求使用 fal 的/edit端点接受宽高比提示。Nano Banana 2 额外接受原生超宽/超高比例如4:1、1:4、8:1、1:8Krea 2 只校验自己较小的宽高比子集。Grok Imagine 有自己的宽高比列表含2:1、20:9、19.5:9及其反转且只接受1K/2K分辨率旧版 Nano Banana 与 Nano Banana 2 Lite 拒绝resolution覆盖。上述限制在源码中均有对应常量与校验逻辑例如GPT_IMAGE_25_EDIT_MAX_INPUT_IMAGES 16、GPT_IMAGE_EDIT_MAX_INPUT_IMAGES 10、GROK_IMAGINE_EDIT_MAX_INPUT_IMAGES 3、KREA_STYLE_REFERENCE_MAX_INPUT_IMAGES 10、NANO_BANANA_EDIT_MAX_INPUT_IMAGES 14而 Flux 默认 schema 的maxInputImages为 1宽高比白名单同样按模型族分开定义KREA_SUPPORTED_ASPECT_RATIOS、GROK_IMAGINE_SUPPORTED_ASPECT_RATIOS、NANO_BANANA_SUPPORTED_ASPECT_RATIOS等。GPT Image 2.5选择以下任一变体fal/openai/gpt-image-2.5/flare/text-to-imagefal/openai/gpt-image-2.5/sunburst/text-to-image带参考图时自动选择同级的/edit端点也可以显式选择fal/openai/gpt-image-2.5/flare/edit或fal/openai/gpt-image-2.5/sunburst/edit。两个变体均支持quality取值为low、medium、high、xhigh、max或autofal 默认是high支持background取transparent、opaque或auto需要透明背景时使用outputFormat: png或webp。这些控制项不影响旧版 fal 模型。尺寸方面可使用size: auto或显式尺寸如1536x864要求宽高必须是 16 的倍数单边不超过 3840 像素总像素数在 655,360 到 8,294,400 之间宽高比在 1:3 到 3:1 之间。OpenClaw 会把宽高比提示转换为合法尺寸例如aspectRatio: 3:2会生成1536x1024想用精确尺寸就传sizeOpenClaw 会拒绝非法显式尺寸。这两个模型拒绝resolution覆盖无几何提示的编辑请求保持 fal 的自动尺寸选择。源码中resolveFalGptImage25AspectRatioSize以 1536px 长边计算短边并四舍五入到 16px 网格validateFalGptImage25Size则对尺寸做 16 整除、边缘上限、像素总量与宽高比范围校验。openclaw infer image generate \ --model fal/openai/gpt-image-2.5/flare/text-to-image \ --prompt A simple red circle sticker \ --quality low --size 1024x1024 --json openclaw infer image edit \ --model fal/openai/gpt-image-2.5/sunburst/edit \ --file /path/to/reference.png \ --prompt Keep the shape and change the color to blue \ --quality low --size auto --jsonKrea 2Krea 2 模型使用 fal 原生的 Krea payload schema。OpenClaw 发送aspect_ratio、creativity与image_style_references而不是 Flux 使用的通用image_size/ 编辑端点 payload。模型引用为fal/krea/v2/medium/text-to-imagefal/krea/v2/large/text-to-imageMedium 适合更快的表现力插画、动漫、绘画与艺术风格Large 适合较慢的写实、原始纹理、胶片颗粒与细节质感。Krea 默认fal.creativity: medium支持的取值为raw、low、medium、high。在 fal 请求 schema 中Krea 2 暴露的是宽高比而不是image_size因此优先使用aspectRatioOpenClaw 会把size映射到最接近的 Krea 宽高比并且对 Krea 的resolution直接拒绝而不是丢弃。源码中applyFalImageGeometry对 Kreageometry: native_aspect_ratio且referenceImages: image_style_references会抛出 fal Krea 2 supports aspectRatio but not resolution overrides。输出格式方面需要 PNG 输出时使用outputFormat: png针对暴露output_format的 fal 模型。除 GPT Image 2.5 外fal 模型在 OpenClaw 中不声明透明背景控制background会被报告为被忽略的覆盖项。Krea 2 端点不通过 fal 暴露output_format请求字段因此 OpenClaw 会拒绝 Krea 请求的outputFormat覆盖。使用 Krea 2 Medium 的配置{ agents: { defaults: { mediaModels: { image: { primary: fal/krea/v2/medium/text-to-image, }, }, }, }, }视频生成内置 fal 视频生成 provider 的默认模型为fal/fal-ai/minimax/video-01-live。能力值模式文生视频、单图参考、Seedance 参考图生视频运行时面向长任务的队列式 submit/status/result 流程超时每任务默认 20 分钟状态每 5 秒轮询一次源码中DEFAULT_OPERATION_TIMEOUT_MS 1_200_000即 20 分钟、POLL_INTERVAL_MS 5_000waitForFalQueueResult循环 GETstatus_url直到状态变为COMPLETED后再 GETresponse_url取结果IN_QUEUE、IN_PROGRESS、PROCESSING、QUEUED、STARTED均视为进行中状态FAILED/CANCELLED直接抛错见 extensions/fal/video-generation-provider.ts。可用视频模型MiniMax默认fal/fal-ai/minimax/video-01-liveHeyGen video-agentfal/fal-ai/heygen/v2/video-agentKling 与 Wanfal/fal-ai/kling-video/v2.1/master/text-to-videofal/fal-ai/wan/v2.2-a14b/text-to-videofal/fal-ai/wan/v2.2-a14b/image-to-videoSeedance 2.0fal/bytedance/seedance-2.0/fast/text-to-videofal/bytedance/seedance-2.0/fast/image-to-videofal/bytedance/seedance-2.0/fast/reference-to-videofal/bytedance/seedance-2.0/text-to-videofal/bytedance/seedance-2.0/image-to-videofal/bytedance/seedance-2.0/reference-to-videoMiniMax Live 与 HeyGen 请求只发送 prompt 与可选的单张参考图其余覆盖项不会转发源码注释也说明 MiniMax Live 目前 fal 文档只支持 prompt 可选image_url保持默认模型保守可避免队列请求因不支持的参数挂起。Seedance 模型接受aspectRatio、size、resolution、4–15 秒时长与音频开关。Seedance 2.0 配置示例{ agents: { defaults: { mediaModels: { video: { primary: fal/bytedance/seedance-2.0/fast/text-to-video, }, }, }, }, }Seedance 2.0 reference-to-video 配置示例{ agents: { defaults: { mediaModels: { video: { primary: fal/bytedance/seedance-2.0/fast/reference-to-video, }, }, }, }, }reference-to-video 通过共享的video_generate参数images、videos、audioRefs最多接受 9 张图片、3 个视频、3 个音频参考单次请求参考文件总数不超过 12提供音频参考时同一请求必须至少附带一张图片或一个视频参考。这些限制在源码中均有对应校验SEEDANCE_REFERENCE_MAX_IMAGES 9、SEEDANCE_REFERENCE_MAX_VIDEOS 3、SEEDANCE_REFERENCE_MAX_AUDIOS 3、SEEDANCE_REFERENCE_MAX_FILES 12且音频参考存在而图片与视频参考都为空时直接报错。HeyGen video-agent 配置示例{ agents: { defaults: { mediaModels: { video: { primary: fal/fal-ai/heygen/v2/video-agent, }, }, }, }, }音乐生成内置 fal 插件同样为共享的music_generate工具注册了音乐生成 provider见 extensions/fal/music-generation-provider.ts。能力值默认模型fal/fal-ai/minimax-music/v2.6模型fal-ai/minimax-music/v2.6mp3、fal-ai/ace-step/prompt-to-audiowav、fal-ai/stable-audio-25/text-to-audiowav最大时长240 秒运行时同步请求 生成音频下载将 fal 设为默认音乐 provider{ agents: { defaults: { mediaModels: { music: { primary: fal/fal-ai/minimax-music/v2.6, }, }, }, }, }fal-ai/minimax-music/v2.6支持显式歌词与纯音乐instrumental模式但同一请求中不能同时使用两者源码中若同时传入lyrics且instrumentaltrue会直接抛错且未提供歌词且非纯音乐时会默认开启lyrics_optimizer: true。ACE-Step 与 Stable Audio 是 prompt-to-audio 端点想使用这些模型家族时通过model覆盖项选择ACE-Step 拒绝显式歌词Stable Audio 同时拒绝歌词与纯音乐模式。 提示上文表格与手风琴内容覆盖了内置 fal provider 特殊处理的模型家族。其他 fal 图片端点 ID 仍可作为图片模型选择它们会被当作 Flux 处理通用image_sizepayload经/image-to-image传一张参考图。相关阅读图片生成工具共享图片工具参数与 provider 选择视频生成工具共享视频工具参数与 provider 选择音乐生成工具共享音乐工具参数与 provider 选择配置参考Agent 默认值包括图片、视频、音乐模型选择【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考