piapi-skills 1.2.0

Provider-agnostic CLI for the PiAPI inference platform — Midjourney, Flux, Kling, Suno, Hailuo, Veo 3, Hunyuan, Faceswap, Trellis 3D, MMAudio, F5-TTS and the OpenAI-compatible LLM proxy. Single-file Python with a thin shell shim, plus skill bundle for Claude Code, Codex, Hermes, OpenClaw.

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

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.

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:

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

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.