从零用Python搭建AI智能体：语音生成完整脚本视频

想象一下，你对着电脑说一句"生成一个程序员喝咖啡、被困难bug折磨的视频"，几分钟后，一个包含画面、旁白和字幕的完整短视频就出现在你面前。这听起来像是科幻电影里的场景，但一位B站UP主用Python和OpenRouter将这个想法变成了现实。整个项目的核心思路并不复杂：将语音转文字、脚本生成、图像生成、语音合成和视频生成这五个步骤串联成一条流水线，用一支API密钥调度所有AI模型。

流水线的整体设计思路

这条流水线包含五个清晰的步骤：录制语音并转录为文字、根据文字生成结构化脚本、依据脚本生成封面图、合成旁白音频、最后将图片和脚本变成动态视频。每一步都调用不同的AI模型，但全部通过OpenRouter的统一接口完成。

这种设计的巧妙之处在于解耦——每个步骤独立成一个Python文件，既可以单独运行调试，也能组合成main.py一键执行。UP主在视频中特别强调，理解了这个流程之后，你可以将其套用到几乎任何多模态AI项目中。

单一API密钥背后的工程哲学

传统做法里，要同时调用文本、图像、视频和语音模型，往往需要注册多个平台、集成不同SDK、管理七八个API密钥。这个项目选择OpenRouter作为统一入口，只用一个密钥就覆盖了所有模型。

这带来的不只是省事。OpenRouter允许在同一个请求中指定多个备选模型，比如主用GPT系列模型，失败时自动回退到Gemini系列。对于需要稳定运行的生产系统来说，这种"模型级联"能力避免了手动编写故障转移逻辑。UP主展示的仪表盘还提供了按请求、按模型的成本明细，让你清楚知道每一分钱花在了哪里。

第一步：从麦克风到文字

语音转录是整条链路的数据入口。项目使用OpenAI Whisper Large V3 Turbo模型，成本极低——UP主实测转录一句话的费用不到千分之一美分。

代码层面，这一步骤分为录制和转录两个函数。录制部分通过sounddevice库创建输入流，以固定采样率采集音频数据块，按回车键停止后合并为WAV文件。转录部分将音频文件转为Base64编码，发送到/audio/transcriptions端点。UP主特意保留了"先存文件再读取"的两步设计，虽然稍显冗余，但方便回听原始录音做调试。

Whisper 是 OpenAI 于 2022 年开源的自动语音识别（ASR）模型系列，Large V3 Turbo 是其 2023 年底发布的蒸馏加速版本。传统 Whisper Large V3 采用编码器-解码器 Transformer 架构，参数量约 15 亿，而 Turbo 版本通过减少解码器层数（从 32 层降至 4 层）将推理速度提升数倍，同时保持接近原版的识别精度，尤其适合对延迟敏感的实时转录场景。该模型支持近百种语言，包括中文，并且对背景噪声和口音有一定鲁棒性。在 OpenRouter 等聚合平台上，Whisper 的计费按音频时长计算，因此成本极低，这也是 UP 主实测转录一句话不到千分之一美分的原因。

第二步：用JSON Schema约束脚本输出

拿到转录文本后，下一步是让大模型生成一份包含脚本、图像提示词和视频提示词的结构化输出。这里的技术亮点是结构化输出（Structured Output）——通过JSON Schema强制模型只返回预定格式的数据。

Schema定义了三个字段：script（带情绪标签的40-60词旁白）、image_prompt（16:9封面图的详细描述）、video_prompt（8秒动态片段描述）。同时设置additionalProperties: false，杜绝模型自由发挥。请求中还指定了回退模型列表和require_parameters: true，确保只有支持该Schema的提供商才会被路由。

这种做法的价值在于下游步骤的稳定性——后续的图像和视频生成可以直接从JSON中提取字段，无需用正则表达式去"猜"模型输出的格式。

JSON Schema 是一种用于描述和验证 JSON 数据结构的声明式语言，在 AI 应用开发中常被用作“结构化输出”的契约。通过向大模型 API 传递一个符合 JSON Schema 规范的 schema 对象，并设置 strict: true 或类似参数，可以强制模型生成的响应必须严格符合该 schema，否则请求会被拒绝或自动重试。additionalProperties: false 是 schema 中的一个关键字，用于禁止对象中出现未定义的额外字段，从而杜绝模型“自由发挥”产生冗余信息。require_parameters: true 则是 OpenRouter 特有的路由参数，它确保只有完整支持请求中所有参数（包括 schema）的模型提供商才会被选中，避免因提供商能力不足导致结构化输出失败。这种机制将数据格式校验从下游代码前移到模型调用层，显著提升了多步骤流水线的稳定性。

第三步：图像生成的模型选择与参数发现

图像生成看似简单，但不同模型支持的参数差异很大。项目调用/images端点，传入模型名、提示词和宽高比即可。返回的图像以Base64 JSON格式嵌入响应，解码后写入文件即可得到PNG。

UP主在视频中演示了一个实用技巧：向/images/models端点发送请求，可以查询某个图像模型支持的全部参数及取值范围。他在Recraft和Gemini之间做了对比——Recraft速度快、价格低，但生成的图片格式在后续视频步骤中引发了兼容性问题；Gemini质量更高但成本也更高。这个细节提醒我们，多模型流水线中，上游输出的格式兼容性是需要提前验证的。

第四步：旁白合成的独立价值

语音合成在这个项目中是一个"可选"步骤——最终的视频模型自带音频生成能力，但UP主仍然单独实现了文本转语音功能，用于展示OpenRouter在语音模型上的调用方式。

这一步骤使用Gemini的TTS模型，向/audio/speech端点发送脚本内容和音色参数。有一个值得注意的工程细节：部分语音模型的响应不直接返回费用，需要通过/generation端点用响应ID反查成本。这种成本追踪机制贯穿整个项目，最终汇总成一份完整的"账单"。

第五步：视频生成与轮询机制

视频生成是整条流水线中最复杂、也最昂贵的一步。项目采用"以图为始"的策略——将第三步生成的封面图作为视频的第一帧传入，这样能保证画面风格的连贯性。

请求发送到/videos端点后，并不会立即返回成品。响应中给出一个轮询URL，状态会在pending、in progress、completed之间流转。代码每隔15秒查询一次，直到视频就绪，再从unsigned_url下载MP4内容。UP主实测一次8秒720P视频花费约3.20美元，是整个流程中最大的开销项。

在实测中他还遇到了一个意外：某次视频请求被拒绝，提示"因第三方内容提供商限制无法提交"。他推测可能是提示词中涉及了版权相关元素。这暴露了视频模型在内容审核上的不确定性，实际部署时需要为此设计重试或降级策略。

轮询（polling）是处理异步任务的一种常见模式：客户端发送请求后立即获得一个任务 ID 或状态查询 URL，随后以固定间隔反复查询该 URL，直到任务状态变为完成或失败。在本项目中，视频生成属于计算密集型长任务，无法在单次 HTTP 请求的合理超时内返回结果，因此服务端采用异步处理。代码每 15 秒查询一次状态，状态依次经历 pending（排队中）、in progress（生成中）、completed（已完成）三个阶段。轮询间隔需要权衡：太短会增加服务器压力和请求成本，太长则延长整体等待时间。对于 8 秒视频，生成通常需要数分钟，15 秒的间隔是一个合理的折中。此外，生产环境还应设置最大轮询次数和超时退避策略，防止无限等待。

成本拆解与实用建议

UP主在完整跑通几个案例后给出了成本概览：转录几乎可以忽略不计，脚本生成不到一美分，图像生成从几美分到几毛钱不等，语音合成费用很低，而视频生成稳定占据总成本的90%以上。

如果你打算复现这个项目，可以从几个方向降低成本：选用更便宜的视频模型、缩短视频时长、降低分辨率。UP主建议初期充值1美元即可开始试验，但要认真生成视频则需要准备更多额度。所有代码通过描述栏链接免费获取。

这条流水线说明了什么

这个项目的意义不在于产出的视频有多精美——UP主自己也坦言效果"不算世界上最好的"。它真正展示的是一种可复用的工程范式：用统一API网关屏蔽多模型差异，用结构化输出保证步骤间数据契约，用轮询模式处理异步长任务，用成本追踪控制预算。

当你把这五个步骤拆开看，每一个都是标准的API调用；但串起来之后，就形成了一个能听懂人话、自动产出多模态内容的智能体雏形。对于想入门AI应用开发的Python开发者来说，这是一个结构清晰、可上手性强的实践样本。