ShowMeAI Universal Media Skill

Purpose

Give Agents one safe, deterministic interface for ShowMeAI creative-media generation, configuration, result download, and long-task recovery.

Context

The Agent interprets creative intent and chooses a workflow. The Python runtime owns secrets, parameter validation, API payloads, retries, state transitions, downloads, and persistence. Do not reimplement those deterministic operations in prose or ad-hoc shell calls.

Use python3 {baseDir}/scripts/showmeai.py. Every command returns JSON; generated files are also emitted as MEDIA:<absolute-path>.

Instructions

The following order is mandatory. The readiness check is the first action for every new media request.

1. Before asking for prompt, style, dimensions, quality, or count, run doctor --category <requested-category>. Never begin creative intake first.
2. If it returns SETUP_REQUIRED, offer the one-time Key setup. Never ask for a Key that is already configured.
3. If it returns ONBOARDING_REQUIRED, run onboarding models --category <category> --json, show the current token group's relevant models with the recommended option first, and ask the user to explicitly choose a model and supported defaults. Then persist the choice with onboarding apply. Do not generate until it succeeds.
4. After category onboarding is complete, silently use the saved default unless the user requests an override. Do not ask for the model again on every generation.
5. Accept a Key only through hidden interactive input or setup --key-stdin; never put it in arguments, config JSON, logs, or replies.
6. Treat models as the current Key group's view. Different token groups can expose different models. If a requested model is absent, tell the user to switch the token group or enable automatic grouping, then refresh.
7. The initial image recommendation is gemini-3.1-flash-image; the user's confirmed choice always wins.
8. For video, 3D, music, and image-processing tasks, keep the command alive until terminal success or failure. Do not stop after a task ID. On interruption, preserve the journal and use tasks resume.
9. Return downloaded local files, not only remote URLs or task IDs.

Configuration isolation

Never create, read, or modify OpenClaw, WorkBuddy, Hermes, Codex, Claude, or another host application's config or .env file for ShowMeAI setup. Use only this bundled runtime. Run paths --json when the exact ShowMeAI-owned config, credential, and state locations are needed. Do not invent a host-specific path.

One-time setup

Local interactive setup:

python3 {baseDir}/scripts/showmeai.py setup

When the user sends a Key to a trusted Agent, start this command and write the Key to standard input without echoing it:

python3 {baseDir}/scripts/showmeai.py setup --key-stdin --json

The Key step validates and stores the credential, then reports needs_defaults. In a local TTY, the wizard can immediately collect category choices. In Agent-assisted mode, continue with onboarding models and onboarding apply; --key-stdin must never silently complete model onboarding. See configuration.md.

Route requests

Use python3 {baseDir}/scripts/showmeai.py <command> --help for exact flags. Legacy scripts remain compatibility wrappers.

Output

{"ok":true,"data":{"kind":"image","model":"gemini-3.1-flash-image","files":["/absolute/path/result.png"]}}

Failures use {"ok":false,"error":{"code":"...","message":"...","retryable":false}}. Relay the safe message and recovery action. For success, return all files and mention any fallback model actually used. Never expose secrets.

Output file conventions

All media is downloaded below output.directory (default ./showmeai-output) in a category subdirectory. Return every absolute path from data.files and every MEDIA: line. Never overwrite an existing file. Async state belongs in the OS-native state directory.

Notes

• A task-ID response is not a completed media result.
• The saved user model overrides the initial recommendation.
• verify_on_use means cataloged but not discoverable through the current Key's /v1/models response.
• verified_uncataloged means a newly discovered creative model can be selected, but its special parameters must use API defaults until cataloged.
• Image --count is a 1–10 output contract. The runtime may use bounded parallel single-image calls, so report the physical request count and note that each request may be billed.
• A user-specified --max-wait is the only normal wall-clock cutoff; otherwise keep polling through nonterminal states.

Files

See README.md for the annotated distribution tree covering entry points, shared modules, data, on-demand references, and tests.

Distribution inventory: SKILL.md, README.md, README.zh-CN.md, DESIGN.md, CHANGELOG.md, LICENSE, data/model-catalog.json, references/audio.md, references/configuration.md, references/image-tools.md, references/image.md, references/polling.md, references/three-d.md, references/video.md, scripts/gen.py, scripts/image_to_3d.py, scripts/showmeai.py, scripts/video_gen.py, scripts/showmeai_core/__init__.py, scripts/showmeai_core/catalog.py, scripts/showmeai_core/config.py, scripts/showmeai_core/errors.py, scripts/showmeai_core/http.py, scripts/showmeai_core/outputs.py, scripts/showmeai_core/paths.py, scripts/showmeai_core/tasks.py, and tests/test.py.

Further Reading

• README.md — installation, Agent handoff prompt, examples, and file tree
• DESIGN.md — architecture, alternatives, limitations, and decisions
• CHANGELOG.md — release history