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:

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

Agent skill paths the installer writes to:

Agent	Path
Claude Code	`~/.claude/skills/piapi/SKILL.md`
Codex	`~/.codex/skills/piapi/SKILL.md`
Hermes	`~/.hermes/skills/creative/piapi/SKILL.md`
OpenClaw	`~/.openclaw/skills/piapi/SKILL.md`
Cursor	`~/.cursor/skills/piapi/SKILL.md`
Windsurf	`~/.windsurf/skills/piapi/SKILL.md`
Generic	`~/.config/agents/skills/piapi/SKILL.md`

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

File	What it covers
`examples/01-text-to-image-flux.md`	Flux txt2img — shell, raw envelope, Python.
`examples/02-midjourney-imagine-upscale.md`	Two-step imagine + upscale, Staged status, process_mode.
`examples/03-kling-image-to-video.md`	Kling image2video / text2video / extend with mode + duration.
`examples/04-suno-music.md`	Suno generate_music + custom + extend + concat + add_lyrics.
`examples/05-faceswap.md`	Image, multi-face, video faceswap; target_index zero-based.
`examples/06-hunyuan-video.md`	Hunyuan txt2video-lora + img2video-lora; LoRA URL + strength.
`examples/07-llm-chat.md`	Sync OpenAI-compatible LLM, streaming, OpenAI SDK base_url override.
`examples/08-webhooks.md`	Flask + Express receivers, constant-time secret check, retry policy.

References

File	Topic
`references/rest-api.md`	Submit / fetch / cancel envelopes, headers, status drift, polling.
`references/models.md`	Per-family `model` + `task_type` + input keys for every supported family.
`references/errors.md`	HTTP status interpretation + per-model gotchas + CLI errors.
`references/webhooks.md`	No-HMAC verification pattern, retry policy, recovery via polling.
`references/rate-limits.md`	Free/Creator/Pro/Enterprise tier table + concurrency planning.

Surface map

Family	`model`	Common `task_type`	Status casing
Midjourney	`midjourney`	`imagine`, `upscale`, `variation`, `inpaint`, `describe`, `blend`	Capitalized
Flux	`Qubico/flux1-schnell`, `Qubico/flux1-dev`, `Qubico/flux1-dev-advanced`	`txt2img`, `img2img`, `inpaint`, `controlnet-lora`, `redux-variation`	lowercase
Gemini	`gemini`	`nano-banana-text-to-image`, `nano-banana-edit`	lowercase
Kling	`kling`	`text2video`, `image2video`, `extend`, `lipsync`, `effects`	Capitalized
Luma	`luma`	`text2video`, `image2video`, `extend`	lowercase
Hailuo	`hailuo`	`text2video`, `image2video`, `subject2video`	lowercase
Veo 3	`veo3`	`txt2vid`, `img2vid`	lowercase
Seedance 2	`seedance`	`text-to-video`, `image-to-video`	lowercase
Hunyuan	`Qubico/hunyuan`	`txt2video-lora`, `img2video-lora`	lowercase
Suno	`music-u`	`generate_music`, `generate_music_custom`, `extend`, `concat`, `add_lyrics`	lowercase
MMAudio	`Qubico/mmaudio`	`video2audio`	lowercase
F5-TTS	`Qubico/f5-tts`	`txt2speech`	lowercase
Trellis	`Qubico/trellis`	`image-to-3d`	lowercase
Faceswap (image)	`Qubico/image-toolkit`	`face-swap`, `multi-face-swap`	Capitalized
Faceswap (video)	`Qubico/video-toolkit`	`face-swap`	Capitalized
LLM	OpenAI-style `model` (`gpt-4o-mini`, `claude-3-5-sonnet`, etc.)	n/a (sync `/v1/chat/completions`)	n/a

Status enum drift

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.

FilesExpand file tree

README.md

Latest commit

History