Gemini Omni 1.2 Flash API 怎么用?从生成视频到下载验收
用完整 Python 示例调用 Gemini Omni 1.2 Flash,处理文件轮询、下载失败恢复和视频校验,并了解参考素材、编辑与续接的限制。
调用 gemini-omni-1.2-flash 时,使用 Google Interactions API 请求视频输出,并分别检查三件事:交互完成、文件就绪、下载后的媒体通过验收。 API 返回完成,不等于你已经拿到可播放的视频。文件还在处理时重新生成,可能增加不必要的任务和费用。
本文用一个小型文生视频请求走完这条流程,提供可下载的 Python 程序、恢复命令和本地媒体校验器,再说明加入参考素材、编辑和续接后哪些设置需要变化。官方文档核对日期为 2026 年 11 月 15 日。
本文由 Ofox 发布。验证依据是使用合成响应和实际 Google SDK 完成的 24 项辅助函数与运行程序离线测试,以及用自行通过 FFmpeg 生成的素材完成的 10 项本地媒体校验测试。未执行真实 Omni 生成、模型画质对比、延迟测量或账单测试。联网程序是经过离线验证的接入模板,不代表已成功完成一次真实 Google 全流程调用;本文也没有把合成测试视频当作 Omni 输出展示。
本文引用的 Google 官方文档为英文。
先确定模型与 API 路径
当前 Google 模型说明列出了 gemini-omni-1.2-flash:输入支持文本、图片和视频,输出支持视频与原生音频。不要换成纯文本 Gemini 模型,也不要沿用旧 Veo 请求格式。站内的 Veo 3.1 API 教程 (英文)讲的是另一种模型接入。
准备具有模型访问权限、且已配置必要账单或额度的 Google 项目。按 Google 的 API Key 文档获取和管理密钥。订阅面向消费者的应用,并不能证明某个 API 项目可以发起调用。通过正常的密钥管理方式设置 GEMINI_API_KEY,不要把密钥放进提示词或公开排错日志。
本文调用 Google 的 https://generativelanguage.googleapis.com/v1beta/interactions。Ofox 有独立的视频任务 API,以及创建任务、查询状态和鉴权说明。这些文档适用于使用 Ofox 已支持的视频模型时的接入,不能与下面的 Google 请求互换。本文不据此确认 Ofox 已支持 Omni,也不提供 Ofox 的 Omni 报价。

Google 英文官方文档的真实截图,已裁去账号信息。它展示的是产品说明,不是生成结果或 Ofox 接入实测。
Google 公布的别名切换时间是 2026 年 12 月 3 日:gemini-omni-1.1-flash 届时路由到 1.2。在本文核验日期,该日期尚未到来。本示例直接指定 1.2,不依赖未来的别名变化。模型说明同时将 gemini-omni-flash-preview 标为已关闭。
安装完整程序,先跑离线检查
下载 Omni 视频示例包,解压并进入 omni-video-kit 目录。里面包含联网运行程序、结果处理辅助函数、媒体校验器、两个测试模块和英文 README,无需从零散片段拼装主程序。
使用 Python 3.11 或更新版本,建立隔离环境:
python -m venv .venv
source .venv/bin/activate
python -m pip install 'google-genai==3.3.0' httpx
python -m unittest test_video_result.py test_runner_offline.py -v
Windows PowerShell 使用 .venv\Scripts\Activate.ps1 激活。安装依赖会访问软件包仓库;测试本身使用合成数据、模拟服务响应,运行程序测试还阻止网络连接,不需要 Google 密钥。预期结果是 24 项测试通过。
辅助函数测试覆盖交互完成与未完成、URI 校验、文件处理状态和有次数上限的轮询。运行程序测试检查已安装 SDK 实际序列化的请求、通过 GET 恢复、超时与服务错误、保留部分下载,以及不覆盖并发创建的输出文件。模拟 503 或超时时,尤其要确认只发出一次创建 POST,没有自动重复提交。
媒体校验器是另一层检查,需要从可信包管理器或官方发行渠道安装 ffmpeg 和 ffprobe。真实调用前先确认两个命令均可用。校验器的本地测试使用生成的图案与声音、静音音轨、损坏文件,以及刻意制造的不一致轨道时长;通过这些测试证明的是校验器的行为,不是模型输出质量。
用明确参数生成一个小视频
先只安排一个主体、一种运动和固定机位,方便判断是否遵循提示词。程序使用的英文提示词表达的是:
一片绿叶从左向右漂过平静的池塘。固定广角镜头,柔和日光。安静的自然水声,不要人声、音乐或文字。
预期目标是带自然水声的 3 秒、横屏、720p 视频。这是请求目标,不是我们观察到的实际结果。完整程序中的创建调用如下:
interaction = client.interactions.create(
model="gemini-omni-1.2-flash",
input=(
"A single green leaf drifts across a still pond from left to right. "
"Fixed wide shot, soft daylight. Quiet natural water sounds, "
"no speech, no music, no text."
),
response_format={
"type": "video",
"delivery": "uri",
"duration": "3s",
"resolution": "720p",
"aspect_ratio": "16:9"
},
store=True,
timeout=180,
automatic_continuation=False
)
这段代码依赖 run_live.py 中的客户端和恢复处理,请执行完整脚本。脚本配置 HTTP 超时,并通过 retry_options.attempts=1 禁用 SDK 自动重试;还会在提交请求之前预留本地恢复记录。这些措施用于避免服务器结果未知时重复创建,不能保证任意基础设施中的“恰好执行一次”。
设置自己的 Google 项目密钥后,运行以下命令会发出真实请求,可能消耗额度或产生费用:
python run_live.py --create --out leaf.mp4
这里有意使用 store=True,以便后续获取结果,并在编辑会话中继续使用。Google 的 Omni 指南也介绍了关闭存储的同步单次生成,但这样无法再通过 previous_interaction_id 继续编辑,不应直接套用到本示例的可恢复流程。
URI 交付避免把大视频直接塞进 JSON 响应,但不代表所有生成都必须作为后台任务执行。生成模式、交互完成和文件就绪是不同问题。下面按程序处理的状态解释,而不是把每一次等待都变成新的生成请求。
区分交互完成、文件就绪与下载恢复
收到响应后,程序会保存 leaf.mp4.interaction.json,并打印交互 ID 和状态。它是私有恢复记录,可能包含内容或媒体数据,不能单凭这个文件认定视频已经完成。
| 阶段 | 程序检查什么 | 应保留什么或下一步做什么 |
|---|---|---|
| 已提交创建,但结果未知 | 即使未拿到 ID,本地待确认记录也存在 | 再次创建前检查账号或服务方记录 |
| 交互已返回 | 状态为 completed、无报告错误且有视频输出 | 保留交互 ID 与响应 |
| 视频通过 URI 交付 | URI 对应预期的 Google 文件资源 | 轮询该资源,不把文件 URI 当成新任务 ID |
| 文件处理中 | PROCESSING、ACTIVE 或 FAILED | 处理中等待,就绪后下载,失败或未知状态时停止 |
| 下载传输中 | 字节写入新的 .part 文件 | 失败时保留部分数据,不把它当成成品 |
| 本地文件交付 | 非空结果写入,且不替换已有输出 | 使用前完成媒体与内容验收 |
辅助函数只接受文档对应的 HTTPS Google 文件来源与资源路径。它会将 /v1beta/files/...:download?alt=media 这样的下载 URI 转为 Files API 使用的 files/... 名称。带凭据或指向无关来源的 URL 会被拒绝,不会任意抓取输出里的链接。鉴权由 SDK 处理,复制下载 URL 时不应夹带密钥。
示例最多检查文件状态 60 次,间隔 5 秒;HTTP 超时为 180 秒。这代表轮询次数上限和单次请求超时,不是五分钟内必然结束的总任务期限,也不是生成延迟承诺。传输错误会向上抛出,不会触发重新生成。目前程序选取 SDK 的第一个视频输出;应用若需要多个输出,应相应修改并测试。
要恢复已有交互,请使用真正返回的 ID:
python run_live.py --resume YOUR_INTERACTION_ID --out recovered-leaf.mp4
这会执行读取 GET,而不是创建 POST。它不会持续轮询未完成的交互;请检查保存的状态,必要时稍后重新读取。如果首次请求超时且没有收到 ID,脚本无法发现服务器上那次未知操作。待确认记录会阻止同名输出的再次创建,应先调查原请求,不要靠换文件名绕过保护。
已有输出或 .part 文件会让程序在提交前停止。下载失败时,部分文件和恢复记录可能保留下来。恢复一个已知存在的交互时,可像上面一样选择新的输出名。最终写入使用同目录硬链接,再删除 .part,从而避免覆盖并发产生的文件。文件系统不支持该操作时,保留完整的部分文件并处理本地写入问题,不要为了文件系统错误再生成一次视频。
先检查文件,再看画面、听声音
程序报告文件保存后,执行本地媒体检查:
python verify_video.py leaf.mp4 --seconds 3 --require-audio
校验器要求文件非空、存在尺寸有效的普通视频流、时长为正,并在指定时要求音频流。它会检查容器和每条普通视频轨道的时长,采用为本示例选择的 0.25 秒容差,再通过 FFmpeg 解码普通视频轨道与音频。如果缺少轨道时长元数据,严格检查会失败,不会悄悄用容器时长代替。
轨道检查很重要:3 秒的容器可能只有 1 秒视频和 3 秒音频,只看容器就会漏掉画面不足。同理,有音频流也可能全是静音。校验器判断的是音轨存在,不是声音可听、音画同步或艺术质量。
针对绿叶示例,再单独完成观看验收:
| 验收问题 | 具体检查 | 未通过时怎么做 |
|---|---|---|
| 主体是否正确? | 池塘上有一片绿叶,没有无关主体 | 调整一个主体约束并记录新尝试 |
| 运动是否正确? | 叶子从左向右,机位固定 | 在提示词中区分主体运动与镜头运动 |
| 片段是否连续? | 无意外切镜、闪烁或突兀结束 | 编辑或重生成前比较开头、中间与结尾画面 |
| 声音能否使用? | 能听见水声,无多余人声或音乐 | 实际听音,不能只以音轨存在判通过 |
| 是否适合目标用途? | 构图符合要求、主体清楚、无多余文字 | 在实际目标版式中检查,而非只看文件元数据 |
我们没有生成或评分真实绿叶视频。以上是供你获准执行时使用的验收标准。保留提示词、精确参数和实际结果,便于比较第二次尝试。能成功解码只是技术节点,不能据此宣称模型已完成创作要求。
按任务选择参考素材、编辑和续接参数
模型规格和 Omni 任务文档对不同模式规定了不同限制,不能把新生成的最长时长套到所有操作上。
| 操作 | 文档规定 | 对实际使用的影响 |
|---|---|---|
| 新生成视频 | 3–15 秒的整数秒,默认 10 秒 | 为可复现的小样明确指定时长 |
| 首尾帧插值 | 3–10 秒 | 两张端点帧不能用于 15 秒插值 |
| 图片参考 | 各时长最多六张 | 说清每张参考的作用 |
| 新生成的视频参考 | 输出 3–10 秒时最多三段,11–15 秒时一段;每段参考最多 3 秒 | 参考数量与最终视频时长分别计算 |
| 编辑输入视频 | 最长 15 秒 | 不合适的输入先裁剪或拆分 |
| 续接 | 每轮新增 3–10 秒,总长最多 30 秒;上下文取最后 10 秒 | 跟踪总长,并重新说明较早的重要细节 |
| 分辨率 | 360p、720p、1080p、4k;默认 720p | Google 将 1080p 与 4K 标为上采样,不要称原生拍摄 |
用自然语言说明图片中需要保留的特征,以及视频怎样影响新镜头。视频参考中的音频会被忽略;视频参考只适用于新生成,不适用于编辑或续接。原生音频输出不代表支持上传音频输入或音频参考,也不支持人声编辑。
Google 还说明,不支持跨多段视频进行引用或推理,多视频提示可能出现效果下降或意外结果。上表的参考数量限制不等于保证可靠的跨视频推理。
第一次加入图片参考时,可明确说明参考角色,不使用过时的控制标签:
Create a 5-second landscape shot.
Use the attached image as the appearance reference for the green leaf.
Keep its shape and color consistent.
The leaf drifts from left to right across still water.
Keep the camera fixed, with soft daylight and gentle water sounds.
Do not add speech, music, captions or extra leaves.
模板的意思是:生成 5 秒横屏镜头,以附图作为绿叶外观参考,保持形状与颜色,叶子向右漂、机位固定,使用日光和水声,不添加人声、音乐、字幕或其他叶子。你仍须按文档的媒体输入格式附上真实图片,文字写“附图”并不会上传文件。确认有权使用素材,且账号支持目标操作。Google 建议先尝试清晰的自然语言角色说明,再考虑强制 video_config.task,因为后者可能限制可接受的媒体组合。
要编辑此前生成且已存储的视频,可将以下独立示例保存为 edit_saved_video.py,通过 OMNI_PREVIOUS_INTERACTION_ID 读取真实的上一轮 ID。这是可能产生费用的新编辑操作,不是离线测试,也不是恢复下载命令:
import os
from pathlib import Path
from google import genai
client = genai.Client(
api_key=os.environ["GEMINI_API_KEY"],
http_options={"timeout": 180000, "retry_options": {"attempts": 1}}
)
try:
edit = client.interactions.create(
model="gemini-omni-1.2-flash",
previous_interaction_id=os.environ["OMNI_PREVIOUS_INTERACTION_ID"],
input="Make the daylight warmer. Keep the leaf, its motion and the camera framing unchanged.",
response_format={"type": "video", "delivery": "uri"},
store=True,
timeout=180,
automatic_continuation=False
)
Path("edit-interaction.json").write_text(edit.model_dump_json(indent=2))
print(edit.id, edit.status)
finally:
client.close()
在同一激活环境与示例包目录中,保留 GEMINI_API_KEY,设置要编辑的视频所属交互 ID。macOS 或 Linux:
export OMNI_PREVIOUS_INTERACTION_ID='YOUR_STORED_GENERATION_ID'
python edit_saved_video.py
Windows PowerShell 使用 $env:OMNI_PREVIOUS_INTERACTION_ID = 'YOUR_STORED_GENERATION_ID',再运行 python edit_saved_video.py。占位符必须换成真实生成交互 ID,不是 Files API 的文件资源名。保密保存 edit-interaction.json,再次运行前先留存本次记录。
成功收到响应后,用返回的新交互 ID 执行 run_live.py --resume,指定新的输出名,再做媒体与画面验收。与完整生成程序不同,这个短编辑示例没有在 POST 前预留待确认记录。如果超时且未收到 ID,应先调查账号记录,不要假定编辑没有发生。本文没有执行该真实编辑调用,也没有执行真实续接。
上传视频的编辑或续接在欧洲经济区、瑞士和英国有区域限制,与模型生成视频的编辑或续接不同。续接只追加在末尾,不能插入中间或前置。对本来就有人声的上传视频添加对白也有限制;此前生成视频的多轮语音续接则有单独说明。请检查具体操作的限制,不要把“支持视频编辑”理解为所有操作都可用。
在实际失败的环节排错
先收集准确模型、端点、SDK 版本、脱敏错误正文,以及已有交互 ID 或文件标识。站内 Gemini 4 API 错误排查说明了如何区分鉴权、访问权限、请求格式和额度问题。该文模型示例是 Argon;本文仍需使用 Omni ID 和视频请求格式。
| 症状 | 应检查的环节 | 下一步 |
|---|---|---|
| HTTP 200,但解析不到视频 | 响应格式或交互尚未完成 | SDK 的 output_video 是便利属性;原始 REST 视频内容位于 steps |
| 首尾帧请求报时长无效 | 特定操作的参数限制 | 改为该模式支持的时长,不重复同一无效请求 |
| 某个生成设置被拒绝 | 不支持的参数 | 删除不支持的系统指令、temperature、top_p、停止序列或独立负面提示字段,约束写入普通提示词 |
| 交互完成,文件仍处理中 | 文件就绪状态 | 继续查询原文件,不重新生成 |
文件状态 FAILED 或未知 | 服务处理失败或格式变化 | 停止并保留证据,不把“不是处理中”都当成功 |
| 客户端超时,不知道是否已创建 | 传输与服务器执行的区别 | 保留待确认记录,再次 POST 前先调查 |
| 下载成功,但校验失败 | 媒体字节、轨道或本地工具 | 检查文件和校验器输出,再决定重新获取还是生成 |
| 上传视频操作不可用 | 区域、素材类型或政策限制 | 核对账号与操作限制,不盲目更换凭据 |
安全过滤拒绝时,应在服务允许的范围内调整请求,而不是重复提交被拦截的提示词。不要在公开示例中使用临时或带凭据的 URL。使用 Ofox 独立协议的应用应参考其视频错误码和通用重试说明,它们不能代替 Google 的错误协议。
保存任务记录后再扩大使用
每次真实尝试都应记录模型 ID、提示词版本、参考素材标识、时长、分辨率、画幅、存储选择、交互 ID、文件资源、本地输出哈希和验收结果。共享报告中不要出现密钥或私有内容。区分恢复已有工作的 GET 和创建新工作的 POST;把所有请求都算作新生成,会干扰排错与成本分析。
估算费用前,按具体模式和分辨率核对 Google 当前的 Omni 价格。本文没有真实生成账单或 Ofox 报价。用量已知时,分别记录失败尝试、编辑和续接,未知用量不能填零。即使初稿更短,多次付费修改也可能抬高总任务费用,应比较最终验收通过的整条流程,而不是单次请求。
先完成一个验收通过的小样,再逐项增加复杂度:一张参考图、不同画幅、已存储视频的编辑或续接。保留原来可用的设置用于比较。只有真实账号能够生成、获取并验收所需结果后,再扩大使用。交付物是可用视频及其验收记录,不只是“生成已完成”的模型消息。


