aigen Image Generation

Use this skill when the user wants AI-generated images and local file output through the aigen CLI.

This is a wrapped external tool skill:

• The skill owns setup guidance, readiness checks, safe secret handling, and the generation workflow.
• aigen owns provider configuration, API calls, response normalization, and writing image files.
• Do not present this as a built-in NextClaw image engine.

What This Skill Covers

• Generate images from text prompts.
• Use provider/model routes such as openrouter/x-ai/grok-imagine-image-quality.
• Configure provider records, model records, and provider API keys through aigen.
• Save generated image files to a caller-created output directory.

What This Skill Does Not Cover

• Video, audio, or image editing workflows.
• Long-running daemon management.
• Secret storage outside aigen secrets.
• Provider-specific SDK patching or hidden fallback behavior.

Readiness Check

First check whether aigen is available:

command -v aigen
aigen --version

If aigen is not installed, use the published package:

npm install -g @nextclaw/aigen

If global install is not appropriate, use npx for the current task:

npx -y @nextclaw/aigen@latest --version

Prefer a stable aigen binary for multi-step workflows because provider and secret commands need consistent local state.

Configuration Model

aigen stores its own config under ${AIGEN_HOME:-~/.aigen}:

• config.json contains providers and models.
• secrets.json contains masked provider API key records.

Do not edit these files manually unless the user explicitly asks. Prefer the dedicated commands.

First-Use Setup

For OpenRouter:

aigen providers add openrouter --api-format openrouter --json

Set the API key through stdin. Never put the key directly in shell history:

printf '%s' "$OPENROUTER_API_KEY" | aigen secrets set openrouter --stdin --json

Add a model under the provider:

aigen models add openrouter/x-ai/grok-imagine-image-quality --kind image --generate --max-count 1 --json

If the user has not provided an API key and no safe environment variable is available, stop and ask the user for the key or for permission to use another configured provider. Do not invent, log, or echo API keys.

Generation Workflow

Create an output directory outside the repo unless the user explicitly asks for a project path:

output_dir="$(mktemp -d)"

Choose a collision-resistant output name:

output_name="image-$(date +%Y%m%d-%H%M%S)-$(openssl rand -hex 3)"

Generate:

aigen image \
  --model openrouter/x-ai/grok-imagine-image-quality \
  --prompt "<prompt>" \
  --output-dir "$output_dir" \
  --output-name "$output_name" \
  --json

Parse the JSON result. A successful result contains:

• ok: true
• assets[]
• assets[].path
• assets[].mimeType
• assets[].sizeBytes

Return the generated file path to the user. In environments that can render local images, show the image using its absolute path.

Safety Rules

• Never print raw API keys.
• Never write secrets into repo files, shell scripts, screenshots, logs, or markdown output.
• Prefer AIGEN_HOME pointing to a temporary directory for tests and smoke checks.
• Prefer non-repo output directories for generated images unless the user explicitly wants files in the project.
• Do not overwrite generated files. Use unique output names.
• If provider/model/secret setup fails, report the exact missing piece and stop before generation.

Diagnostics

Check provider and model setup:

aigen providers list --json
aigen models list --json
aigen secrets list --json
aigen doctor --model openrouter/x-ai/grok-imagine-image-quality --json

Remote model discovery, when supported by the provider:

aigen models list --remote --provider openrouter --kind image --json

Troubleshooting

aigen not found

Install @nextclaw/aigen globally or use npx -y @nextclaw/aigen@latest.

Config not found

Run provider/model setup commands first, or set AIGEN_HOME to the expected config directory.

Missing API key

Use aigen secrets set <provider-id> --stdin --json. Do not pass the key as a command-line argument.

Provider request failed

Check:

• provider apiFormat
• provider apiBase
• model route
• API key validity
• whether the model supports image output

Use aigen models list --remote --provider <provider-id> --kind image --json when supported.

Success Criteria

The skill succeeds when:

• aigen --version runs,
• provider/model/secret readiness is confirmed,
• aigen image returns ok: true,
• at least one asset exists on disk,
• and the user receives the generated image path or rendered image.