AutoGPT 平台 AI Video Generator 块实战：基于 FAL.ai（Mochi / Luma / Veo3）的文本生成视频
【免费下载链接】AutoGPTAutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.项目地址: https://gitcode.com/GitHub_Trending/au/AutoGPT
导读
AI Video Generator 是 AutoGPT 平台（autogpt_platform）内置的 FAL.ai 集成块，它把"用一句文字描述生成一段 AI 视频"封装为一个可直接拖入 Agent 流程图的节点。本文将以官方块文档为骨架，结合仓库中的块源码、凭据定义与成本配置，系统讲解该块的输入输出契约、三种可选模型（Mochi / Luma Dream Machine / Veo3）、底层"提交—轮询—取回"的异步队列机制，以及如何将其接入内容创作、可视化与原型设计类 Agent 工作流。读完你可以直接在编辑器里配置它，并理解生成结果是如何被持久化到工作区、按秒计费的。
一、块是什么：一段文字换一段视频
按照官方块文档的定义，AI Video Generator 是一类"使用 FAL.ai 模型生成 AI 视频"的块。它的工作方式很直接：用自然语言描述你想生成的视频画面，模型后台完成生成并返回视频地址。
[你的 prompt 文字描述] → AI Video Generator → [video_url 视频地址 + logs 进度日志]在源码层面，该块对应AIVideoGeneratorBlock类，位于 ai_video_generator.py。它继承了平台通用的Block基类，拥有全局唯一 ID530cf046-2ce0-4854-ae2c-659db17c7a46，并被归入BlockCategory.AI（AI 类别）：
class AIVideoGeneratorBlock(Block): def __init__(self): super().__init__( id="530cf046-2ce0-4854-ae2c-659db17c7a46", description="Generate videos using FAL AI models.", categories={BlockCategory.AI}, ... )从仓库结构看，FAL 集成由三个文件组成，ai_video_generator.py是核心实现，_auth.py负责 FAL API Key 凭据，_config.py完成 Provider 注册元数据——本篇文章聚焦第一个文件对应块的用法与原理。
二、输入与输出契约：在编辑器中需要填什么
输入参数（Inputs）
文档给出两个输入字段：
| 输入 | 描述 | 类型 | 是否必填 |
|---|---|---|---|
| prompt | 描述要生成的视频内容 | str | 是 |
| model | 用于生成视频的 FAL 模型 | "fal-ai/mochi-v1" | "fal-ai/luma-dream-machine" | "fal-ai/veo3" | 否 |
- prompt（必填）：一句对视频画面的文字描述。例如在源码的占位符与测试样例中使用了
"A dog running in a field."（ai_video_generator.py），文档建议用户像写"一条狗在田野里奔跑"这样具体的描述。 - model（可选）：FAL 上要调用的视频生成模型。未指定时默认使用
fal-ai/mochi-v1。
该枚举在源码中被建模为FalModel(str, Enum)（ai_video_generator.py），共有三个成员，与文档表格完全一致：
class FalModel(str, Enum): MOCHI = "fal-ai/mochi-v1" LUMA = "fal-ai/luma-dream-machine" VEO3 = "fal-ai/veo3"它们分别对应 FAL.ai 上开放的 Mochi v1、Luma Dream Machine 与 Veo3 三个文本生成视频模型，model字段的默认值也指向FalModel.MOCHI。
输出结果（Outputs）
| 输出 | 描述 | 类型 |
|---|---|---|
| error | 视频生成失败时的错误信息 | str |
| video_url | 生成视频的 URL | str |
| logs | 生成进度日志 | List[str] |
三个输出中，成功时video_url携带视频地址，logs携带长任务进度日志；失败时error输出错误信息。源码中的输出定义还给出了各自的 SchemaField 描述（ai_video_generator.py），并在run()方法中用yield分别产出：
yield "video_url", stored_url # 成功：产出持久化后的视频地址 ... yield "error", error_message # 失败：产出错误信息字符串三、前置条件：配置 FAL API Key 凭据
与许多平台集成一样，使用该块前必须在 AutoGPT 平台中为"fal"这个 Provider 保存一把 API Key。
- Provider 标识为
fal。在 providers.py 的ProviderName枚举中定义FAL = "fal"。 - 凭据字段由 _auth.py 定义：
FalCredentials = APIKeyCredentials，即CredentialsMetaInput限定了 Provider 为fal、凭据类型为api_key；FalCredentialsField()生成的字段描述是 "The FAL integration can be used with an API Key."，说明该集成仅支持 API Key 一种认证方式（不支持 OAuth）。 - Provider 注册元数据见 _config.py：
ProviderBuilder("fal").with_description("Hosted model inference").with_supported_auth_types("api_key")，即"托管模型推理 + API Key 认证"。
请求 FAL API 时，该块在请求头写入Authorization: Key <你的 API Key>（ai_video_generator.py）。所以接入流程为：先在 FAL.ai 开通账号获取 API Key → 在 AutoGPT 平台的凭据管理中添加 fal Provider 的 Key → 在块实例的 credentials 输入中选择该凭据。
四、底层原理：异步队列式生成流程
视频生成通常耗时较长，不适合同步等待。因此该块按 FAL 的queue.fal.run 队列接口实现了"提交 → 轮询状态 → 取回结果"三步异步流程（见 generate_video）：
1. 提交生成请求
向https://queue.fal.run/{model}POST 提交{"prompt": ...}。值得注意的是源码中的模型差异化处理：
if input_data.model == FalModel.VEO3: submit_data["generate_audio"] = True即当选择fal-ai/veo3时，会自动额外开启音频生成（generate_audio=True），使视频同时包含声音；而 Mochi 与 Luma Dream Machine 只提交 prompt。
2. 解析响应并轮询状态
提交后从响应中取出三样东西并校验其存在性：request_id（请求 ID）、status_url（状态查询地址）、response_url（结果取回地址）。
随后进入轮询循环，向status_url?logs=1发起 GET 请求。其中?logs=1会让响应额外携带生成日志，块会逐条解析日志中的timestamp/message/level/source字段，并用"时间戳-消息"组合去重、仅处理新增日志（避免重复输出）——这就是logs输出的数据来源。
状态机存在以下几种取值：
COMPLETED：生成完成，转而去response_url取最终结果，校验result_data["video"]是 dict 且含有效url后返回该 URL；FAILED：抛出RuntimeError，携带接口返回的错误详情；IN_QUEUE：仍在排队，读取queue_position队列位置；IN_PROGRESS：正在生成；- 其他未知状态：记录为 unknown 继续等待。
3. 指数退避等待
两次轮询之间使用指数退避睡眠，且单次上限 60 秒、总轮询上限 30 次（ai_video_generator.py）：
max_attempts = 30 base_wait_time = 5 wait_time = min(base_wait_time * (2**attempt), 60) # 5s → 10s → 20s → 40s → 60s(封顶) await asyncio.sleep(wait_time)也就是说，轮询等待最长约为前几次 5s/10s/20s/40s 加若干次 60s 封顶，总计最多约 30 分钟上限；若超过仍未完成，块会抛出 "Maximum polling attempts reached"。整个过程由 async/await 驱动，多个视频任务可以并行执行而不阻塞其他节点。
五、生成结果的持久化：从临时 URL 到工作区文件
拿到 FAL 返回的视频 URL 后，块并不会直接把它当输出丢出去，而是先调用平台工具store_media_file()将媒体落盘到当前用户的 workspace（ai_video_generator.py）：
stored_url = await store_media_file( file=MediaFileType(video_url), execution_context=execution_context, return_format="for_block_output", ) yield "video_url", stored_url该工具定义在 backend/util/file.py（入参类型MediaFileType见 backend/util/type.py）。其意义在于：
- FAL 返回的是临时的远程 URL，可能过期；写入 workspace 后，视频会以
workspace://...的形式长期归属用户； - 块的自动化测试断言也印证了这一点——
test_output中校验video_url必须以workspace://或data:开头（ai_video_generator.py），即"取决于上下文，输出是工作区引用或 data URI"； - 用户可以在下游直接引用该工作区文件，做二次处理、下载或分发给下游块。
六、计费与成本模型：按秒计费
平台会为块调用计费。FAL 视频生成块的费用登记在 backend/data/block_cost_config.py：
AIVideoGeneratorBlock: [ BlockCost( cost_amount=15, cost_type=BlockCostType.SECOND, cost_filter={ "credentials": { "id": fal_credentials.id, "provider": fal_credentials.provider, "type": fal_credentials.type, } }, ) ],配置代码中的注释清楚解释了定价思路：Veo/Seedance 档约 $0.25–0.30/秒、Lite 档约 $0.05–0.10/秒，因此按15 积分/秒（15 cr/s，约 $0.15/s）的费率覆盖 Lite 档并留 1.5 倍余量。也就是说，该块实际消耗的积分与**生成等待时长（秒数）**成正比，而非与输出内容大小成正比——生成视频越久、占用的队列与算力时间越长，费用越高。相关计费逻辑由 block_cost_config_test.py 与 block_usage_cost_test.py 覆盖验证，例如 5 秒 walltime 的调用会按 15 cr/s 折算费用。
七、典型使用场景
文档明确给出三类落地场景，与前面的实操能力一一对应：
- 内容创作（Content Creation）：为社媒、广告或创意项目批量生成短视频素材。例如"写一条产品广告文案 → 生成对应画面视频 → 保存到工作区 → 由发布类块分发"。
- 可视化（Visualization）：把抽象的概念、产品形态或故事情节变成看得见的画面。适合非专业视频团队快速表达"一个概念长什么样"。
- 原型设计（Prototyping）：为创意构思与分镜（storyboarding）快速产出视频 mockup，在动手实拍或精修前低成本验证镜头语言与叙事节奏。
将这些场景落到流程图上，AI Video Generator 通常放在 LLM 之后作为"产出终端"，其video_url输出可以直接接存储、预览或通知节点。
八、可验证性与测试设计
该块自带一套完整的自测夹具（ai_video_generator.py），对阅读源码理解契约很有帮助：
test_input={"prompt": "A dog running in a field.", "model": FalModel.MOCHI, ...}, test_credentials=TEST_CREDENTIALS, # 来自 _auth.py 的 Mock FAL API key test_output=[("video_url", lambda x: x.startswith(("workspace://", "data:")))], test_mock={"generate_video": lambda *a, **k: "data:video/mp4;base64,AAAA"},- 测试输入使用的正是文档示例 prompt 与默认模型 Mochi；
test_credentials是 _auth.py 里的 Mock Key，避免真实网络请求；test_mock将生成方法替换为返回一个合法 data URI，从而在无 HTTP 请求的前提下验证整个块的输入输出链。
当你自己在平台中新增该块时，同样可以先用这类"占位描述"验证管线通畅，再替换为真实 prompt 投入生产。
小结
AI Video Generator 把"文字 → 视频"的昂贵、慢速操作收敛成一个对开发者友好的黑盒节点：配好 FAL API Key，填入 prompt 与模型，输出即获得可持久化的视频地址。理解它的队列式异步轮询、Veo3 自动伴音、指数退避与按秒计费规则，能帮你更合理地设计长视频生成类 Agent 工作流，也便于在失败时定位错误、在成本上做好预估。想要深入其实现细节，可继续阅读 块源码、凭据定义 与 成本配置。
【免费下载链接】AutoGPTAutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.项目地址: https://gitcode.com/GitHub_Trending/au/AutoGPT
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
