媒体生成

通过统一工作流处理图像生成、图像编辑与短视频生成：选择合适的模态（modality），将调用方意图透传至服务商，输出文件保存至 tmp/images/ 或 tmp/videos/ 目录，并优先使用封装好的辅助脚本，而非临时拼凑的单次 API 调用。

工作流决策

• 若用户需要一张全新静态图像，请使用图像生成模型。
• 若用户提供了一张图像，或希望修改某张已有图像，请使用图像编辑工作流。
• 若用户需要动态效果 / 视频片段 / 短视频，请使用视频生成模型。
• 若请求中包含一张或多张参考图像，请使用支持参考图像传输的辅助脚本。

标准工作流

1. 判断任务类型：图像生成、图像编辑，还是视频生成。
2. 仅在确保请求可正确执行时才进行澄清。
3. 静态图像生成优先使用 scripts/generate_image.py。
4. 直接图像编辑优先使用 scripts/edit_image.py。
5. 带掩码（mask）或生成区域的局部编辑优先使用 scripts/mask_inpaint.py。
6. 画布扩展（outpainting）优先使用 scripts/outpaint_image.py。
7. 需透传参考图像时，优先使用 scripts/reference_media.py。
8. 视频生成优先使用 scripts/generate_video.py，尤其当服务商可能返回异步任务载荷（async job payload）时。
9. 可复现的批量任务、模板化变体或需审计的清单（auditable manifest）优先使用 scripts/generate_batch_media.py。
10. 针对透明资产或纯色背景上的简单“对象 vs 背景”编辑，优先使用 scripts/object_select_edit.py。
11. 若服务商返回 URL、本地路径、HTML 片段、Markdown 片段、data: URL 或 b64_json，请使用 scripts/fetch_generated_media.py。
12. 输出文件保存路径：
    • 图像 → tmp/images/
    • 视频 → tmp/videos/
13. 若用户要求将文件发送至聊天窗口，请优先发送本地已下载的文件。
14. 当本地获取失败时，保留原始远程引用作为备选方案。

提示词处理

默认采用提示词透传（prompt pass-through）策略。

• 原样传递调用方提供的提示词，不做修改。
• 仅在调用方明确提供时，才使用可选的请求字段。
• 保持提示词语义由调用方完全控制。

辅助脚本主要作为功能型工具使用：

• 参数标准化
• 字段映射至服务商特定的 JSON 结构
• 文件上传
• 异步任务轮询（polling）
• 返回媒体内容下载
• 输出保存至 tmp/images/ 或 tmp/videos/

交付规则

• 生成或编辑后的图像保存至 tmp/images/。
• 生成的视频保存至 tmp/videos/。
• 切勿将生成文件散落在工作区根目录下。
• 若消息交付机制屏蔽远程 URL，请先下载至本地，再发送本地文件。
• 若远程文件无法本地获取，但原始链接仍具参考价值，请清晰提供该原始链接。

辅助脚本速查指南

选用满足需求的最小粒度辅助脚本：

• scripts/generate_image.py → 直接静态图像生成
• scripts/edit_image.py → 全图直接编辑
• scripts/mask_inpaint.py → 带显式或自动生成掩码的局部编辑
• scripts/outpaint_image.py → 编辑前的画布扩展
• scripts/reference_media.py → 参考图像传输与委托处理
• scripts/generate_consistent_media.py → 仅用于向后兼容的包装器
• scripts/generate_batch_media.py → 可复现、清单驱动的批量任务
• scripts/object_select_edit.py → 针对透明资产或纯色背景的简单“对象 vs 背景”编辑
• scripts/generate_video.py → 直接视频生成及异步轮询
• scripts/fetch_generated_media.py → 将返回的媒体引用标准化为本地文件

在判断哪个辅助脚本适配当前模态、传输方式或返回结构时，请查阅 references/model-capabilities.md。 参考图像传输细节请参阅 references/reference-image-workflow.md。 清单格式、模板机制及批量执行行为请参阅 references/batch-workflows.md。

最小化示例：

python3 skills/media-generation/scripts/generate_image.py 
  --prompt 'person' 
  --size '1024x1024' 
  --out-dir 'tmp/images' 
  --prefix 'generated'

python3 skills/media-generation/scripts/edit_image.py 
  --image 'tmp/images/source.jpg' 
  --prompt 'replace the background' 
  --out-dir 'tmp/images' 
  --prefix 'edited'

python3 skills/media-generation/scripts/mask_inpaint.py 
  --image 'tmp/images/source.jpg' 
  --x 120 --y 80 --width 220 --height 180 
  --prompt 'replace the masked area' 
  --out-dir 'tmp/images' 
  --prefix 'mask-result'

python3 skills/media-generation/scripts/outpaint_image.py 
  --image 'tmp/images/source.jpg' 
  --left 512 --right 512 --top 128 --bottom 128 
  --mode blur 
  --prompt 'extend outward' 
  --out-dir 'tmp/images' 
  --prefix 'outpaint-result'

python3 skills/media-generation/scripts/reference_media.py 
  --mode image 
  --reference-image 'tmp/images/reference.png' 
  --prompt 'character' 
  --size '1024x1024' 
  --out-dir 'tmp/images' 
  --prefix 'reference-output'

python3 skills/media-generation/scripts/generate_batch_media.py 
  --manifest 'tmp/images/media-batch.jsonl' 
  --vars-json '{"subject":"item"}' 
  --summary-out 'tmp/images/media-batch-summary.json' 
  --continue-on-error 
  --print-json

python3 skills/media-generation/scripts/object_select_edit.py 
  --image 'tmp/images/product.png' 
  --selection-mode alpha 
  --edit-target background 
  --prompt 'replace the background' 
  --out-dir 'tmp/images' 
  --prefix 'product-bg-edit'

python3 skills/media-generation/scripts/generate_video.py 
  --prompt 'motion clip' 
  --size '720x1280' 
  --seconds 6 
  --out-dir 'tmp/videos' 
  --prefix 'generated-video'

快速兼容性检查清单

在归责于该技能前，请首先确认以下几点：

• 配置文件存在且为合法 JSON 格式
• config.models.providers. 字段存在
• 所选服务商配置中同时包含 baseUrl 和 apiKey
• 所选端点（endpoint）确实在该服务商上可用
• 所选模型名称对该端点有效
• 通过 --extra-json 或 --extra-json-file 传入的任何服务商专属字段均符合其 schema 定义

各封装脚本使用的默认值如下：

• 配置路径：~/.openclaw/openclaw.json 或 $OPENCLAW_CONFIG
• 默认服务商：$OPENCLAW_MEDIA_PROVIDER；若未设置，则取配置中第一个服务商
• 默认模型名称：除非被环境变量或 --model 显式覆盖，否则为占位符
  • 图像 → $OPENCLAW_MEDIA_IMAGE_MODEL 或 image-model
  • 编辑 → $OPENCLAW_MEDIA_EDIT_MODEL 或 image-edit-model
  • 视频 → $OPENCLAW_MEDIA_VIDEO_MODEL 或 video-model
• 输出根目录：tmp/ 或 $MEDIA_GENERATION_OUTPUT_ROOT
• 输出路径默认相对于当前工作目录解析；若指定绝对路径的 --out-dir，则以该路径为准

快速排障指南

常见失败模式：

• provider not found → 显式传入 --provider 参数，或设置 $OPENCLAW_MEDIA_PROVIDER
• 占位符模型警告（image-model / image-edit-model / video-model） → 显式传入 --model 参数，或设置对应的 $OPENCLAW_MEDIA_*_MODEL 环境变量
• config not found / JSON 格式非法 → 显式传入 --config 参数，或修复 OpenClaw 配置文件
• HTTP 404 → 检查 --endpoint 参数及视频轮询路径
• HTTP 400 → 检查模型名称，以及 --extra-json / --extra-json-file 中服务商专属载荷字段是否合规
• HTTP 401/403 → 检查服务商的 apiKey
• HTTP 响应前请求即失败 → 检查 base URL、代理/TLS 设置或网络连通性
• 视频请求被接受但后续失败 → 检查请求载荷、服务商日志，或尝试切换服务商/模型

调试时请启用 --print-json 参数，以确保响应体、解析后的端点地址及失败提示信息始终可见。

参考资料

按需查阅以下文档：

• 辅助脚本选型、模态匹配、传输说明、返回结构处理 → references/model-capabilities.md
• 参考图像传输规则与兼容性说明 → references/reference-image-workflow.md
• 清单格式、模板机制与批量执行行为 → references/batch-workflows.md

核心辅助脚本列表：

• 图像生成 → scripts/generate_image.py
• 图像编辑 → scripts/edit_image.py
• 掩码修复（inpaint） → scripts/mask_inpaint.py
• 外绘（outpaint） → scripts/outpaint_image.py
• 参考图像传输 → scripts/reference_media.py
• 向后兼容包装器 → scripts/generate_consistent_media.py
• 视频生成 → scripts/generate_video.py
• 批量生成 → scripts/generate_batch_media.py
• 对象选择式编辑 → scripts/object_select_edit.py
• 对象掩码预处理 → scripts/prepare_object_mask.py
• 共享请求工具 → scripts/media_request_common.py
• 冒烟测试 → scripts/smoke_test.py
• 媒体内容获取 → scripts/fetch_generated_media.py