PiAPI Skills for Claude, Codex, Hermes, OpenClaw, and others

🇺🇸 English. Leia em português: README.pt-BR.md.

Single skill bundle that teaches AI coding agents how to drive
PiAPI — Midjourney, Flux, Kling, Luma, Hailuo, Veo 3,
Suno, Hunyuan, Faceswap, Trellis 3D, MMAudio, F5-TTS, Gemini Nano Banana,
Seedance 2, plus the OpenAI-compatible LLM proxy — through one CLI.

Not affiliated with PiAPI. "PiAPI" is a trademark of its respective owner.

Watch the tutorial (1 min)

▶︎ Full MP4 · Cover · Per-scene stills · Source (Remotion)

A 9-scene animated walkthrough — install, configure PIAPI_API_KEY, CLI
tour, model catalog, async submit/poll/result flow, and per-agent skill
paths. Built with Remotion; edit and re-render
from presentation/remotion-tutorial/.

Scene gallery

1. Intro	2. What is it	3. Install
4. Configure	5. CLI tour	6. Models
7. Workflow	8. Agents	9. Outro

Install

curl -fsSL https://raw.githubusercontent.com/wesleysimplicio/PiAPI-Skills/master/install.sh | bash

Or clone and run:

git clone https://github.com/wesleysimplicio/PiAPI-Skills.git
cd PiAPI-Skills
./install.sh

Flags:

./install.sh --yes                          # non-interactive
./install.sh --agents claude,codex,hermes   # install only listed agents
./install.sh --uninstall                    # remove CLI + agent skills

The installer:

1. Provisions a Python 3.10+ virtualenv at
   ~/.local/share/piapi-skill/venv and installs requests.
2. Drops piapi-cli into ~/.local/bin (add to PATH if missing).
3. Copies the appropriate SKILL.md into each detected agent skill root.

Agent skill paths the installer writes to:

Configure

Set the API key from https://piapi.ai/workspace/key:

export PIAPI_API_KEY="<your key>"
# optional, only if you receive webhooks:
export PIAPI_WEBHOOK_SECRET="<your shared secret>"

Persist in your shell rc (~/.zshrc, ~/.bashrc).

CLI tour

piapi-cli --help                                              # subcommand list
piapi-cli models                                              # list known model · task_type pairs
piapi-cli imagine "studio portrait, calico cat" --aspect 1:1  # Midjourney imagine
piapi-cli flux "cyberpunk alley at night"                     # Flux schnell txt2img
piapi-cli kling --image-url https://… --prompt "slow zoom"    # Kling image2video
piapi-cli suno --prompt "lofi piano under rain"               # Suno music
piapi-cli faceswap --target-image https://… --swap-image …   # Faceswap (image)
piapi-cli submit --model <m> --task-type <t> --input '{...}' # generic submit
piapi-cli wait <task_id>                                      # poll until terminal
piapi-cli result <task_id>                                    # fetch one snapshot
piapi-cli cancel <task_id>                                    # cancel pending only
piapi-cli run --model <m> --task-type <t> --input '{...}'    # submit + wait + print
piapi-cli llm --model gpt-4o-mini --message 'user:Hi'         # sync chat completion
piapi-cli verify-webhook --header-secret X --expected Y       # constant-time compare

Add --webhook-url and --webhook-secret to any submit-style command to
register a callback.

Examples

References

Surface map

Status enum drift

Lowercase before comparing. Staged (Midjourney) is not terminal —
follow up with upscale / variation. Treat
completed | complete | success | succeeded as terminal-success and
failed | failure | error | canceled | cancelled | rejected as
terminal-failure.

Webhooks

PiAPI does not sign payloads with HMAC. The secret you registered on
the task is echoed in the x-webhook-secret request header. Constant-time
compare against your stored secret.

Retry policy: every 5s, up to 3 attempts on any non-2xx. After three
failures, recover by polling piapi-cli result <task_id>.

Contributing

PRs welcome — see CONTRIBUTING.md and the
CODE_OF_CONDUCT.md.

License

MIT — see LICENSE and NOTICE for attribution
caveats and trademark disclaimers.