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. 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/generate_consistent_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:
    • images →

      tmp/images/

    • videos →

      tmp/videos/

13. If the user wants files sent in chat, prefer sending the local downloaded file.
14. 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

  tmp/videos/

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.

Image generation helper

Use

scripts/generate_image.py

for direct still-image generation.

Example:

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

The helper:

• reads provider credentials from OpenClaw config (

  ~/.openclaw/openclaw.json

  by default, or

  --config

  /

  $OPENCLAW_CONFIG

  )
• calls

  /images/generations

  by default
• supports

  size

  ,

  quality

  ,

  style

  ,

  background

  ,

  n

  ,

  seed

  ,

  extra-json

  , and

  extra-json-file

• downloads the returned image into

  tmp/images/

  by default
• handles providers that reply with URL/path,

  data:

  URL, or

  b64_json

Image edit helper

Use

scripts/edit_image.py

for direct image-edit calls.

Example:

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

The helper:

• reads provider credentials from OpenClaw config
• calls

  /images/edits

  by default
• supports optional

  --mask

  input for localized edits
• downloads the returned image into

  tmp/images/

  by default
• handles URL/path,

  data:

  URL, or

  b64_json

Mask inpaint helper

Use

scripts/mask_inpaint.py

for localized repainting tasks.

Example:

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'

The helper:

• accepts either an existing

  --mask

  image or generated regions
• supports rectangle / ellipse regions and repeatable

  --region

  specs
• supports percentage-based regions like

  rect-pct

  /

  ellipse-pct

• supports

  --expand

  /

  --shrink

  before feathering
• supports

  --mask-only

  for local preparation / testing without a live API call
• forwards

  --config

  ,

  --provider

  ,

  --model

  , and

  --endpoint

  to

  scripts/edit_image.py

• reuses

  scripts/edit_image.py

  for the final edit call

Outpaint helper

Use

scripts/outpaint_image.py

for extension / canvas expansion tasks.

Example:

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'

The helper:

• expands the canvas locally before calling the model
• supports directional expansion on each side
• supports

  transparent

  ,

  blur

  , and

  solid

  initialization modes
• forwards

  --config

  ,

  --provider

  ,

  --model

  , and

  --endpoint

  to

  scripts/edit_image.py

• reuses

  scripts/edit_image.py

  for the final edit call

Reference-image helper

Use

scripts/generate_consistent_media.py

when one or more reference images need to be passed through to the provider.

Note: the script name is historical; its current role is reference-image transport and delegation.

Example:

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

The helper:

• can pass encoded reference images in provider JSON (default key:

  reference_images

  )
• can retry without provider-json references when transport is

  auto

• delegates to

  scripts/generate_image.py

  or

  scripts/generate_video.py

Batch generation helper

Use

scripts/generate_batch_media.py

when the user wants several related outputs, repeatable batch rendering, or a manifest-driven workflow.

Example:

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

The helper supports:

• JSON array or JSONL manifests
• image generation, video generation, and reference-image generation
• shared templating vars via

  --vars-json

  or

  --vars-file

• item-local

  vars

  objects for per-item string rendering such as

  {index}

• --summary-out

  to persist the resolved batch result JSON

• --dry-run

  to validate a manifest before spending live generation calls

Object-select edit helper

Use

scripts/object_select_edit.py

when the source has a transparent background or a simple clean backdrop and the user wants a one-step object or background edit workflow.

Example:

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'

The helper:

• prepares an object/background mask with

  prepare_object_mask.py

• flips the mask automatically when editing the background instead of the object
• passes the prepared mask into

  mask_inpaint.py

• supports

  --prepare-only

  for local inspection/testing without a live edit call

Video generation helper

Use

scripts/generate_video.py

for direct video-generation calls.

Example:

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

The helper:

• reads provider credentials from OpenClaw config
• calls

  /videos

  by default
• supports

  size

  ,

  seconds

  /

  duration

  ,

  fps

  ,

  seed

  , optional input image,

  extra-json

  , and

  extra-json-file

• can resolve both immediate-result and async job responses by polling when the provider returns job metadata instead of the final media directly
• downloads the returned video into

  tmp/videos/

  by default

Retrieval helper

Use

scripts/fetch_generated_media.py

for both images and videos. It can extract downloadable refs from markdown / HTML / JSON, and can also persist

data:

URLs or

b64_json

payloads directly to local files.

Quick compatibility checklist

Before blaming the skill, check these first:

• config exists and is valid JSON

• config.models.providers.<provider>

  exists
• the selected provider has both

  baseUrl

  and

  apiKey

• 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

  $OPENCLAW_CONFIG

• default provider:

  $OPENCLAW_MEDIA_PROVIDER

  , otherwise the first provider found in config
• default model names: placeholders unless overridden by env vars or

  --model

  • image →

    $OPENCLAW_MEDIA_IMAGE_MODEL

    or

    image-model

  • edit →

    $OPENCLAW_MEDIA_EDIT_MODEL

    or

    image-edit-model

  • video →

    $OPENCLAW_MEDIA_VIDEO_MODEL

    or

    video-model

• output root:

  tmp/

  or

  $MEDIA_GENERATION_OUTPUT_ROOT

• output paths are resolved relative to the current working directory unless you pass an absolute

  --out-dir

Quick troubleshooting

Common failure patterns:

• provider not found

  → pass

  --provider

  explicitly or set

  $OPENCLAW_MEDIA_PROVIDER

• 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

  /

  --extra-json-file

• HTTP 401/403 → check the provider

  apiKey

• 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

• Batch workflow reference:

  references/batch-workflows.md

• Model capability matrix:

  references/model-capabilities.md

• Reference-image workflow:

  references/reference-image-workflow.md

• Image generation helper:

  scripts/generate_image.py

• Reference-image helper:

  scripts/generate_consistent_media.py

• Image edit helper:

  scripts/edit_image.py

• Mask inpaint helper:

  scripts/mask_inpaint.py

• Outpaint helper:

  scripts/outpaint_image.py

• Video generation helper:

  scripts/generate_video.py

• Batch generation helper:

  scripts/generate_batch_media.py

• Object-select edit helper:

  scripts/object_select_edit.py

• Object mask prep helper:

  scripts/prepare_object_mask.py

• Shared request utility:

  scripts/media_request_common.py

• Smoke tests:

  scripts/smoke_test.py

• Unified fetch helper:

  scripts/fetch_generated_media.py