| name | media-tools |
| description | Two CLI tools for image generation + vision analysis using goclaw's provider-chain pattern. `create_image` generates images via 7-provider chain (ChatGPT-OAuth/Codex, OpenRouter, Gemini, OpenAI, MiniMax, DashScope, BytePlus) — first available credential wins (OAuth session OR API key), embeds prompt into PNG tEXt metadata, saves to date-folder workspace. The ChatGPT-OAuth provider reads from `~/.codex/auth.json` so a ChatGPT Plus / Codex login works without any API key. `read_image` analyzes images via 4-provider vision chain (OpenRouter, Gemini, Anthropic, DashScope) — accepts file path. Supports `--prompt-file` for long/multi-line prompts, auto UTF-8 stdout, `.env` auto-load, and `--list-providers` diagnostic. Use when Claude needs to generate images or run vision analysis with a specific provider rather than relying on Claude's built-in image understanding. |
| license | MIT |
| allowed-tools | ["Bash","Read"] |
Media Tools
Python ports of goclaw's create_image and read_image tools. Faithful provider-chain pattern: priority order, skip-if-no-key, first-success-wins, cascade-on-failure.
Setup
.claude/skills/.venv/Scripts/python.exe -m pip install -r .claude/skills/media-tools/requirements.txt
API keys (env vars)
Set whichever providers you have keys for. Chain skips providers without keys.
# Image generation
$env:OPENROUTER_API_KEY = "..." # OpenRouter (aggregator, OpenAI-compat)
$env:GEMINI_API_KEY = "..." # Google AI Studio
$env:OPENAI_API_KEY = "..." # OpenAI gpt-image
$env:MINIMAX_API_KEY = "..." # MiniMax image-01
$env:DASHSCOPE_API_KEY = "..." # Alibaba Qwen / Wan2.6
$env:BYTEPLUS_API_KEY = "..." # ByteDance Seedream
# Vision (some keys overlap with image gen)
$env:ANTHROPIC_API_KEY = "..." # Anthropic Claude vision
# Optional API base overrides (for proxies / regional endpoints)
$env:OPENROUTER_API_BASE = "https://openrouter.ai/api/v1"
$env:OPENAI_API_BASE = "https://api.openai.com/v1"
# etc — see lib/env_keys.py for full list
create_image
.claude/skills/.venv/Scripts/python.exe .claude/skills/media-tools/scripts/create_image.py \
--prompt "a cyberpunk cat in neon rain, ukiyo-e style" \
--aspect-ratio 16:9 \
--filename-hint "neon-cat"
Options:
--prompt (required) — text description--aspect-ratio — 1:1 (default) | 3:4 | 4:3 | 9:16 | 16:9--filename-hint — kebab-slug for output file (no extension)--workspace — output dir; default $WEB_TOOLS_WORKSPACE or OS temp--provider — force a specific provider (skip chain): chatgpt_oauth|openrouter|gemini|openai|minimax|dashscope|byteplus--provider-order — comma-separated chain override (default: chatgpt_oauth,openrouter,gemini,openai,minimax,dashscope,byteplus)--reference-image PATH — seed generation with a reference image (PNG/JPG/WEBP). Repeatable, max 4. Supported by chatgpt_oauth, gemini, openai; chain auto-skips others when refs are present.
Output saved to <workspace>/generated/<YYYY-MM-DD>/<name>.png with prompt embedded in PNG tEXt metadata.
Reference-image example (image-to-image / restyle / character-consistency)
.claude/skills/.venv/Scripts/python.exe .claude/skills/media-tools/scripts/create_image.py \
--prompt "Same character, now wearing a red trench coat, neon Tokyo street at night" \
--reference-image ./character.png \
--aspect-ratio 9:16
read_image
.claude/skills/.venv/Scripts/python.exe .claude/skills/media-tools/scripts/read_image.py \
--path "C:/path/to/image.png" \
--prompt "Describe this image in detail. What text appears?"
Options:
--prompt (required) — what to ask about the image--path (required) — local image file (jpg/png/gif/webp/bmp, ≤10MB)--provider — force specific provider: openrouter|gemini|anthropic|dashscope--provider-order — comma-separated chain (default: openrouter,gemini,anthropic,dashscope)--max-tokens — response max tokens (default 1024)
Patterns ported from goclaw
| Pattern | goclaw source | skill file |
|---|
| Provider chain (priority + skip-no-key + first-success) | media_provider_chain.go | lib/chain.py |
| OpenRouter image (OpenAI-compat + modalities) | create_image.go:callImageGenAPI | lib/providers/openrouter_image.py |
| Gemini image (native generateContent + responseModalities) | create_image.go:callGeminiNativeImageGen | lib/providers/gemini_image.py |
OpenAI image (/images/generations) | create_image.go:callStandardImageGenAPI | lib/providers/openai_image.py |
MiniMax image (/image_generation) | create_image_minimax.go | lib/providers/minimax_image.py |
| DashScope image (async task polling) | create_image_dashscope.go | lib/providers/dashscope_image.py |
BytePlus Seedream (/api/v3/images/generations + URL download) | create_image_byteplus.go | lib/providers/byteplus_image.py |
| Vision providers (4-way chain) | read_image.go + provider Chat() | lib/providers/*_vision.py |
| PNG tEXt prompt embedding | pngEmbedPrompt | lib/png_metadata.py |
| Date-folder workspace + sanitized filename | mediaFileName | lib/filename.py |
Aspect-ratio mapping
Each provider has its own size convention; the skill maps --aspect-ratio to each:
| aspect | dashscope | byteplus | minimax/openrouter/gemini |
|---|
| 1:1 | 1024*1024 | 1024x1024 | 1:1 (passed through) |
| 16:9 | 1280*720 | 1280x720 | 16:9 |
| 9:16 | 720*1280 | 720x1280 | 9:16 |
| 4:3 | 1024*768 | 1024x768 | 4:3 |
| 3:4 | 768*1024 | 768x1024 | 3:4 |
