gemini-omni-flash-api

Gemini Omni Flash 技能

此技能使用 Gemini Omni 1.1 Flash 模型（gemini-omni-1.1-flash）执行文本生成视频、图像生成视频（首帧与末帧过渡）、视频扩展（最长 40 秒）和视频编辑。

警告

重要的区域限制：在欧洲经济区、瑞士、英国和美国部分州，无法上传用于视频编辑或扩展的视频。如果视频转视频编辑很快完成，但输出为空（total_output_tokens: 0 或没有视频内容），很可能是受到此限制影响。

核心功能

1. 文本生成视频：根据文本提示词生成视频。
2. 首帧生成视频：根据起始图像生成视频（--first-frame）。
3. 首帧与末帧过渡：生成在起始图像与最终图像之间插值过渡的视频（--first-frame 和 --last-frame；注意：--last-frame 必须与 --first-frame 搭配使用）。
4. 视频扩展：每轮最多将现有视频延长 10 秒，总时长最长可达 40 秒（--extend 或 --previous-interaction-id）。
5. 视频编辑与优化：编辑现有视频（最长 10 秒），应用风格变更，或执行修补/扩图。
6. 基于图像和视频参考的生成：使用图像或视频中的风格、角色或物体作为参考，引导视频生成。

工作流

1. 分析请求：确定目标任务（例如首帧生成视频、首帧与末帧过渡、视频扩展、参考引导编辑），并识别输入媒体素材。

2. 运行 SDK 脚本：

   • 直接运行相应的实用工具（scripts/video/generate_video.py 或 scripts/upload_file.py）。
   • 配置 --aspect-ratio（例如 16:9、9:16）、--resolution（360p、720p、1080p、4k；默认值：720p）和 --duration（3 到 10 秒之间的任意整数，例如 3、5、10）。注意：4k 请求的生成时间更长。

3. 获取并处理输出：输出会保存到本地文件系统（例如 media/）。向用户报告已完成媒体的路径。

参考文档

• Interactions API：Gemini Omni 1.1 Flash 模型（gemini-omni-1.1-flash）的所有操作和状态管理均通过 Interactions API 处理。
• Files API：输入媒体文件（例如参考图像和视频）必须先通过 Files API 上传，才能在生成时引用。随后将上传文件的 URI 和 MIME 类型包含在 interactions.create 的 input parts 数组中。
• Gemini API 技能参考：Gemini API 的平台级指南、当前模型规格和 SDK 使用规则。

依赖项和先决条件

• Python SDK（google-genai）：需要 google-genai >= 2.19.0（Python），以支持 interactions 客户端和完整的视频输出分辨率配置（360p、720p、1080p、4k）。使用以下命令安装或升级：

  pip install -U google-genai
  

• Python 运行时：需要 Python >= 3.10（以兼容新版 google-genai SDK 类型和方法）。
• ffmpeg 和 ffprobe：prep_video.py、inspect_video.py，以及在通过 --strip-audio 去除音频时使用的 generate_video.py，均要求安装 ffmpeg 和 ffprobe 二进制文件，并确保它们位于系统 PATH 中。
• API 密钥：设置 GEMINI_API_KEY 环境变量：

  export GEMINI_API_KEY="your-api-key"
  

可用脚本

使用以下 Python 脚本，通过 Files API 上传媒体、使用 ffmpeg 准备输入视频，并通过 Interactions API 生成视频输出。

1. upload_file.py：将本地媒体（图像和视频）上传到 Files API，并持续轮询，直到状态变为 ACTIVE。如果上传的视频大于 25MB，脚本会打印一条提示，说明 Gemini Omni Flash 针对以 720p/24fps 编辑 10s 视频进行了优化，并建议先使用 prep_video.py 进行预处理，以加快上传速度。

   ./scripts/upload_file.py path/to/image.png
   

2. generate_video.py：端到端生成视频并下载输出视频。调用 Interactions API 前，脚本会检测并上传本地媒体引用（图像或视频）。大型视频素材（>25MB）会触发预处理建议，但不会阻止上传。

   • 文本生成视频：

     ./scripts/video/generate_video.py "A close-up of a cat drinking tea" --output media/cat_tea.mp4
     

   • 输出分辨率选项（--resolution）：

     Gemini Omni 1.1 Flash 原生支持横向（16:9）和纵向（9:16）宽高比下的四种输出分辨率：

     • 360p：640x360（16:9）或 360x640（9:16）
     • 720p：1280x720（16:9）或 720x1280（9:16）— （默认）
     • 1080p：1920x1080（16:9）或 1080x1920（9:16）
     • 4k：3840x2160（16:9）或 2160x3840（9:16）

     # 高清（1080p）
     ./scripts/video/generate_video.py "A cinematic drone shot over misty mountains at sunrise" --resolution 1080p --output media/mountains_1080p.mp4
     
     # 超高清 4K（注意：4K 请求需要更长的生成时间；如有需要，请传入 --timeout）
     ./scripts/video/generate_video.py "A macro shot of a dewdrop on a flower petal in golden sunlight" --resolution 4k --timeout 900 --output media/flower_4k.mp4
     

   • 可配置的请求超时（--timeout）：

     HTTP 超时默认为 600 秒（10 分钟）。对于计算密集型请求，例如将 30s 的视频延长 10s（视频总时长最多为 40s），生成可能需要几分钟。使用 --timeout 900（或 1200）可延长执行时间。

   • 首帧生成视频：

     ./scripts/video/generate_video.py "The waves crash against the shore." --first-frame start.png --output media/waves.mp4
     

   • 首帧与尾帧过渡：

     提供起始帧和结束帧，以生成两者之间的平滑过渡（注意：--last-frame 必须与 --first-frame 一起使用）：

     ./scripts/video/generate_video.py "A smooth timelapse from sunrise to sunset" --first-frame start.png --last-frame end.png --output media/interpolation.mp4
     

   • 循环视频（首尾帧相同）：

     ./scripts/video/generate_video.py "A crystal orb spinning continuously in place" --first-frame orb.png --last-frame orb.png --output media/loop.mp4
     

   • 基于图像引用生成视频：

     ./scripts/video/generate_video.py "A cybernetic warrior in the style of <IMAGE_REF_0>" --image reference.png --output media/warrior.mp4
     

   • 基于视频引用生成视频：

     提供一个或多个参考视频（--video-reference / -vr），以引导角色、物体或动作风格（理想时长约为 3s，建议最多使用 3 个参考视频）：

     ./scripts/video/generate_video.py "A musician playing cello in the style of <VIDEO_REF_0>" --video-reference ref_dance.mp4 --output media/cello.mp4
     

   • 延长视频（延长现有视频）：

     将现有视频延长最多 10 秒（总时长最多为 40 秒）：

     ./scripts/video/generate_video.py "The scene continues as the sun sets over the horizon" --extend media/sunset.mp4 --output media/sunset_extended.mp4
     

   • 使用参考图像和参考视频延长视频： 基于提示词的扩展支持同时传入参考图像和参考视频：

     ./scripts/video/generate_video.py "Extend this video. The character in <IMAGE_REF_0> enters dancing like the dancer in <VIDEO_REF_0>." --extend media/sunset.mp4 --image character.png --video-reference dance_ref.mp4 --output media/sunset_extended_with_refs.mp4
     

   • 视频编辑（保留原始音频）：

     ./scripts/video/generate_video.py "Transform the style to Japanese anime" --video input.mp4 --output media/anime_style.mp4
     

   • 视频编辑（从头重新生成所有音频）：

     ./scripts/video/generate_video.py "Transform the style to Japanese anime" --video input.mp4 --strip-audio --output media/anime_style_new_audio.mp4
     

   • 逐轮视频编辑（编辑此前的交互）：

     通过传入交互 ID，无需重新上传素材即可编辑先前生成的视频：

     ./scripts/video/generate_video.py "Change the setting to a snowy winter wonderland." --previous-interaction-id "v1_..." --output media/winter_wonderland.mp4
     

   • 逐轮视频扩展（扩展此前的交互）：

     通过传入此前的交互 ID，扩展先前生成的视频：

     ./scripts/video/generate_video.py "Extend this video. The character turns around and begins to run." --previous-interaction-id "v1_..." --output media/extended_turn.mp4
     

   • 并行批量执行（提示词文件）：从逐行排列的文本文件中读取多个提示词并发执行：

     ./scripts/video/generate_video.py --prompts-file prompts.txt --concurrency 3
     

   • 并行批量执行（JSON 配置）：并行执行完全配置且各不相同的生成和编辑任务：

     ./scripts/video/generate_video.py --batch jobs.json --concurrency 3
     

     jobs.json 示例：

     [
       {
         "prompt": "A smooth timelapse from sunrise to sunset.",
         "first_frame": "start.png",
         "last_frame": "end.png",
         "resolution": "1080p",
         "output": "media/interpolation.mp4"
       },
       {
         "prompt": "Extend this video. The scene continues with the character in <IMAGE_REF_0> dancing like <VIDEO_REF_0>.",
         "extend": "media/sunset.mp4",
         "image": "character.png",
         "video_reference": "dance_ref.mp4",
         "output": "media/extended_with_refs.mp4"
       },
       {
         "prompt": "A macro shot of a crystal orb refracting cosmic nebula colors.",
         "resolution": "4k",
         "output": "media/nebula_orb_4k.mp4"
       },
       {
         "prompt": "A musician playing cello in the style of <VIDEO_REF_0>.",
         "video_reference": "cello_ref.mp4",
         "output": "media/cello.mp4"
       },
       {
         "prompt": "Transform the style to Japanese anime.",
         "video": "input.mp4",
         "output": "media/anime_style.mp4",
         "strip_audio": false,
         "aspect_ratio": "16:9"
       }
     ]
     

3. inspect_video.py：检查本地视频文件（使用 ffprobe），查看其时长、分辨率、帧率（FPS）、音频流是否存在以及格式详情。

   ./scripts/video/inspect_video.py media/output.mp4
   

   • 获取预解析的结构化 JSON 摘要：

     ./scripts/video/inspect_video.py media/output.mp4 --json
     

   • 获取完整且未经修改的 ffprobe 原始 JSON 转储：

     ./scripts/video/inspect_video.py media/output.mp4 --raw
     

4. prep_video.py：规范化、剪辑并转换任意视频文件的格式，使其符合 Gemini Omni Flash 的标准生成和编辑限制。它支持按时间码剪辑、可选的帧率转换，并按比例缩小大型视频（横向视频最大为 1280x720，纵向视频最大为 720x1280），以缩短上传时间且不拉伸画面。如果视频超过 10 秒，且脚本在交互式终端（TTY）中运行，它会提示用户选择前 10 秒、后 10 秒，或输入自定义时间码（默认为前 10 秒）。

   • 剪辑前 10 秒（默认）：

    ./scripts/video/prep_video.py path/to/source.mp4
   

   或显式指定起始时间和时长：

   ./scripts/video/prep_video.py path/to/source.mp4 --start 0 --duration 10
   

   • 剪辑后 10 秒（根据源视频时长自动计算起始位置）：

     ./scripts/video/prep_video.py path/to/source.mp4 --start last
     

   • 从指定时间码开始剪辑 10 秒（MM:SS 或 HH:MM:SS）：

     ./scripts/video/prep_video.py path/to/source.mp4 --start 00:03 --output media/custom.mp4
     

   • 自定义帧率和分辨率：

     ./scripts/video/prep_video.py path/to/source.mp4 --fps 30 --resolution 1920x1080
     

   • 移除音频以重新生成音频：

     ./scripts/video/prep_video.py path/to/source.mp4 --strip-audio --output media/video_with_no_audio.mp4
     

视频编辑中的音频处理

编辑包含音频的源视频时，必须选择保留原始音频，或从头重新生成所有音频。

• 保留原始音频：默认情况下，Gemini Omni Flash 会保留现有音轨（不过在生成过程中可能会稍作修改或调整）。如果需要保留原始背景音乐、对白或音效，请使用此选项。

• 从头重新生成所有音频：如果希望 Gemini Omni Flash 根据新的视觉风格或提示词重新创建全新的音轨，必须上传已移除音频流的视频。如果存在任何音频流，Gemini Omni Flash 会尝试保留或修改它，而不是从头开始生成。

  • 使用 --strip-audio（或 -a）通过 scripts/video/prep_video.py 预处理视频，或运行 scripts/video/generate_video.py。
  • 这会让 Gemini Omni Flash 完整生成音频。

为 Gemini Omni Flash 编写提示词

单个场景

默认情况下，Gemini Omni Flash 会尝试生成包含多个不同镜头的视频，并根据提示词创作有趣的叙事。

如果需要生成的视频只包含单个场景，必须在提示词中明确说明：

• 一个不中断的场景
• 一个连续镜头
• 不要切换场景

例如：

Continuous, unbroken handheld shot of a fluffy tabby cat sitting on a sunny windowsill, looking out into a leafy garden. The cat's tail twitches slowly, and its ears rotate slightly toward ambient noises. Sunbeams illuminate dust motes in the air. Sound design: Gentle breeze, distant bird chirps. No dialogue.

移除不需要的元素

如果生成的视频包含不需要的内容，可以添加简单的负面提示词来避免这些内容：

• 不要对白
• 不要额外修饰
• 不要额外音效

用于编辑的提示词

简单的提示词最适合视频编辑。描述过于繁琐可能会导致意料之外的更改。

以下是更多简单编辑提示词示例：

• 把这个视频变成动漫风格
• 给这个人戴上一顶时髦的帽子
• 把灯光调得更有戏剧性
• 把招牌上的文字改成“Omni Flash”

编辑视频的特定部分时，加入 "Keep everything else the same"，以保持视觉一致性。

以下是一些示例，说明如何运用这一技巧：

• 避免： 在这个男人坐在沙发上的视频中，请添加一只小黑猫，让它从画面右侧跑来，跳到他腿上，然后他低头开始抚摸它的头。
  • 简化： 添加一只跳到他腿上的猫，他开始抚摸它。其他内容保持不变。
• 避免： 请移除这个人手里拿着的手机，并补全背景，让他看起来像是空手拿着手。
  • 简化： 让手机消失。其他内容保持不变。

音频提示词

默认情况下，模型会尝试为视频生成合适的音轨。这不一定总是符合你的需求。你可以在提示词中描述想要的音频类型。如果你希望视频中包含音乐，这一点尤其重要：

• 加入平静的背景音乐
• 视频配有节奏强劲的电子音乐
• 背景音频是低沉、音质单薄的电台广播，正在播放一首歌

定时事件

你可以提示模型让事件在视频的特定时间发生，不需要精确的语法，可以使用自然语言。这对自行设计场景切换、节奏或快速连续镜头特别有用。以下是一些示例：

• 3 秒后，一位女士进入场景。
• 5 秒时，背景音频中开始播放副歌。
• 每隔 2 秒切换到一个新画面。
• 采用快速连续镜头，每半秒（24 fps 下为 12 帧）将场景切换到一个新地点。

你也可以使用时间码语法：

[0-3s] A person is walking
[3-6s] They stop and turn around
[6-10s] They start running

元提示

你可以让 Gemini Omni Flash 留意视频生成的一般特征或原则：

• 考虑微观细节、表情和时机，创作一个非常丰富、细致又完全自然的场景。
• 极其细致地描述角色和环境。运用服装设计原则塑造角色。具体描述场景中的人物、物品和对象。
• 在背景元素中加入充足且恰当的细节，让场景显得真实自然。
• 制作一段快速连续的视频，每 1 秒展示一个不同的稀有 [thing]，配上欢快的音乐，并加入文字为该事物标注名称。

视频中的文字

你可以提示模型在视频中加入文字，Gemini Omni 会以正确且易读的方式呈现。如果视频中会自然出现文字（包括背景元素中的文字），明确指定文字内容会有所帮助。

• 屏幕上每次只显示一个词：“did, you, know, that, Omni, can, do, awesome, text?” 每个词显示 1 秒，采用不同的动画样式。没有对白。
• 有一块街道路牌写着：“This is an AI generation by Omni”，有一家店面写着：“All you need AI”，还有一辆车的车牌号是：“OMNI1.1”

用于扩展视频的提示词

使用 Gemini Omni 1.1 Flash，你可以通过 "Extend this video" 或 "The scene continues" 之类的提示词扩展视频。每次可以将视频延长 10s，最长可达 40s。

Omni 会将原始视频的最后 10s 用作上下文，生成与视频、动作、角色和音频保持连贯的扩展内容。输入视频的一些末尾帧会经过编辑，以实现无缝衔接。

提示

使用参考内容进行扩展：可以仅使用提示词（例如 "Extend this video"、"The scene continues"）扩展视频，而无需设置 API 的 task="extend" 参数。省略 task 参数后，扩展视频时可以传入参考图片（--image）和参考视频（--video-reference），将新角色、物体或风格无缝融入扩展场景。如果明确设置了 task="extend"，则不能传入多模态参考内容。

扩展视频时，本指南中的所有 Omni 提示词技巧仍然适用：

• 描述扩展场景中的音频，尤其是在需要改变音频时，例如 "The music continues into the chorus"
• 描述场景是继续发展，还是切换镜头进入新场景（也可以保留相同角色），例如 "Show the same characters in the next scene"
• 扩展时加入图片和视频作为参考，有助于确保输出准确，或引入新角色，例如 "The person shown in the reference image enters the scene"、"The dog in the reference video <VIDEO_REF_0> jumps onto the sofa"
• 如果使用时间戳或时间码语法，0s 指扩展视频部分的开头。如果扩展一段 10s 的视频，这条提示词中的场景切换会在 12s 后发生："After 2s cut to a new scene with the same characters"

视频扩展的限制与指南

• 时长限制：上传用于扩展的输入视频时，时长必须不超过 10 秒（多轮交互除外）。
• 上传视频中的口语对白：目前，如果上传的视频中有人说话，则无法通过扩展视频为其添加更多对白（如果角色保持沉默，或提示词不添加对白，则支持扩展）。
• 多轮语音扩展：通过多轮交互（previous_interaction_id）扩展之前生成的视频时，支持生成口语对白或语音。
• 任务参数建议：我们建议主要依靠提示词，仅在单靠提示词不起作用且需要帮助模型理解应使用哪种模式时，才使用 task="extend" 参数，因为设置 task 字段会增加限制（例如禁用多模态参考输入）。

在提示词中使用标签设置图片和视频的角色

你可以使用标签，将上传的媒体关联到特定的生成角色。这样，你就能指定每张图片或每个视频是起始帧、结束帧还是参考内容。

简单标签（推荐）

对于媒体角色在提示词中明确的简单情况，你可以直接将图像和视频绑定到相应角色：

• <FIRST_FRAME>：将图像用作视频的起始帧，例如：<FIRST_FRAME> a woman is walking
• <LAST_FRAME>：将图像用作视频转场到的最终帧。必须与 <FIRST_FRAME> 一起使用，例如：<FIRST_FRAME> <LAST_FRAME> a woman is walking
• <IMAGE_REF_N>：将图像用作参考，例如：in the style of <IMAGE_REF_0> a woman <IMAGE_REF_1> is walking（结合第一张图像的风格参考和第二张图像的主体参考）。图像参考从 0 开始编号。
• <VIDEO_REF_N>：将视频用作角色或物体参考，例如：the person in <VIDEO_REF_0> is playing the violin。视频参考也从 0 开始编号。

说明

参考视频指南：

• 时长：理想的参考视频时长约为 3 秒，更长的视频也可以。如果要将较长的源文件裁剪为参考时长，可以使用 prep_video.py --duration 3。
• 数量：理想情况下最多使用 3 个参考视频，也可以使用更多。

以下是一个包含 6 张参考图像的示例：

[0-3s] A studio fashion sequence. Starting with woman <IMAGE_REF_0>, she is holding <IMAGE_REF_1>
[3-6s] Then we see the man <IMAGE_REF_2> holding <IMAGE_REF_3>
[6-10s] And finally another woman <IMAGE_REF_4> who is holding <IMAGE_REF_5> while walking.

声明源和参考

对于包含多个媒体输入和多个角色的复杂情况，你可以使用显式前缀标签并搭配自然语言指令。请在提示词开头声明这些源和参考。

• [# Sources <FIRST_FRAME>@Image1] 将使用第一张图像作为起始帧。
• [# Sources <FIRST_FRAME>@Image1 <LAST_FRAME>@Image2] 将使用第一张图像作为起始帧，第二张图像作为最终帧。
• [# Sources <FIRST_FRAME>@Image1 <LAST_FRAME>@Image1] 将使用第一张图像同时作为起始帧和最终帧，生成循环播放的视频。
• [# Sources <FIRST_FRAME>@Image1] [# References <IMAGE_REF_0>@Image2] 将使用第一张图像作为起始帧，第二张图像作为参考。
• [# Sources <VIDEO_0>@Video1] 将使用该视频作为主要源视频进行编辑或修改。
• [# Sources <PREVIOUS_VIDEO>@Video1] 将使用上一轮的视频进行延展。
• [# References <IMAGE_REF_0>@Image1] 将使用第一张图像作为参考。
• [# References <IMAGE_REF_1>@Image2] 将使用第二张图像作为参考。
• [# References <IMAGE_REF_0>@Image1 <IMAGE_REF_1>@Image2] 将使用两张图像作为参考。
• [# References <VIDEO_REF_0>@Video1] 将使用第一个视频作为参考。
• [# References <IMAGE_REF_0>@Image1 <VIDEO_REF_0>@Video1] 将同时使用图像和视频作为参考。

在提示词末尾添加引导指令：

• 对于起始帧："Use this image as the starting frame."
• 对于通过起始帧和结束帧创建的循环视频："Use this image as the first frame and the last frame."
• 对于参考图像："Use the given image(s) as references for video generation. The images should not be used as literal initial frames."
• 对于参考视频："Use the given video(s) as references. Do not use them as a source for video editing."

以下是一些包含源和参考声明的提示词示例：

[# Sources <FIRST_FRAME>@Image1] [# References <IMAGE_REF_0>@Image2] a woman <IMAGE_REF_0> is walking. Use Image1 as the starting frame. Use Image2 as a reference for the video generation.

[# References <IMAGE_REF_0>@Image1 <VIDEO_REF_0>@Video1] The woman in <VIDEO_REF_0> is playing the violin shown in <IMAGE_REF_0>. Use Video1 as a character reference and Image1 as an object reference.