PiAPI-Skills

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)

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

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.