ADK 通用商品 360° 旋转视频生成：基于 Veo 3.1 R2V 的 Other Products Spinning 流水线深度解析

ADK 通用商品 360° 旋转视频生成基于 Veo 3.1 R2V 的 Other Products Spinning 流水线深度解析【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples导读本文聚焦 adk-samples 仓库中genmedia-for-commerce示例的Other Products Spinning (R2V)模块它利用 Google Vertex AI 上的 Gemini、Veo 3.1 R2VReference-to-Video与 Imagen 三大模型将任意商品包袋、电子产品、配件、家具等非鞋类商品的多角度图片自动合成为一段 8 秒的 360° 旋转视频。通过阅读本文你将掌握该流水线的五阶段处理流程、图片选择与画布布局策略、提示词模板设计、旋转方向与画面瑕疵的双重校验机制以及如何通过 MCP 工具与 REST API 调用这一能力。模块定位与整体设计该模块以 MCP 工具run_spinning_other_r2v对外暴露能力在 ADK Agent 中经由 Router Agent 路由调用源码位于 genmedia4commerce/workflows/spinning/r2v/other/。其核心思路是用多张静态商品图作为参考输入借助 Veo 3.1 的 R2V 模式生成相机围绕静止商品匀速旋转一周的连续视频替代传统的多图插值interpolation方案得到更流畅、更真实的旋转效果。从源码结构看整个模块被拆分为两个子包工作流实现workflows/spinning/r2v/other/——包含pipeline.pyVeo 视频生成、image_selection.py图片分类与优选、r2v_utils.py提示词模板与商品描述生成服务封装mcp_server/spinning/r2v/other/——包含other_mcp.pyMCP 工具与other_api.pyFastAPI REST 路由。五阶段流水线总览文档给出的完整链路为Product Images - Select Best 4 - Preprocess - Stack Canvas - Describe Product - Generate Video - Validate Direction - Glitch Check - Retry if Needed对应到 other_mcp.py 中的实现可归纳为五个阶段图片选择当输入超过 4 张图片时用 Gemini 对每张图片做产品类型与视角分类选出覆盖度与质量最优的 4 张预处理利用 Gemini 去除背景、Imagen 做 4 倍放大再按布局策略拼接到参考画布上提示词生成Gemini 分析全部商品图生成简短描述再渲染进 Veo 提示词模板视频生成以参考图为 asset 资源调用 Veo 3.1 R2V 生成 8 秒旋转视频校验与重试帧级分析旋转方向逆时针则反转、Gemini 检测画面瑕疵失败最多重试 5 次。整条链路涉及的模型分工非常清晰Gemini负责商品描述、图片分类与瑕疵检测Veo 3.1 R2V负责参考图到视频的生成Imagen负责 4 倍图片放大。Stage 1图片选择——一次调用完成分类与优选当传入图片超过 4 张时模块会调用 image_selection.py 中的classify_product_images和select_best_images。一次 Gemini 调用完成双重分类classify_product_images将全部图片打包进一次Gemini 调用temperature0、thinking_budget0、强制 JSON 输出要求模型对每张图输出三类信息维度取值说明产品类型shoes/cars/other决定后续布局优先级shoes指鞋靴cars指车辆other覆盖服装、电子、包袋、家具、配饰等一切其他商品视角right/left/front/back/other俯视、底部、特写等归入other质量1-1010 为清晰、明亮、背景干净、商品完整5 为轻微模糊/背景杂乱/部分裁切1 为严重裁切或不可用返回结构为{product_type: ..., classifications: [{index: 0, view: right, quality: 8}, ...]}且classifications数组长度必须与输入图片数一致、按序对应。源码对返回结果做了严格的合法性兜底非法产品类型回退为other非法视角回退为other非数值质量回退为 5甚至 Gemini 调用整体失败时也会返回全other/5 的默认结果保证流水线不会因分类异常而中断。视角布局策略3D 与平面商品不同select_best_images的核心逻辑在 image_selection.py按视角分组、组内按质量降序再按槽位优先级依次为 4 个槽位挑选未被占用且视角匹配的最佳图片。布局策略取决于商品是3D 对象还是平面对象3D 对象shoes/cars侧视图信息量最大因此右侧视图独占槽位 1、左侧视图独占槽位 2前视图与后视图在槽位 3、4 上堆叠平面对象other前/后视图信息量最大因此前视图独占槽位 1、后视图独占槽位 2左右侧视图在槽位 3、4 上堆叠。若某个视角没有可用图片则按优先级顺序回退到次优视角若输入不超过 4 张则直接原样返回、不做选择。这一策略与stack_and_canvas_images的画布拼接规则一一对应确保进入 Veo 的参考图排列方式符合模型预期。Stage 2预处理——背景移除、4 倍放大与画布拼接预处理阶段由 image_utils.py 中的preprocess_images完成MCP 调用时参数为num_workers4、upscale_imagesTrue、create_canvaFalse背景移除与放大extract_upscale_product先用 Gemini 将商品从原始背景中抠出再用 Imagen 做 4 倍放大得到更高质量、纯背景的参考帧画布拼接stack_and_canvas_images将处理后的图片排列到统一规格的参考画布上。从 image_utils.py 的默认参数可见画布为 4K 规格canvas_height2160、canvas_width3840含边距4 张图时第 3、4 张堆叠在同一画布最终产出 3 张画布作为 Veo 的参考资源。这一步的意义在于统一画布比例与背景消除不同图片间的尺度、背景差异让 Veo 更容易理解同一商品的不同视角从而生成连贯的旋转。Stage 3提示词生成——描述商品并渲染 Veo 模板提示词由 r2v_utils.py 负责分两步第一步生成商品描述generate_product_description让 Gemini 以temperature0、max_output_tokens100分析全部商品图返回符合固定模板的极短描述A [type of product], standing still in a completely white studio void (Hex: #FFFFFF, RGB: 255, 255, 255)模板刻意只包含产品类型 主色并要求避免描述品牌。文档与源码给出的示例包括A red ceramic mug standing still…、A silver smartwatch standing still…、A blue backpack standing still…、A white wireless headphones standing still…。这种约束保证了提示词简洁一致、聚焦于形态与颜色不引入品牌噪声。第二步渲染 Veo 提示词模板描述随后被 Jinja2 模板引擎渲染进VEO_R2V_PROMPT_TEMPLATE见 r2v_utils.py**[Subject]:** {{description}} **[Action]:** The camera performs **one continuous, seamless, very fast 360-degree orbit** around the stationary product. The camera movement is perfectly smooth and steady, maintaining a constant distance and speed throughout the entire clip. The product does not move or rotate; only the camera moves. **[Scene]:** A completely white studio void (Hex: #FFFFFF, RGB: 255, 255, 255). The only visible element is the product, nothing else.模板通过[Subject] / [Action] / [Scene]三段式明确指定主体是商品、动作是相机围绕静止商品做一次连续无缝的快速 360° 环绕商品自身不移动、不旋转、场景为纯白影棚虚空。这种结构化提示词是 Veo 生成高质量旋转视频的关键。Stage 4视频生成——Veo 3.1 R2V 调用细节视频生成封装在 pipeline.py 的generate_video_r2v中核心 API 调用如下def generate_video_r2v(reference_images_bytes, prompt, index): reference_image_sources [] for img_bytes in reference_images_bytes: ref_image VideoGenerationReferenceImage( imageImage(imageBytesimg_bytes, mime_typeimage/png), reference_typeasset, ) reference_image_sources.append(ref_image) operation veo_client.models.generate_videos( modelveo-3.1-generate-001, promptprompt, configtypes.GenerateVideosConfig( aspect_ratio16:9, number_of_videos1, duration_seconds8, generate_audioFalse, reference_imagesreference_image_sources, ), ) while not operation.done: time.sleep(2) operation veo_client.operations.get(operation) ... return video_bytes值得注意的实现细节模型固定为veo-3.1-generate-001每个参考图通过VideoGenerationReferenceImage声明为reference_typeasset即把商品参考图作为资产约束视频内容生成参数为16:9 画幅、时长 8 秒、单条视频、不生成音频调用为阻塞式长任务每 2 秒轮询一次operation.done直到获取generated_videos[0].video.video_bytes若 API 无响应或返回空字节会抛出异常交由上层重试逻辑处理。Stage 5双重校验与重试机制生成出的视频并不会直接交付而是经过旋转方向校验与画面瑕疵检测两道关卡全部通过才标记为有效。旋转方向校验check_spin_direction见 workflows/spinning/eval.py将视频写入临时文件调用 V3f 光学流分类器classify_rotation判定方向返回clockwise/anticlockwise/invalid三态之一。该分类器实现在 rotation_classifier.py基于稀疏光流分析帧间运动方向其参数如 dx_spike32、dy_spike35、min_ratio0.1 等经网格搜索优化源码注释声称在 876 个样本上达到 98.3% 的整体准确率。方向处理策略对应 other_mcp.pyclockwise顺时针保留原片anticlockwise逆时针调用reverse_video见 workflows/shared/video_utils.py按帧抽取后反转顺序默认 24fps、质量 7反转视频使最终成片统一为顺时针旋转invalid无法判定一致旋转计入重试次数触发重新生成。画面瑕疵检测glitch_detection使用 Gemini 视觉模型默认gemini-3.6-flashthinking_levelHIGH视频以 2fps 的VideoMetadata采样检查以下四类问题详见 eval.py方向突变旋转中途长时间反向起止处的轻微摆动不算不自然形变文字/Logo 异常镜像、旋转时手机两侧同时显示屏幕、商品特征错误出现/消失脱离旋转轨迹商品突然缩放、明显倾斜、跳到画面边缘或瞬移旋转不连续大幅跳跃如从背面直接跳到正面。同时明确放行可接受的小瑕疵商品表面的细微不完美、轻微光照变化、自然反光与阴影、起止处的轻微摆动。返回结构为{explanation: ..., is_valid: true/false}。重试循环MCP 工具中重试上限为MAX_CONSISTENCY_RETRIES 5见 other_mcp.py流程为方向invalid或瑕疵检测不通过 → 重新生成 → 再次校验最多尝试 6 次初始生成 5 次重试。若全部失败仍返回最后一次生成的视频但is_valid标记为false由上层调用方决定是否使用。MCP 工具与 REST API 双入口MCP 工具调用MCP 工具run_spinning_other_r2vother_mcp.py接收一个参数参数必填默认说明images_base64是--base64 编码的商品图片列表推荐 1-4 张多于 4 张时自动执行优选空输入或非法 base64 会直接返回错误字典。视频生成、方向校验等耗时操作均通过asyncio.get_event_loop().run_in_executor放入线程池执行避免阻塞事件循环。成功响应的 JSON 结构如下{ video_base64: base64-encoded MP4 video, description: A red ceramic mug standing still..., prompt: Full Veo prompt used for generation, retries: 1, is_valid: true }其中description是 Gemini 生成的商品描述prompt是渲染后的完整 Veo 提示词retries是实际重试次数is_valid表示是否通过全部校验。REST API 端点other_api.py 提供了前缀为/api/spinning/r2v/other的 FastAPI 路由将流水线拆分为可单独调用的步骤便于前端分步展示或调试端点方法功能/get_gallery_imagesGET扫描workflows/spinning/r2v/other/images/目录按product_*文件夹分组返回示例商品图/preprocessPOST仅执行预处理最多 4 张图返回处理后的参考图画布base64/generate-promptPOST仅生成商品描述与渲染后的 Veo 提示词/generatePOST基于参考图 提示词生成单条旋转视频校验结果通过响应头X-Retries、X-Is-Valid、X-Validation-Reason返回/pipelinePOST端到端完整流水线预处理 提示词 生成 校验一次性返回 MP4/mergePOST将多个视频片段按指定速度合并为最终视频注意 REST 入口的MAX_CONSISTENCY_RETRIES 3other_api.py与 MCP 入口的 5 次不同——这是两个入口在重试策略上的实现差异从源码结构可以推断是出于 API 响应时长与成本的权衡。配置项说明模块依赖的环境变量与文档略有出入以仓库实际代码为准。文档中记载的变量名LOCATION、NANO_LOCATION与当前源码使用的实际变量名不完全一致源码pipeline.py、other_mcp.py、other_api.py统一通过以下变量配置变量默认值说明PROJECT_IDmy_projectGoogle Cloud 项目 ID用于创建 Vertex AI 客户端GLOBAL_REGIONglobalVeo/Imagen 与 Gemini 客户端使用的 API 区域默认globalMODEL_NAME_GENERATED_1无图片分类与商品描述使用的 Gemini 模型名MODEL_NAME_GENERATED_2无商品类型判定glasses/other使用的 Gemini 模型MODEL_NAME_GENERATED_4gemini-3.6-flash画面瑕疵检测使用的 Gemini 视觉模型仓库根目录的 config.env.example 提供了更完整的部署级配置参考其中还包含US_REGIONus-central1、EUROPE_REGIONeurope-west4、DEFAULT_REGION等区域定义以及 Cloud Run 部署参数如MEMORY32Gi、CPU8、TIMEOUT3600说明该服务在生产环境以较高资源规格运行长视频任务需要大内存与长超时。运行前提需要具备访问 Vertex AI 上 Gemini、Veo 3.1 与 Imagen 服务的 GCP 凭据认证信息与 Vertex AI 配额是运行本模块的基础条件仓库代码不包含配额申请流程。故障排查与最佳实践旋转方向无效流水线会自动反转逆时针视频因此最终交付片通常统一为顺时针若方向被判定为invalid无法识别出一致的旋转会触发最多 5 次重试建议提供视角差异明显的图片避免各图角度过于接近导致模型无法理解旋转意图。瑕疵检测不通过Gemini 会在生成后检查画面瑕疵未通过的视频自动重新生成若所有重试均失败最后一次生成的视频仍会返回但is_valid: false调用方需自行决定是否接受或提示用户重试。视频质量不佳提供高分辨率、多角度的商品图前、后、左、右四视图全覆盖效果最佳图片虽然会自动做 4 倍放大但原始质量仍然重要——放大无法凭空补足严重模糊或过曝尽量保证每张图只含单一商品、背景简洁降低背景移除阶段的误差。小结Other Products Spinning (R2V) 模块展示了 ADK 生态中多模型协作的典型范式Gemini 承担理解与审核分类、描述、瑕疵检测Veo 3.1 R2V 承担生成Imagen 承担画质增强再以校验-重试循环兜底生成质量。对于希望为电商商品批量产出 360° 展示视频的开发者该模块既可作为 MCP 工具被 ADK Agent 直接调用也可通过 REST API 分步集成到自有前端流程中是理解参考图驱动视频生成R2V工程化落地的绝佳样例。与之互补的鞋类专属流程位于 workflows/spinning/r2v/shoes/可对照阅读以理解两类商品在选图策略上的差异。【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考