ZM IMG2 Direct Image Generation

intent

run image generation directly against the happy/gpt-image-2 API endpoint for both text2img (文生图, prompt-only) and img2img (参考图生图, prompt plus reference images). this skill is locked to the happy provider and gpt-image-2 model, with no local mock fallback. use this when you need production-grade image artifacts with full audit trail: input specs, API response metadata, and proof that happy/gpt-image-2 actually generated the output.

inputs

external connections:

• happy image API (OpenAI-compatible endpoint). configure via models.providers.happy in openclaw config. requires valid auth token in env or config.
• environment variables: OPENCLAW_IMAGE_PROVIDER (defaults to happy), OPENCLAW_IMAGE_MODEL (defaults to gpt-image-2).

binaries:

• python3 (for run.py, batch_run.py, image_queue.py scripts).
• node (for generate-image.js utility).

parameters (run.py single-image mode):

• --prompt (required): text description of image to generate.
• --task-name (required): string used as output directory prefix and filename prefix.
• --input-image / --image / --reference-image (optional): path to reference image for img2img. repeatable, max 5 total across all aliases.
• --images (optional): JSON array or comma-separated list of reference image paths.
• --provider (optional): provider key, defaults to happy.
• --model (optional): model name, defaults to gpt-image-2.
• --size (optional): image dimensions, defaults to 1024x1024.
• --timeout-ms (optional): request timeout in milliseconds, defaults to 600000 (10 minutes).
• --output-dir (optional): output directory, defaults to <openclaw-home>/generated-images.
• --max-attempts (optional): retry attempts, defaults to 3, max 5.
• --retry-base-delay, --retry-max-delay, --retry-jitter (optional): retry timing parameters.
• --raw (optional): marker for callers that intentionally preserve user prompt unchanged (no auto-sanitization).
• --no-send (optional): accepted for compatibility; this skill never auto-sends output. use external channel tools for delivery.

parameters (batch_run.py):

• @batch.json file with structure: batch_name, max_workers (capped at 4), timeout_ms, send_to_feishu (boolean), tasks array.
• each task object: task_name, prompt, optional input_image/image/reference_image (repeatable) or images list.

parameters (image_queue.py):

• --prompt (required): image description.
• --task-name: output directory prefix.
• --task-key: unique identifier for this task in queue state.
• --max-workers (optional): concurrency, defaults to 4 (hard-capped).
• --task-timeout-seconds (optional): per-task timeout, defaults to 600.
• --max-queue-size (optional): pending queue size, defaults to 100.
• --state-dir (optional): queue state directory, defaults to <openclaw-home>/image-queue.
• --output-dir (optional): image output directory, defaults to <openclaw-home>/generated-images.

procedure

single-image text2img (文生图)

1. invoke python3 skills/zm-img2-generation-direct/scripts/run.py --prompt "<description>" --task-name "<name>" with no reference image flags.
2. script routes internally to /images/generations endpoint (mode: generation).
3. script sends prompt to happy/gpt-image-2 API.
4. API returns image bytes and metadata.
5. script writes PNG image to <output-dir>/<task-name>.png.
6. script writes run metadata to <output-dir>/_runs/<task-name>-<timestamp>/state.json with status, attempt count, elapsed time, and output path.
7. script writes per-attempt request.json, result.json, stdout.txt, stderr.txt to same run directory.
8. script exits with result.json containing ok: true, provider: happy, model: gpt-image-2, mode: generation, input_images: [], bytes: <size>.
9. user inspects result.json to verify generation proof. image file is ready for use.

single-image img2img (参考图生图)

1. invoke python3 skills/zm-img2-generation-direct/scripts/run.py --prompt "<description>" --input-image <path> --task-name "<name>".
2. script validates reference image exists at .
3. script routes internally to /images/edits endpoint (mode: edit).
4. script sends prompt plus reference image(s) to happy/gpt-image-2 API.
5. API returns edited/generated image bytes and metadata.
6. script writes PNG to <output-dir>/<task-name>.png.
7. script writes run directory artifacts as in text2img case, but mode: edit and input_images: [<path>].
8. script exits with full result metadata including reference image paths.
9. user inspects result.json to confirm mode and input images. image is production-ready.

batch image generation

1. create batch JSON file with batch_name, max_workers, timeout_ms, tasks array.
2. invoke python3 skills/zm-img2-generation-direct/scripts/batch_run.py @batch.json.
3. script creates batch directory under <output-dir>/batches/<batch-name>-<timestamp>/.
4. script writes batch_request.json with original batch spec.
5. script spawns up to max_workers (capped at 4) parallel processes, each calling run.py for one task.
6. each task gets its own subdirectory: <batch-dir>/<task-name>/ with batch_task.json, state.json, stdout, stderr, and result.json.
7. completed tasks do not block pending tasks. a failed task is recorded but does not stop other tasks.
8. script waits for all tasks to finish or timeout.
9. script writes final batch_result.json with per-task success/failure status and artifact paths.
10. user inspects batch_result.json and per-task result.json files to verify all generations.

image queue submission and monitoring

1. invoke python3 skills/zm-img2-generation-direct/scripts/image_queue.py run --prompt "<description>" --task-name "<name>" --task-key "<unique-key>" to submit a single task.
2. script validates task: checks for duplicate task_key in currently active (queued or running) tasks.
3. if duplicate, task is marked skipped and summary.ok=false.
4. if queue is full (max_workers + max_queue_size tasks already accepted), task is marked rejected.
5. if valid and capacity exists, task is accepted, written to <state-dir>/tasks/<task_id>/task.json, and queued.
6. child process is spawned from a worker thread, executing run.py with the task parameters.
7. script supervises child process. if it exceeds task_timeout_seconds, script sends SIGTERM, then SIGKILL if process ignores.
8. upon child exit, script reads result.json from task directory and verifies worker binding (task_id/worker_id match).
9. if binding is OK and child exited 0 with ok: true, task is marked completed.
10. if child exited non-zero or returned ok: false, task is marked failed.
11. if timeout occurred, task is marked timed_out.
12. if worker binding fails, task is marked orphan_late_output (not acceptable).
13. user invokes python3 ... image_queue.py status, list, get, or history to inspect queue state.
14. user inspects final <state-dir>/queue_state.json and per-task <state-dir>/tasks/<task_id>/result.json for proof.

queue monitoring commands

• status: display overall queue health (counts of completed, failed, timed_out, rejected, etc.).
• list: show all tasks in queue (optionally filtered by --status <completed|failed|...>).
• get <task_id_or_key>: show single task metadata, last stdout/stderr lines, and artifact paths.
• history -n <count>: show last N completed/failed tasks with timestamps.
• cancel <task_id_or_key>: mark a queued task as cancelled (only works for tasks not yet running).

decision points

routing: text2img vs img2img:

• if no reference images are provided (no --input-image, --image, --reference-image, or --images flags), route to /images/generations endpoint (text2img / 文生图, mode: generation).
• if any reference image is provided, route to /images/edits endpoint (img2img / 参考图生图, mode: edit).

provider and model selection:

• if OPENCLAW_IMAGE_PROVIDER env var is set, use that value. else if --provider flag is supplied, use that. else use default happy.
• if OPENCLAW_IMAGE_MODEL env var is set, use that value. else if --model flag is supplied, use that. else use default gpt-image-2.
• production acceptance workflows must not switch to non-happy providers or models. reject any request to use a different provider/model pair for acceptance-sensitive tasks.

reference image handling:

• accept --input-image, --image, or --reference-image as aliases for the same concept (img2img reference).
• if --images is also provided, combine all reference images from all flags.
• cap total reference images at 5. if user provides more than 5, fail with clear error message citing the limit.

retry logic:

• retryable errors: timeout, upstream HTTP 408/429/500/502/503/504, rate limits, wrapper parse errors.
• non-retryable errors: invalid request format, auth failure, model not found, API key invalid or expired.
• on retryable error, retry up to max-attempts times (default 3, max 5) with exponential backoff (retry-base-delay, retry-max-delay, retry-jitter).
• on non-retryable error, fail fast with redacted error details (do not expose API keys or internal paths).

auth and config:

• if happy provider config is missing from openclaw config, fail with clear instruction to configure models.providers.happy and provide auth token.
• if API auth token is missing or expired, fail fast with non-retryable error (do not retry).

batch and queue capacity:

• batch max-workers is hard-capped at 4. if user requests more, silently cap to 4.
• queue max_workers defaults to 4 (hard-capped). max_queue_size defaults to 100.
• total queue capacity is max_workers + max_queue_size. if total accepted tasks exceeds this, reject new tasks explicitly.
• do not silently discard or queue indefinitely. new tasks beyond capacity are marked rejected.

queue duplicate task keys:

• within a single run of image_queue.py, task_key must be unique among queued and running tasks.
• if a duplicate task_key is submitted while an earlier task with the same key is still queued or running, mark the new task skipped.
• skipped tasks cause summary.ok=false.

timeout handling:

• per-image request timeout is --timeout-ms, defaults to 600000 (10 minutes).
• per-task in queue is --task-timeout-seconds, defaults to 600 (10 minutes).
• on timeout, send SIGTERM to child process. if process is still alive after 2 seconds, send SIGKILL.
• mark timed-out tasks as timed_out in final state (not acceptable).

empty or invalid result sets:

• if API returns success but no image bytes, fail with clear error (malformed API response).
• if image file write fails (disk full, permission denied), fail and report error.
• if result.json is missing or unreadable after child process exit, mark task as orphan_late_output (not acceptable).

network and connection issues:

• on network timeout, treat as retryable error.
• on connection refused or DNS failure, treat as retryable error for up to max-attempts.
• on persistent connection failure after max-attempts, fail with redacted error.

output contract

single-image run artifacts:

• image file: <output-dir>/<task-name>.png (PNG format, newly generated from API).
• run directory: <output-dir>/_runs/<task-name>-<timestamp>/ containing:
  • state.json: run metadata with status (ok/failed/timeout), attempt count, elapsed_seconds, output_path, error (redacted if sensitive).
  • per-attempt subdirectory attempt_<N>/ with request.json (API request payload), result.json (API response + metadata), stdout.txt, stderr.txt.

result.json schema (single image and batch tasks):

{
  "ok": true,
  "provider": "happy",
  "model": "gpt-image-2",
  "mode": "generation" or "edit",
  "input_images": [] or ["<path1>", "<path2>"],
  "bytes": <integer>,
  "output_path": "<absolute-path-to-image>",
  "request_id": "<api-request-id>",
  "timestamp": "<ISO-8601>",
  "elapsed_ms": <integer>,
  "attempt": <integer>
}

batch run artifacts:

• batch directory: <output-dir>/batches/<batch-name>-<timestamp>/ containing:
  • batch_request.json: original batch spec.
  • batch_result.json: final summary with per-task status rows.
  • per-task subdirectory <task-name>/ with same structure as single-image run (state.json, result.json, logs).

batch_result.json schema:

{
  "ok": <boolean (true only if all tasks succeeded)>,
  "batch_name": "<batch-name>",
  "batch_dir": "<path>",
  "timestamp": "<ISO-8601>",
  "tasks": [
    {
      "task_name": "<name>",
      "status": "completed|failed|timed_out|rejected|skipped",
      "ok": <boolean>,
      "result_path": "<path-to-result.json>",
      "output_path": "<path-to-image-or-null>"
    }
  ],
  "summary": {
    "total": <int>,
    "completed": <int>,
    "failed": <int>,
    "timed_out": <int>,
    "rejected": <int>,
    "skipped": <int>
  }
}

queue artifacts:

• state directory: <state-dir>/image-queue/ or custom --state-dir.
• per-task subdirectory: <state-dir>/tasks/<task_id>/ containing:
  • task.json: task metadata (task_id, task_key, prompt, input_images, worker_id, thread_id, child pid, submission timestamp).
  • command.json: actual command invoked (run.py or mock command for tests).
  • result.json: final result from run.py (as above).
  • stdout.txt, stderr.txt: child process output.
• queue_state.json: global queue state with active task_ids, pending queue, worker assignments.

acceptance-eligible result.json must contain:

• ok: true.
• provider: "happy".
• model: "gpt-image-2" (or "happy/gpt-image-2" as full pair).
• mode: "generation" for text2img or mode: "edit" for img2img (must match routing).
• input_images: [] for text2img or input_images: [list of actual reference paths] for img2img.
• newly generated PNG file at output_path (not a reused, cropped, spliced, or collaged image).

acceptance ineligible results:

• ok: false or missing.
• provider != happy or missing.
• model != gpt-image-2 or missing.
• mode mismatch (e.g., mode=generation but input_images is non-empty).
• image file is CSS/HTML render, webpage screenshot, SVG export, or manual composite.
• image is reused or derived from old generation (crop, splice, collage).
• input_images missing or inaccurate.

outcome signal

success indicators:

• result.json is written to run directory with ok: true.
• provider field is happy, model field is gpt-image-2.
• mode field matches expected routing: generation for text2img, edit for img2img.
• input_images field is present and accurate (empty array for text2img, list of paths for img2img).
• image file is written to output_path and is a valid PNG with nonzero filesize.
• bytes field matches actual PNG file size.
• elapsed_ms field is present and reasonable (under 600000ms).
• for batch runs, batch_result.json shows per-task status and final