Image Generation

Single-gateway image generation CLI for async text-to-image and image-to-image, with polling, download handling, and request alignment to the current gateway OpenAPI. Use when the user asks to generate an image, create a picture, draw something, or make a visual from a text prompt.

Image Generation (image-generation)

Generate an image, create a picture, draw something, or make a visual from a text prompt — all through a single CLI gateway with async polling and automatic download.

This skill follows a single aggregated gateway backend model. One API key is used locally, while multiple models are aggregated behind the gateway. The CLI wraps the full async flow: submit task -> poll lowercase task_status -> fetch data.images. The backend platform is a fixed implementation choice, not a configurable provider switch. If another platform is needed, publish a separate skill for it.

The design goal is smooth automation for common workflows such as single-image generation, multi-file prompts, image-to-image with references, batch jobs, EXTEND defaults, and reusable style presets. Full gateway-alignment notes are in references/weryai-platform.md.

Safety & Scope

• Network: This skill calls the WeryAI gateway over HTTPS (https://api.weryai.com).
• Auth: Uses IMAGE_GEN_API_KEY. The key is never printed. It may be persisted only when you explicitly run npm run setup -- --persist-api-key.
• Reference images: Must be public URLs (https:// recommended). http:// may work but is insecure. Local file paths and data: URLs are rejected.
• No arbitrary shell: The generation runtime does not execute arbitrary shell commands.
• Files written: Output images and optional local config under .image-skills/image-generation/ (project) and/or ~/.image-skills/image-generation/ (home).

Current Gateway Contract (WeryAI)

Item	Contract
Base URL	https://api.weryai.com (hard-coded in scripts/main.ts)
Auth	Authorization: Bearer via IMAGE_GEN_API_KEY (get a key)
text-to-image	POST /v1/generation/text-to-image; requires model, prompt, aspect_ratio
image-to-image	POST /v1/generation/image-to-image; also requires images[]
status lookup	GET /v1/generation/{taskId}/status; task_status is waiting, processing, succeed, or failed
business success	success: true (or status: 200); failures return business codes such as 1001, 1002, 1003
text length	the script validates prompt and negative_prompt lengths before request submission
result download	after succeed, images are fetched by URL; the script uses timeout, retry, backoff, optional Bearer retry, and minimum-payload validation

See references/weryai-platform.md for field mapping, model lookup guidance, and troubleshooting flow.

Step 0: First-Trigger Readiness Gate

When this skill is triggered for the first time in a project or environment, the agent must not jump straight to model selection or generation. It must do this first:

1. Check local readiness silently with npm run ensure-ready -- --project . --workflow <workflow>
2. If runtime dependencies are missing, propose to install them on behalf of the user
3. If IMAGE_GEN_API_KEY is missing, ask the user for permission to configure it now
4. Only after readiness and API key are resolved, continue to model selection / prompt clarification / generation

Access token: only use IMAGE_GEN_API_KEY. It may also live in .image-skills/image-generation/.env as IMAGE_GEN_API_KEY=.... After the user approves, the agent may persist it there by running npm run setup -- --project . --workflow <workflow> --persist-api-key when the key is already in env, or by writing the file locally on the user's behalf instead of asking the user to edit files manually.

First-use readiness check: before the first generation run in a new OpenClaw or local instance, the agent must run:

bash

npm run ensure-ready -- --project . --workflow <workflow>

This readiness step is not optional. It checks the local toolchain, reads the local doctor report, and automatically runs bootstrap when local script dependencies are missing.

First-trigger user behavior:

• If dependencies are missing: ask for approval to install them, then install silently
• If IMAGE_GEN_API_KEY is missing: tell the user image generation needs an API key and offer to configure it now by writing .image-skills/image-generation/.env on the user's behalf
• Do not ask the user to debug the environment before this readiness gate runs
• Do not ask the user to choose a model before readiness and API key are resolved
• Treat API keys as secrets: prefer writing them locally on the user's behalf, never echo them back, and never include them in normal progress messages

EXTEND.md is optional and can hold default model, quality, aspect ratio, and batch worker limits.

bash

test -f .image-skills/image-generation/EXTEND.md && echo project
test -f "$HOME/.image-skills/image-generation/EXTEND.md" && echo user

Default model on initialization: if no model is configured yet, initialize this skill with Nano Banana 2 (GEMINI_3_1_FLASH_IMAGE) and tell the user that it is now the default. Also remind them they can switch models anytime later.

Model selection: after initialization, one of these provides the active default:

• --model
• default_model in EXTEND.md
• IMAGE_GEN_DEFAULT_MODEL

If none of them is set yet, the agent should initialize the local default to Nano Banana 2 first, tell the user that this workspace now defaults to that model, and remind them they can switch anytime if another model fits better. See references/config/first-time-setup.md, references/config/preferences-schema.md, and references/config/model-registry-schema.md.

Style presets: references/style-presets.md

Model priority:

--model -> EXTEND.md default_model -> IMAGE_GEN_DEFAULT_MODEL

If No Model Was Specified

When the user wants image generation but no model is configured (EXTEND.md, --model, and IMAGE_GEN_DEFAULT_MODEL are all absent):

Do not ask the user to read docs or edit config files. Follow the guided flow in references/config/first-time-setup.md § "Model Selection — Agent-Guided Flow":

1. Start from the bundled starter registry shipped with this skill. If the model list looks stale or a requested model is missing, refresh it silently with npm run discover-image-models -- --out .image-skills/image-generation/MODELS.json
2. Initialize local defaults with Nano Banana 2 (GEMINI_3_1_FLASH_IMAGE) by writing EXTEND.md
3. Tell the user that the default model is now Nano Banana 2, and explicitly remind them they can switch anytime later if they need another model
4. Continue to prompt clarification and generation
5. If the user immediately asks for another model, rank candidates for the workflow → npm run recommend-model -- --workflow <workflow> --role <role> --json, then update EXTEND.md

If the workflow is more specific than a generic single image, prefer a role-aware recommendation such as comic-page, comic-character-sheet, infographic-dense, or article-framework instead of only passing the broad workflow name.

If the user later asks to switch models, update EXTEND.md in place — do not ask the user to edit it manually.

If the gateway returns "model does not exist" or a similar model-key error, the agent must first refresh from WeryAI docs and retry recommendation before asking the user for any platform-side information.

If The Request Is Underspecified

When the user gives only a rough idea and the visual brief is still weak, do not jump straight into prompt writing. Use the local brief helper first:

bash

npm run build-visual-brief -- --workflow cover --topic "Habit systems"

Use its question menu to ask about at least:

1. Photorealistic or illustration
2. Color temperature / palette direction
3. Shot language (close-up, wide, etc.)
4. Composition pattern
5. Aspect ratio
6. Text density

Then map the answered brief into the final prompt or workflow files.

Do not tell the user to go read the docs alone. If the CLI fails because the model is missing, the agent should complete this selection flow and retry.

Workflow

1. On first trigger, run the readiness gate: check dependencies, bootstrap missing local tooling, and confirm IMAGE_GEN_API_KEY.
2. Confirm a default model is configured (via EXTEND.md or environment), or enter the guided model-selection flow.
3. Build the prompt: inline text (--prompt) or assembled from files (--promptfiles).
4. Choose a style preset if applicable (--style).
5. Run the CLI to submit the task, poll for completion, and download the result.
6. For multiple images, use batch mode (--batchfile) with parallel jobs.

Script

{baseDir} is the directory containing this file. ${BUN_X} is either bun or npx -y bun.

Path	Purpose
{baseDir}/scripts/main.ts	the only execution entrypoint

Usage

bash

# examples only; M should be chosen by the user or resolved by the agent
M=<chosen model key>

# single image
${BUN_X} {baseDir}/scripts/main.ts --prompt "a cat" --image cat.png --ar 1:1 -m "$M"

# prompt assembled from multiple files
${BUN_X} {baseDir}/scripts/main.ts --promptfiles system.md user.md --image out.png --ar 16:9 -m "$M"

# style preset
${BUN_X} {baseDir}/scripts/main.ts --prompt "city nightscape" --style cinematic --image out.png --ar 16:9 -m "$M"

# image-to-image with reference
${BUN_X} {baseDir}/scripts/main.ts --prompt "turn it into cyberpunk" --image out.png --ref src.png --ar 1:1 -m "$M"

# quality / resolution
${BUN_X} {baseDir}/scripts/main.ts --prompt "poster" --image poster.png --ar 16:9 --quality 2k -m "$M"
${BUN_X} {baseDir}/scripts/main.ts --prompt "poster" --image poster.png --ar 16:9 --imageSize 2K -m "$M"

# infer aspect from size when --ar is omitted
${BUN_X} {baseDir}/scripts/main.ts --prompt "scene" --image scene.png --size 1280x720 -m "$M"

# batch mode
${BUN_X} {baseDir}/scripts/main.ts --batchfile batch.json --jobs 4 --json

# do not write downloaded images to disk
${BUN_X} {baseDir}/scripts/main.ts --prompt "abstract" --image dummy.png --ar 1:1 --no-download -m "$M"

# dry-run request preview; --image is optional here
${BUN_X} {baseDir}/scripts/main.ts --prompt "test" --ar 1:1 -m "$M" --dry-run

Batch JSON Example

json

{
  "jobs": 4,
  "tasks": [
    {
      "id": "hero",
      "promptFiles": ["prompts/hero.md"],
      "image": "out/hero.png",
      "model": "<model key from gateway docs>",
      "style": "editorial",
      "ar": "16:9",
      "quality": "2k",
      "use_web_search": false
    },
    {
      "id": "edit",
      "prompt": "turn it into watercolor",
      "image": "out/edit.png",
      "ref": ["assets/in.png"],
      "negative_prompt": "blurry",
      "webhook_url": "https://example.com/hook"
    }
  ]
}

Paths are resolved relative to the batch file directory. If a provider field exists, it is ignored in single-gateway mode. Task-level optional fields include style, webhook_url, negative_prompt, resolution, use_web_search, and caller_id.

Main Options

Option	Description
--prompt / -p	prompt text
--promptfiles	concatenate multiple files into the prompt
--image / -o / --output	output path in single-task mode; defaults to .png if no extension is given
--batchfile	batch JSON file
--jobs	worker count
--model / -m	model key; one of CLI / EXTEND.md / IMAGE_GEN_DEFAULT_MODEL must provide it
--style	style preset, see style-presets.md
--ar / --aspect-ratio	aspect ratio; defaults to EXTEND.md or 1:1
--size	WIDTHxHEIGHT; can infer aspect ratio if --ar is omitted
--quality	normal or 2k, mapped into gateway resolution
--imageSize	1K, 2K, or 4K
--resolution	pass resolution directly to the API
--negative-prompt	negative prompt
--ref / --reference	reference image, either URL or local file
--n	image_number (default: 1)
--webhook-url	gateway webhook_url
--use-web-search	set use_web_search: true
--caller-id	gateway caller_id
--poll-interval-ms / --poll-timeout-ms	polling controls
--no-download	skip file writing
--dry-run	print the final request body instead of calling the API
--json	JSON summary or batch report

Parallelism and Retry

• Batch jobs use gated concurrency through --jobs, with environment overrides such as BASE_IMAGE_GEN_CONCURRENCY and BASE_IMAGE_GEN_START_INTERVAL_MS.
• A single task retries up to 3 times, but obvious parameter or auth errors are not retried.
• Batch worker caps come from batch.max_workers in EXTEND.md or BASE_IMAGE_MAX_WORKERS.

Environment Variables

Variable	Description
IMAGE_GEN_API_KEY	the only API key variable
IMAGE_GEN_DEFAULT_MODEL	default model key
BASE_IMAGE_MAX_WORKERS	override batch worker limit
BASE_IMAGE_GEN_CONCURRENCY	batch concurrency
BASE_IMAGE_GEN_START_INTERVAL_MS	minimum delay between batch task starts

Supported .env locations:

• <cwd>/.image-skills/.env
• $HOME/.image-skills/.env

Existing environment variables are not overwritten.

Agent Notes

1. On first use in a new environment, run npm run ensure-ready -- --project . --workflow <workflow> from this skill directory before generation. Do not skip this just because direct API calls appear to work.
2. Confirm that IMAGE_GEN_API_KEY is available, directly or through .image-skills/.env.
3. If the model is missing, complete the model-selection flow above before running the CLI.
4. Single-task mode usually requires --image, but --dry-run may omit it. If --ref is present, the script uses the image-to-image endpoint.
5. Polling behavior is: waiting / processing -> keep polling, succeed -> use images, failed -> inspect msg.
6. The selected model key is printed to stderr for easier debugging.

User Feedback During Generation

• Before generation starts: tell the user what's about to happen, including the model being used (e.g., "Generating your cover with Model X, roughly 30 seconds"). Never start silently.
• Model disclosure: always mention the model name/key when generation begins. This helps the user understand quality expectations and makes later model switching easier.
• Batch generation: estimate the total count and rough time. As images complete, show them incrementally — do not wait for the entire batch to finish before showing anything.
• On failure: do not dump error codes. Translate the failure into a user-level explanation and suggest a fix (e.g., "This model is temporarily unavailable — want to try another one?").
• On timeout: if polling exceeds the expected window, proactively inform the user (e.g., "Taking longer than usual, still waiting") rather than staying silent.
• On completion: send/display the image immediately. Never output just a filename — the user must see the actual image. If the platform supports file sending, send the file. If it supports inline rendering, render inline. If neither works, provide a download URL.

Interaction Rules (Mandatory)

These rules apply to every user interaction. They are not optional guidelines.

1. Never show commands, file paths, config syntax, or schema details to the user. All tool execution is silent.
2. Never ask the user to edit config files. The agent writes EXTEND.md, MODELS.json, and other configs on behalf of the user.
3. Ask one question at a time. Do not present all dimensions at once. Lead with the highest-impact choice.
4. Offer concrete options with descriptions, not raw technical names. If presenting styles, describe what each looks like.
5. Always disclose the model and estimated time when generation starts.
6. Show images directly when delivering results. Never respond with only file paths or file names. If the channel supports sending image files, send the file. If it supports inline display, display inline. If neither is possible, provide a clickable download link. A bare filename like output.png is never acceptable delivery.
7. On iteration, only re-generate what changed. Do not restart the entire workflow.
8. If tools are missing, propose to install them on behalf of the user — never expose tool names, PATH errors, or ask the user to run install commands. See "Missing Tools" below.
9. Default to Nano Banana 2 unless the user asks otherwise. When no default model is configured yet, initialize GEMINI_3_1_FLASH_IMAGE (Nano Banana 2), tell the user that it is now the default for this skill, and explicitly remind them they can switch any time if another model fits better.
10. Reply in the user's language. Match the language the user is using for questions, status updates, explanations, and delivery messages unless they explicitly ask you to switch.
11. On first trigger, run readiness before anything else. Check dependencies and IMAGE_GEN_API_KEY status before asking the user to choose a model or before starting generation.
12. Handle API keys as secrets. Offer to configure IMAGE_GEN_API_KEY locally for the user, avoid asking them to paste secrets into normal chat when a local write is possible, and never repeat or quote the key back.

Re-run Behavior

• Running main.ts with the same --image path overwrites the existing output file.
• --batchfile re-processes all tasks in the batch; completed images are overwritten.
• --dry-run never writes files regardless of prior state.
• Polling a previously completed taskId returns the cached result without re-generating.

Definition of Done

• IMAGE_GEN_API_KEY is configured and a default model is set in EXTEND.md.
• The CLI produces a valid image file (or a correct --dry-run request body).
• Batch mode completes all tasks and reports per-task status via --json.
• Failed tasks include a user-readable explanation, not just an error code.
• The model name is disclosed to the user before generation starts.

Missing Tools

If bun and npx are both unavailable in the current environment:

1. Do not expose tool names or PATH errors to the user. Never mention "bun", "npx", "PATH", or installation commands.
2. Propose installation in user-friendly terms. Say something like: "I need to set up a small runtime to generate images — OK if I install it now? Takes about 30 seconds."
3. On user approval, run npm install -g bun or the platform-appropriate installer silently. Report success or failure in plain language.
4. If the user declines or installation fails, explain honestly: "I can't generate images in this environment right now. You can ask your admin to set up the image toolchain, or try again in a different environment."
5. Never ask the user to install tools themselves or paste terminal commands.

Troubleshooting

See references/weryai-platform.md. For failed calls, compare the request and response with call history.