Media Generation

Handle image generation, image editing, and short video generation through one workflow: choose the right modality, pass caller intent through to the provider, save outputs under tmp/images/ or tmp/videos/, and prefer the bundled helpers over ad-hoc one-off API calls.

Workflow decision

• - If the user wants a brand-new still image, use an image-generation model.
• If the user supplies an image or wants a specific existing image changed, use an image-edit workflow.
• If the user wants motion / a clip / a short video, use a video-generation model.
• If the request includes one or more reference images, use the helper that supports reference-image transport.

Standard workflow

1. 1. Determine whether the task is image generation, image editing, or video generation.
2. Clarify only when required to execute the request correctly.
3. Prefer scripts/generate_image.py for still-image generation.
4. Prefer scripts/edit_image.py for direct image edits.
5. Prefer scripts/mask_inpaint.py for localized edits with masks or generated regions.
6. Prefer scripts/outpaint_image.py for canvas expansion / outpainting.
7. Prefer scripts/reference_media.py when reference images need to be passed through.
8. Prefer scripts/generate_video.py for video generation, especially when the provider may return async job payloads.
9. Prefer scripts/generate_batch_media.py for repeatable batch jobs, templated variations, or auditable manifests.
10. Prefer scripts/object_select_edit.py for simple object-vs-background edits on transparent assets or clean backdrops.
11. If the provider returns a URL, path, HTML snippet, markdown snippet, data: URL, or b64_json, use scripts/fetch_generated_media.py.
12. Save outputs under:

1. 13. If the user wants files sent in chat, prefer sending the local downloaded file.
2. Keep the original remote reference as fallback when local retrieval fails.

Prompt handling

Default to prompt pass-through.

• - Pass the caller's prompt through unchanged.
• Use optional request fields only when the caller provides them.
• Keep prompt semantics under caller control.

Use the scripts mainly as functional helpers:

• - normalize arguments
• map fields to provider-specific JSON
• upload files
• poll async jobs
• download returned media
• save outputs under tmp/images/ or INLINECODE16

Delivery rules

• - Save generated or edited images in tmp/images/.
• Save generated videos in tmp/videos/.
• Never scatter generated files in the workspace root.
• If message delivery blocks remote URLs, download locally first and then send the local file.
• If a remote file cannot be fetched locally but the raw link may still help, provide the original link clearly.

Helper quick guide

Use the smallest helper that matches the request:

• - scripts/generate_image.py → direct still-image generation
• INLINECODE20 → direct full-image edits
• INLINECODE21 → localized edits with an explicit or generated mask
• INLINECODE22 → canvas expansion before an edit call
• INLINECODE23 → reference-image transport and delegation
• INLINECODE24 → backward-compatible wrapper only
• INLINECODE25 → repeatable manifest-driven batches
• INLINECODE26 → simple object-vs-background edits on transparent or clean-backdrop assets
• INLINECODE27 → direct video generation and async polling
• INLINECODE28 → normalize returned media refs into local files

Use references/model-capabilities.md when deciding which helper fits the modality, transport, or return shape.
Use references/reference-image-workflow.md for reference-image transport details.
Use references/batch-workflows.md for manifest structure and batch execution behavior.

Minimal examples:

CODEBLOCK0

Quick compatibility checklist

Before blaming the skill, check these first:

• - config exists and is valid JSON
• INLINECODE32 exists
• the selected provider has both baseUrl and INLINECODE34
• the chosen endpoint actually exists on that provider
• the chosen model name is valid for that endpoint
• any provider-specific fields passed through --extra-json or --extra-json-file match that provider's schema

Defaults used by the bundled scripts:

• - config path: ~/.openclaw/openclaw.json or INLINECODE38
• default provider: $OPENCLAW_MEDIA_PROVIDER, otherwise the first provider found in config
• default model names: placeholders unless overridden by env vars or INLINECODE40

• - output root: tmp/ or INLINECODE48
• output paths are resolved relative to the current working directory unless you pass an absolute INLINECODE49

Quick troubleshooting

Common failure patterns:

• - provider not found → pass --provider explicitly or set INLINECODE52
• placeholder model warning (image-model / image-edit-model / video-model) → pass --model explicitly or set the matching $OPENCLAW_MEDIA_*_MODEL env var
• config not found / invalid JSON → pass --config explicitly or fix the OpenClaw config file
• HTTP 404 → check --endpoint and video polling paths
• HTTP 400 → check model name and provider-specific payload fields in --extra-json / INLINECODE62
• HTTP 401/403 → check the provider INLINECODE63
• request failed before HTTP response → check base URL, proxy/TLS, or network reachability
• video accepted then failed later → check request payload, provider logs, or switch provider/model

Use --print-json when debugging so the response body, resolved endpoint, and failure hints stay visible.

References

Read these selectively:

• - helper selection, modality fit, transport notes, return-shape handling → INLINECODE65
• reference-image transport rules and compatibility notes → INLINECODE66
• manifest format, templating, and batch execution behavior → INLINECODE67

Primary helpers:

• - image generation → INLINECODE68
• image edit → INLINECODE69
• mask inpaint → INLINECODE70
• outpaint → INLINECODE71
• reference-image transport → INLINECODE72
• backward-compatible wrapper → INLINECODE73
• video generation → INLINECODE74
• batch generation → INLINECODE75
• object-select edit → INLINECODE76
• object mask prep → INLINECODE77
• shared request utility → INLINECODE78
• smoke tests → INLINECODE79
• media retrieval → INLINECODE80