genmedia-for-commerce 通用商品生成能力帧插值、R2V 旋转视频与换背景的完整实战指南【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples本篇指南聚焦 ADK 示例项目 genmedia-for-commerce 中面向任意商品类型的通用生成能力模块other帧插值Frame Interpolation、参考图转视频R2V360° 旋转与人物换背景Background Changer。文章以 workflows/other/README.md 为主干结合workflows/下的源码与 MCP API 实现完整讲解三个功能的 HTTP 端点、调用管线、关键参数、源码实现原理与排障方法帮助读者直接在本地或 Cloud Run 上复现可运行的商品视频/图片生成服务。模块概览一鱼三吃的通用生成工具箱other模块定位为与商品类型无关的通用能力集合通过 Router Agent 路由分发对外暴露 3 个 MCP 工具spinning_other_r2v、spinning_interpolation、background_changer。它区别于专门化的鞋子旋转workflows/spinning/r2v/shoes/与 VTO 换装流程不需要商品分类前置条件任何商品图片都可以直接进入流水线。Feature能力描述Interpolation帧插值在商品相邻帧之间生成平滑过渡视频适合把一组静态照片变成产品展示片R2VReference-to-Video基于商品参考图生成 360° 旋转视频无需鞋类专属分类Background Changer换背景保持人脸身份的前提下替换人物照片背景用于多场景营销图生成三个功能共享同一套图像预处理基础设施背景移除、超分、画布化核心实现在 workflows/shared/ 与 workflows/spinning/。目录结构能力按模块拆分的组织方式other的功能横跨多个能力目录源码与前端组件分离存放genmedia4commerce/workflows/spinning/r2v/other/ ├── main.py # R2V 旋转的 FastAPI 端点 ├── r2v_utils.py # R2V 提示词生成 ├── image_selection.py # 商品类型分类与最佳图像选择 ├── pipeline.py # Veo R2V 视频生成阻塞式 └── images/products_r2v/ # R2V 商品样例图 genmedia4commerce/workflows/spinning/interpolation/other/ ├── main.py # 帧插值 FastAPI 端点 ├── interpolation_utils.py # 帧插值逻辑与后处理 └── images/products_interpolation/ # 插值样例图 genmedia4commerce/workflows/shared/ └── image_utils.py # 共享图像预处理preprocess_images 等 genmedia4commerce/workflows/other/ ├── main.py # 换背景 FastAPI 端点 └── background_changer/ └── background_changer.py # 背景替换逻辑 frontend_dev/spinning/r2v/other/ └── SpinningR2V.tsx # R2V 旋转前端组件 frontend_dev/spinning/interpolation/other/ ├── SpinningInterpolation.tsx # 插值前端组件 ├── Spinning.css └── InteractiveViewer.tsx frontend_dev/other/background_changer/ └── BackgroundChanger.tsx # 换背景前端组件换背景模块对应 MCP 服务端路由实现在 mcp_server/other/background_changer/background_changer_api.py其路由前缀为/api/other/background-changer与文档示例中的/api/other/change-background对应网关层透传路径以实际部署为准。Feature 1帧插值Frame Interpolation帧插值用于在多张静态商品照片之间生成平滑过渡视频。典型场景是把 4 张不同角度的商品图通过预处理 → 逐段生成过渡 → 合并三步变成一段连续的产品展示视频。管线Images → Preprocess (BG removal upscale canvas) → Generate Transitions → Merge预处理阶段复用共享模块 image_utils.py 的preprocess_images背景移除、超分、画布化三步过渡生成调用 Veo 的 interpolation 模式最后用共享的视频工具合并成 MP4。端点说明POST /interpolation-preprocess预处理插值输入图。multipart/form-data表单字段images接收图片文件列表返回 JSON 数组每个元素包含index帧序号与database64 编码的 PNG 图像{ images: [ {index: 0, data: base64_image}, {index: 1, data: base64_image} ] }POST /interpolation-generate-prompt生成插值提示词当前返回一个静态优化提示词。字段img1、img2为相邻两帧输出形如{prompt: Smoothly transition between the two product views...}。POST /interpolation-generate生成两帧之间的单段过渡视频。字段包括img1起始帧、img2结束帧、index分段序号、prompt过渡提示词、backgroundColor背景色 hex默认#FFFFFF输出video/mp4。POST /interpolation-merge合并多段视频并支持速度调整。字段videos为视频文件列表speeds为 JSON 数组形式的播放速度列表输出video/mp4。源码实现细节interpolation_utils.py是插值能力的核心实现workflows/spinning/interpolation/other/interpolation_utils.py包含两条关键路径提示词生成get_interpolation_prompt先用generate_generic_product_title让 Gemini 以温度 0 输出一个极简商品类别标题如 a smartphone、a t-shirt再套进 Veo 模板return f[Subject]: {product_title.strip()} rotating clockwise in a perfect white void. **[Action]:** The camera performs **one continuous, seamless orbit** around the stationary product. ... **[Scene]:** A completely white studio void (Hex: #FFFFFF, RGB: 255, 255, 255). ...单段生成与后处理process_single_video组合generate_veo模型veo-3.1-generate-001时长 4 秒传入last_frame启用插值模式与post_process_single_video。后者是保证多段视频无缝衔接的关键从视频末尾抽取约 15 帧用find_most_similar_frame_index找到与目标结束帧最相似的一帧把视频裁剪到该帧非首段视频还会去掉第一帧避免拼接时帧重复def process_single_video(client, start_image, end_image, prompt, index, num_frames_for_similarity15, background_color#FFFFFF): veo_video generate_veo(client, start_image, end_image, prompt) video post_process_single_video( video_bytesveo_video, end_imageend_image, num_frames_for_similaritynum_frames_for_similarity, is_first_video(index 0), ) return video视频生成失败的重试由共享的generate_veo_shared承担指数退避最多 5 次重试见 workflows/shared/veo_utils.py 与 workflows/shared/llm_utils.py 的retry_with_exponential_backoff。调用示例import requests import base64 import json # Step 1: 预处理图片 preprocess_response requests.post( /api/spinning/interpolation/other/interpolation-preprocess, files[(images, open(fframe_{i}.jpg, rb)) for i in range(4)] ) processed preprocess_response.json()[images] # Step 2: 逐对生成过渡视频 videos [] for i in range(len(processed) - 1): response requests.post( /api/spinning/interpolation/other/interpolation-generate, files{ img1: base64.b64decode(processed[i][data]), img2: base64.b64decode(processed[i1][data]) }, data{index: i, prompt: Smooth transition, backgroundColor: #FFFFFF} ) videos.append(response.content) # Step 3: 合并所有分段 merge_response requests.post( /api/spinning/interpolation/other/interpolation-merge, files[(videos, v) for v in videos], data{speeds: json.dumps([1.0] * len(videos))} ) with open(final_video.mp4, wb) as f: f.write(merge_response.content)Feature 2R2VReference-to-Video360° 旋转R2V 用商品参考图直接生成 360° 环绕旋转视频与鞋子旋转shoes 模块的区别在于不需要鞋类专用分类——任何商品都可用同一套流程。管线Images → Preprocess (upscale extract) → Stack References → Generate Prompt → Generate Video预处理超分 商品抠取后参考图会被堆叠组合以符合 Veo 的参考图数量上限最多 3 张随后生成旋转提示词并调用 Veo R2V 生成视频。端点说明POST /r2v-preprocess预处理商品图。字段images接收图片文件列表最多 4 张返回处理后的参考图列表{ processed_images: [ {index: 0, image_base64: ...}, {index: 1, image_base64: ...}, {index: 2, image_base64: ...} ], num_processed: 3 }注意图片会被堆叠组合成最多 3 张参考图Veo 参考图数量上限。POST /r2v-generate-prompt基于商品图生成旋转提示词。字段images为图片文件列表输出商品描述与提示词{ prompt: A sleek wireless speaker rotates slowly 360 degrees..., description: wireless bluetooth speaker with metallic finish }POST /r2v-generate生成单段旋转视频。字段reference_images参考图文件列表、prompt生成提示词、index视频序号默认 0输出video/mp4。POST /r2v-pipeline端到端 R2V 管线一键接口。仅需字段images最多 4 张商品图直接输出video/mp4。源码实现细节提示词模板定义在 r2v_utils.py模板明确要求相机围绕静止商品做一次连续、无缝、快速的 360° 环绕商品本身不动**[Subject]:** {{description}} **[Action]:** The camera performs **one continuous, seamless, very fast 360-degree orbit** around the stationary product. ... **[Scene]:** A completely white studio void (Hex: #FFFFFF, RGB: 255, 255, 255). ...其中{{description}}由generate_product_description调用 Gemini 生成系统提示词要求模型输出商品类型 主色的最短描述且明确禁止出现品牌名温度 0、max_output_tokens100、关闭思考预算。例如A red ceramic mug standing still in a completely white studio void (Hex: #FFFFFF, RGB: 255, 255, 255)。描述会再被填充进VEO_R2V_PROMPT_TEMPLATE作为最终 Veo 提示词。图片选择与堆叠逻辑在 image_selection.pyclassify_product_images先判断商品是3D 物体鞋、车还是平面物体select_best_images再据此决定堆叠布局——3D 物体侧视图独立成画布、正反面堆叠平面物体正反面独立、侧面堆叠。共享的stack_and_canvas_imagesworkflows/shared/image_utils.py在 4 张图时会把后两张横向堆叠后输出 3 张 4K 画布。视频生成在 pipeline.py 的generate_video_r2v将参考图包装为VideoGenerationReferenceImage(reference_typeasset)调用veo-3.1-generate-001配置 16:9 画幅、时长 8 秒、单视频、无音频然后轮询长任务直至完成并返回视频字节。调用示例import requests # 简单方式直接走端到端管线 response requests.post( /api/spinning/r2v/other/r2v-pipeline, files[(images, open(fproduct_{i}.jpg, rb)) for i in range(4)] ) with open(spinning_video.mp4, wb) as f: f.write(response.content)Feature 3背景更换Background Changer换背景功能把人物照片中的背景替换为新场景同时保持人脸身份不变适用于为同一组人物素材快速产出多套营销场景图。管线Person Image → Preprocess (face person in parallel) → Generate Variations → Evaluate → Stream Results从 background_changer_api.py 的实现可以看到关键设计人脸预处理与人物预处理通过asyncio.gather并行执行各自包装在run_in_threadpool中所有变体并行生成每个变体生成后立即评估结果以 SSE 流式返回。端点说明POST /change-background生成多张换背景变体SSE 流式返回预处理自动完成。字段person_image人物照片文件必填background_description目标背景的文字描述可选background_image参考背景图片可选num_variations生成变体数量默认 4注意background_description与background_image至少提供一个否则 API 返回 400Either background_description or background_image must be provided见 background_changer_api.py。输出为 SSE 流每个变体在生成 评估完成后立即推送顺序不保证data: {index: 0, status: ready, image_base64: ..., evaluation: {similarity_percentage: 93.6, face_detected: true}} data: {index: 2, status: ready, image_base64: ..., evaluation: {similarity_percentage: 92.9, face_detected: true}} data: {index: 1, status: failed, error: Generation failed} data: {index: 3, status: ready, image_base64: ..., evaluation: {similarity_percentage: 92.7, face_detected: true}} data: {status: complete, total: 4}错误400No face detected in the person image. Please upload a clearer image with a visible face.当 Vision API 检测不到人脸时触发。处理流程人脸裁剪/超分与人物预处理并行执行所有变体并行开始生成每个变体生成后立即评估结果按完成顺序逐个流式推送非输入顺序源码实现细节background_changer.pyworkflows/other/background_changer/background_changer.py实现了三步核心逻辑人脸预处理preprocess_face_image用共享工具crop_faceGoogle Cloud Vision 人脸检测 30% padding 裁剪见 image_utils.py 的crop_face→ Imagen 4.0upscale_image_bytes超分 x4 → 移除背景并放置到#F0F0F0灰底。返回(reference_face, preprocessed_face)二元组无脸时返回(None, None)。人物预处理preprocess_person_imagereplace_background移除背景contour_tolerance0.01、透明背景→ x4 超分异常时回退返回原图。两阶段生成generate_background_change第一步让 Nano Bananagenerate_nano3:4 画幅、1K 尺寸、PNG 输出、温度 0.1把人物放入新背景第二步人脸校正——将第一步结果与reference_face拼进提示词No, the face is different. Use this face: ...再次生成以修正人脸一致性。第二步失败时降级返回第一步结果。质量评估evaluate_background_change_image将生成图与参考人脸提交给共享进程池workflows/shared/person_eval.py 的submit_evaluationDeepFace ArcFace 模型120 秒超时返回similarity_percentage、distance、face_detected等指标评估异常时返回全零兜底结果。调用示例import requests import json import base64 # 文字描述方式 - SSE 流式接收 response requests.post( /api/other/change-background, files{person_image: open(person.jpg, rb)}, data{background_description: tropical beach at sunset, num_variations: 4}, streamTrue ) # 逐个处理 SSE 事件 results [] for line in response.iter_lines(): if line and line.startswith(bdata: ): data json.loads(line[6:]) if data.get(status) ready: results.append(data) print(fVariation {data[index]}: {data[evaluation][similarity_percentage]:.1f}%) elif data.get(status) complete: print(fAll {data[total]} variations complete) # 保存相似度最高的结果 best max(results, keylambda x: x[evaluation][similarity_percentage]) with open(background_result.png, wb) as f: f.write(base64.b64decode(best[image_base64])) # 参考背景图方式 response requests.post( /api/other/change-background, files{ person_image: open(person.jpg, rb), background_image: open(beach.jpg, rb) }, data{num_variations: 4}, streamTrue )画廊端点与配置GET /get_gallery_images获取任意功能的示例商品图。查询参数gallery_type取值为default、interpolation、r2v之一返回 JSON{ products: [ { folder_name: product_001, images: [ {url: /other/images/products/product_001/front.jpg, name: front.jpg} ] } ] }环境变量配置在config.env参考根目录 config.env.example中配置VariableDescriptionPROJECT_IDGoogle Cloud 项目 IDLOCATIONGemini API 使用的 GCP 区域示例中同时提供GLOBAL_REGIONglobal、US_REGIONus-central1、EUROPE_REGIONeurope-west4、DEFAULT_REGIONus-central1NANO_LOCATIONNano Banana API 区域默认global从源码看pipeline.py与background_changer_api.py均以PROJECT_IDGLOBAL_REGION构造genai.Client(vertexaiTrue, ...)MODEL_NAME_GENERATED_2插值标题模型默认gemini-3.5-flash-lite、MODEL_NAME_GENERATED_5换背景 Nano Banana 模型、MODEL_NAME_GENERATED_8Imagen 超分模型等模型名均通过环境变量读取部署时需按实际开通的模型服务配置。关键组件速查组件文件核心职责get_interpolation_prompt/process_single_videointerpolation_utils.py插值提示词生成、单段视频生成 无缝裁剪后处理VEO_R2V_PROMPT_TEMPLATE/generate_product_descriptionr2v_utils.py旋转提示词 Jinja 模板、Gemini 商品描述生成classify_product_images/select_best_imagesimage_selection.py商品类型分类、最佳 4 图选择与堆叠布局generate_video_r2vpipeline.pyVeo R2V 长任务视频生成preprocess_face_image/preprocess_person_image/generate_background_change/evaluate_background_change_imagebackground_changer.py换背景的预处理、两阶段生成、人脸相似度评估preprocess_images共享workflows/shared/image_utils.py批量预处理背景移除、超分、画布创建插值与 R2V 共用change_background_endpointbackground_changer_api.pySSE 流式换背景 HTTP 端点共享图像预处理的细节见 workflows/shared/README.md其中preprocess_images(images_bytes_list, client, upscale_client, num_workers16, upscale_imagesTrue, create_canvaTrue)同时服务于插值与 R2V 两个模式。常见问题排查插值视频出现伪影确保输入帧之间足够相似过渡才能平滑先调用预处理端点统一图像尺寸尝试减小相邻帧之间的差异R2V 视频旋转不正常提供多角度图片正面、侧面、背面确保商品已从背景中清晰抠出建议使用 34 张输入图以获得最佳效果换背景后脸部相似度偏低使用清晰的正脸人物照片避免复杂姿势或面部部分遮挡多生成几个变体并挑选相似度最高的结果No face detected 错误确保人脸在图中清晰可见使用光线充足、高分辨率的图片人脸在图中应至少约 100×100 像素总结other模块通过共享预处理 三个独立生成管线的设计把帧插值、R2V 旋转与换背景三个通用能力封装成可直接调用的 HTTP 端点插值与 R2V 复用preprocess_images与 Veo 系列模型后者还借助 Gemini 自动生成商品描述与旋转提示词换背景则用两阶段生成 DeepFace 人脸评估 SSE 流式返回兼顾效果与体验。实际接入时重点确认PROJECT_ID/LOCATION/NANO_LOCATION及MODEL_NAME_GENERATED_*系列环境变量并遵循各端点的输入约束如 R2V 最多 4 图、换背景必须提供文字描述或参考背景图即可在生产链路中复现文档所示的完整商品生成流程。【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考