用 Gemini Omni 1.1 Flash…

当需要通过 google-genai SDK 调用 gemini-omni-1.1-flash 完成文生视频、首帧/首尾帧生成、视频扩展（最长 40s）、视频编辑与参考图/参考视频引导生成时使用。

适用场景

解决思路

1. 先分析请求，确定目标任务（如首帧生视频、首尾帧过渡、视频扩展、参考引导编辑），并识别所有输入媒体素材。
2. 直接运行对应脚本：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/），完成后把媒体路径报告给用户。
4. 文生视频：./scripts/video/generate_video.py "A close-up of a cat drinking tea" --output media/cat_tea.mp4
5. 首帧生视频：./scripts/video/generate_video.py "The waves crash against the shore." --first-frame start.png --output media/waves.mp4
6. 首尾帧过渡：./scripts/video/generate_video.py "A smooth timelapse from sunrise to sunset" --first-frame start.png --last-frame end.png --output media/interpolation.mp4（--last-frame 必须与 --first-frame 一起使用）。
7. 循环视频（首尾帧相同）：./scripts/video/generate_video.py "A crystal orb spinning continuously in place" --first-frame orb.png --last-frame orb.png --output media/loop.mp4
8. 图像参考生成：./scripts/video/generate_video.py "A cybernetic warrior in the style of <IMAGE_REF_0>" --image reference.png --output media/warrior.mp4
9. 视频参考生成：用 --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. 视频扩展：用 --extend 扩展已有视频，每轮最多 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
11. 带参考图和参考视频的扩展：./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
12. 视频编辑（保留原音频）：./scripts/video/generate_video.py "Transform the style to Japanese anime" --video input.mp4 --output media/anime_style.mp4
13. 视频编辑（完全重新生成音频）：./scripts/video/generate_video.py "Transform the style to Japanese anime" --video input.mp4 --strip-audio --output media/anime_style_new_audio.mp4
14. 逐轮视频编辑（编辑上一次交互）：通过 --previous-interaction-id 传入交互 ID，无需重新上传素材：./scripts/video/generate_video.py "Change the setting to a snowy winter wonderland." --previous-interaction-id "v1_..." --output media/winter_wonderland.mp4
15. 逐轮视频扩展（扩展上一次交互）：./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
16. 并行批量执行（提示词文件）：./scripts/video/generate_video.py --prompts-file prompts.txt --concurrency 3
17. 并行批量执行（JSON 配置）：./scripts/video/generate_video.py --batch jobs.json --concurrency 3；jobs.json 为数组，每项可含 prompt、first_frame、last_frame、extend、image、video_reference、video、resolution、output、strip_audio、aspect_ratio 等字段。
18. 用 scripts/upload_file.py 上传本地媒体到 Files API 并轮询直到 ACTIVE：./scripts/upload_file.py path/to/image.png；上传大于 25MB 的视频时会提示 Gemini Omni Flash 针对 10s、720p/24fps 编辑优化，建议先用 prep_video.py 预处理以加快上传。
19. 用 scripts/video/inspect_video.py 检查本地视频的时长、分辨率、帧率、是否含音频流和格式：./scripts/video/inspect_video.py media/output.mp4；加 --json 得到结构化 JSON 摘要，加 --raw 得到完整未修改的 ffprobe 原始 JSON。
20. 用 scripts/video/prep_video.py 归一化、裁剪并格式化视频以符合 Gemini Omni Flash 的生成与编辑限制，支持按时间码裁剪、可选帧率转换和按比例缩放（横屏最大 1280x720，竖屏最大 720x1280）以优化上传且不拉伸；若视频超过 10 秒且脚本在 TTY 交互运行，会提示选择前 10s、后 10s 或输入自定义时间码（默认前 10s）。
21. 裁剪前 10s（默认）：./scripts/video/prep_video.py path/to/source.mp4，或显式指定：./scripts/video/prep_video.py path/to/source.mp4 --start 0 --duration 10
22. 裁剪后 10s：./scripts/video/prep_video.py path/to/source.mp4 --start last
23. 从指定时间码裁剪 10s（MM:SS 或 HH:MM:SS）：./scripts/video/prep_video.py path/to/source.mp4 --start 00:03 --output media/custom.mp4
24. 自定义帧率和分辨率：./scripts/video/prep_video.py path/to/source.mp4 --fps 30 --resolution 1920x1080
25. 去除音频以便重新生成：./scripts/video/prep_video.py path/to/source.mp4 --strip-audio --output media/video_with_no_audio.mp4
26. 音频处理选择：默认保留原音频（模型可能略微修改）；若要完全重新生成音频，必须先用 --strip-audio（或 -a）在上传前去除音频流，否则模型会尝试保留/修改原音频。
27. 单场景提示：默认模型会尝试多镜头叙事；若需要单场景，必须在提示词中写明：In a single unbroken scene、In a single continuous shot、No scene cuts。
28. 去除不想要的元素：在提示词中加入简单负面提示，如 No dialogue、No embellishments、No extra sound effects。
29. 编辑提示：使用简单提示效果最好，过度描述会导致意外改动；编辑特定方面时加上 "Keep everything else the same" 以保持视觉一致性。
30. 音频提示：用提示词描述想要的音频类型，尤其需要音乐时，如 Include calm background music、The video has a high energy techno beat、The audio is a low tinny radio broadcast in the background, playing a song。
31. 时间控制：用自然语言指定事件发生时间，如 After 3 seconds, a woman enters the scene.、At 5s the chorus starts in the background audio.、Every 2s cut to a new frame.、In a rapid fire sequence, every half a second (12 frames at 24fps) change the scene to a new location.；也可用时间码语法：[0-3s] A person is walking / [3-6s] They stop and turn around / [6-10s] They start running。
32. 元提示：可要求模型关注通用质量原则，如 Consider micro-detail, expression and timing to create a very rich, detailed but entirely natural scene.、Be extremely detailed in your descriptions of characters and environments...、Include plenty of appropriate detail in the background elements...、Make a rapid fire video that shows a different rare [thing] every 1s, upbeat music, include text to label the thing。
33. 视频内文字：可提示包含文字，模型会正确渲染；若视频中自然会出现文字（包括背景元素），最好定义其内容，如 One word on the screen at a time: "did, you, know, that, Omni, can, do, awesome, text?" Each word appears for 1s with a different animated style. No dialogue.、There is a street sign that says: "This is an AI generation by Omni"...
34. 扩展视频提示：用 "Extend this video" 或 "The scene continues" 等提示扩展，每次 10s，总长最多 40s；模型会用原视频最后 10s 作为上下文保持视频、运动、角色和音频连贯，并会编辑输入视频的部分末尾帧使过渡无缝。
35. 扩展时用参考：扩展可不设置 API 的 task="extend" 参数，从而允许通过 --image 和 --video-reference 传入参考图和参考视频，无缝引入新角色、物体或风格；若显式设置 task="extend"，则无法传入多模态参考。
36. 扩展提示技巧：描述扩展场景的音频（如 "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 视频时 "After 2s cut to a new scene with the same characters" 会在 12s 后切换）。
37. 扩展约束：上传用于扩展的输入视频必须不超过 10 秒（多轮除外）；不能扩展有人说话的上传视频来添加新对话（角色保持沉默或提示不加对话则支持）；通过 previous_interaction_id 多轮扩展之前生成的视频时支持生成语音对话；建议主要依赖提示词，仅在提示无效时才用 task="extend"，因为设置 task 会增加约束（如禁用多模态参考输入）。
38. 用标签绑定媒体角色（简单标签，推荐）：<FIRST_FRAME> 用作起始帧；<LAST_FRAME> 用作最终帧（必须与 <FIRST_FRAME> 一起用）；<IMAGE_REF_N> 用作参考图（从 0 开始）；<VIDEO_REF_N> 用作角色或物体参考视频（从 0 开始）。
39. 参考视频指南：理想时长约 3 秒（更长也可以），可用 prep_video.py --duration 3 裁剪；建议最多 3 个参考视频（更多也可用）。
40. 复杂多素材多角色场景：在提示词开头用显式前缀标签声明来源和参考，如 [# 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]。
41. 在提示词末尾加引导指令：起始帧用 "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."。
42. 安装依赖：pip install -U google-genai（需 google-genai >= 2.19.0 以支持 interactions 客户端和完整视频输出分辨率配置）。
43. 确保 Python >= 3.10（兼容现代 google-genai SDK 类型和方法）。
44. 确保系统 PATH 中有 ffmpeg 和 ffprobe（prep_video.py、inspect_video.py 以及 generate_video.py 使用 --strip-audio 时需要）。
45. 设置 API Key 环境变量：export GEMINI_API_KEY="your-api-key"。
46. 所有操作和状态管理通过 Interactions API 处理；输入媒体文件（参考图、视频）必须先通过 Files API 上传，再把上传的文件 URI 和 MIME 类型放进 interactions.create 的 input parts 数组。
47. 请求超时：默认 HTTP 超时 600 秒（10 分钟）；计算密集型请求（如把 30s 视频在 4K 下扩展 10s 到最长 40s）可能耗时数分钟，用 --timeout 900（或 1200）提供更长执行预算。

适用边界 · 注意事项

• 上传视频用于视频编辑或扩展在 EEA、瑞士、英国和部分美国州不可用；若视频到视频编辑很快完成但输出为空（total_output_tokens: 0 或无视频内容），很可能就是该地区限制导致。
• 上传用于扩展的输入视频超过 10 秒（多轮除外）时不适用。
• 不能扩展有人说话的上传视频来添加新对话（角色保持沉默或提示不加对话则支持）。