| name | piapi |
| version | 1.0.0 |
| author | Wesley Simplicio |
| license | MIT |
| platforms | ["macos","linux"] |
| description | Generate images, video, music, 3D, audio, and chat completions through
PiAPI's unified async-task gateway. Aggregates Midjourney, Flux, Kling,
Luma, Hailuo, Veo 3, Suno, Hunyuan, MMAudio, F5-TTS, Trellis, Gemini Nano
Banana, Seedance, and Faceswap behind a single `POST /api/v1/task` envelope,
plus an OpenAI-compatible `POST /v1/chat/completions` LLM proxy.
|
| metadata | {"hermes":{"tags":["creative","generation","image","video","music","3d","tts","llm","midjourney","flux","kling","suno","faceswap","veo3","gemini","seedance","hunyuan"],"related_skills":["wavespeed","comfyui","creative-campaign-media-studio"]}} |
| prerequisites | {"commands":["piapi-cli"],"env":["PIAPI_API_KEY"]} |
PiAPI (Hermes — Creative)
PiAPI is a single-gateway inference platform: every media job is a task on
POST /api/v1/task, polled via GET /api/v1/task/{task_id}. The LLM API at
POST /v1/chat/completions is OpenAI-compatible and synchronous (with
optional SSE streaming).
Prerequisites
export PIAPI_API_KEY="pk-..."
export PIAPI_WEBHOOK_SECRET="..."
piapi-cli --help
There is no official PiAPI SDK — the CLI uses pure requests. The shim
piapi-cli runs the bundled Python from ~/.local/share/piapi-skill/venv.
When to use
- A user prompt mentions Midjourney, Suno, Kling, Luma, Hailuo, Flux, Veo 3,
Gemini Nano Banana, Seedance, Hunyuan, MMAudio, F5-TTS, Trellis, or Faceswap.
- The pipeline needs a vendor-agnostic media generator and PiAPI is the
configured backend.
- Webhook callbacks from PiAPI need to be verified.
- An LLM call must go through PiAPI's OpenAI-compatible proxy.
When NOT to use
- The user already specified a competing platform (WaveSpeedAI, fal.ai,
Replicate, Runway) — use that one instead.
- The job is a direct vendor SDK call (e.g., the user explicitly wants the
official Suno API rather than PiAPI's wrapper).
- The flow is a creative-campaign chain that should stay in
creative-campaign-media-studio; only invoke piapi for the leaf step
that calls a model.
Quick reference
piapi-cli imagine "ultrarealistic mediterranean coast" --aspect-ratio 16:9 --process-mode fast --wait
piapi-cli flux --prompt "cyberpunk alley at night" --model Qubico/flux1-schnell --wait
piapi-cli submit --model gemini --task-type nano-banana-text-to-image \
--input '{"prompt":"a calico cat in a cafe"}' --webhook-url ...
piapi-cli kling --image-url URL --prompt "slow dolly forward, cinematic" --duration 5 --wait
piapi-cli run --model veo3 --task-type txt2vid \
--input '{"prompt":"a hummingbird in slow motion","aspect_ratio":"16:9","duration":8}'
piapi-cli run --model Qubico/hunyuan --task-type txt2video-lora \
--input '{"prompt":"...","lora_url":"https://.../lora.safetensors"}'
piapi-cli suno --prompt "warm lo-fi instrumental, vinyl crackle" --wait
piapi-cli run --model Qubico/f5-tts --task-type txt2speech \
--input '{"text":"Welcome to the demo.","voice_url":"https://.../voice.wav"}'
piapi-cli run --model Qubico/trellis --task-type image-to-3d \
--input '{"image_url":"https://.../object.png"}'
piapi-cli faceswap --target-url T --swap-url F --wait
piapi-cli submit --model <m> --task-type <t> --input '<json>' [--public|--private]
piapi-cli result <task_id>
piapi-cli wait <task_id> --timeout 1800 --poll-interval 2
piapi-cli cancel <task_id>
piapi-cli run --model <m> --task-type <t> --input '<json>'
piapi-cli llm --model gpt-4o-mini \
--message 'system:You are concise.' --message 'user:Hello.'
piapi-cli verify-webhook --header-secret "$RAW_HEADER" --expected "$PIAPI_WEBHOOK_SECRET"
Python (no SDK — uses requests)
import os, requests, time
API = "https://api.piapi.ai"
H = {"x-api-key": os.environ["PIAPI_API_KEY"], "Content-Type": "application/json"}
def submit(model: str, task_type: str, payload: dict, *, mode="public", webhook=None):
body = {"model": model, "task_type": task_type, "input": payload, "config": {"service_mode": mode}}
if webhook:
body["config"]["webhook_config"] = {"endpoint": webhook["url"], "secret": webhook["secret"]}
r = requests.post(f"{API}/api/v1/task", json=body, headers=H, timeout=60)
r.raise_for_status()
return r.json()["data"]["task_id"]
def wait(task_id: str, timeout=1800, poll=2):
deadline = time.time() + timeout
while time.time() < deadline:
r = requests.get(f"{API}/api/v1/task/{task_id}", headers=H, timeout=30)
r.raise_for_status()
data = r.json()["data"]
status = (data.get("status") or "").lower()
if status in {"completed", "complete", "success", "succeeded"}:
return data
if status in {"failed", "failure", "error", "canceled", "cancelled", "rejected"}:
raise RuntimeError(f"task {task_id} failed: {data.get('error') or data}")
time.sleep(poll)
raise TimeoutError(task_id)
REST primitives
| Method | Path | Purpose |
|---|
POST | /api/v1/task | Submit any media job. Returns task_id. |
GET | /api/v1/task/{task_id} | Poll status + fetch output URLs. |
DELETE | /api/v1/task/{task_id} | Cancel — only if status is pending. |
POST | /v1/chat/completions | OpenAI-compatible LLM. Sync; supports SSE. |
Auth header (lowercase canonical): x-api-key: <PIAPI_API_KEY>.
Status enum drift
PiAPI returns both capitalized and lowercase enums depending on the model
family. Always lowercase before comparing.
- Midjourney / Kling / Faceswap:
Pending | Processing | Staged | Completed | Failed
- Flux / Veo 3 / Gemini / Suno:
pending | starting | processing | success | failed | retry
Terminal-success: completed, complete, success, succeeded.
Terminal-failure: failed, failure, error, canceled, cancelled,
rejected. Anything else means keep polling.
Service modes
public — Pay-Per-Use (PPU). Default. Concurrency capped per pricing tier.private — Host-Your-Account (HYA). Required for Midjourney private mode
(Discord token + channel ID + guild ID). Higher upfront commit, no per-image
PPU charge after the seat fee.
Frequently-used model · task_type
| Family | model | task_type |
|---|
| Midjourney | midjourney | imagine, upscale, variation, inpaint, describe, blend |
| Flux | Qubico/flux1-schnell / Qubico/flux1-dev / Qubico/flux1-dev-advanced | txt2img, img2img, inpaint, controlnet-lora, redux-variation |
| Kling | kling | text2video, image2video, extend, lipsync, effects |
| Luma | luma | text2video, image2video, extend |
| Hailuo | hailuo | text2video, image2video, subject2video |
| Veo 3 | veo3 | txt2vid, img2vid |
| Seedance | seedance | text-to-video, image-to-video |
| Suno | music-u | generate_music, generate_music_custom, extend, concat, add_lyrics |
| Hunyuan | Qubico/hunyuan | txt2video-lora, img2video-lora |
| MMAudio | Qubico/mmaudio | video2audio |
| Faceswap | Qubico/image-toolkit / Qubico/video-toolkit | face-swap, multi-face-swap |
| Trellis | Qubico/trellis | image-to-3d |
| F5-TTS | Qubico/f5-tts | txt2speech |
| Gemini Image | gemini | nano-banana-text-to-image, nano-banana-edit |
Latency knobs
- Midjourney
process_mode: fast (default), turbo (~half wait, costs more),
relax (cheapest, queues for minutes).
- Flux:
flux1-schnell is the speed model (~4 steps); flux1-dev is the
quality model (~28 steps).
- Kling:
mode = std | pro and duration = 5 | 10 seconds.
- Suno: set
custom_mode=true to control lyrics + style; otherwise PiAPI fills
both from the prompt.
Troubleshooting
401: PIAPI_API_KEY missing or wrong header casing — header must be
exactly x-api-key.402: out of credits or no active plan.429: tier concurrency cap hit — back off, do not hammer.- Status stuck
Staged for Midjourney: that family stages an interactive grid;
follow up with upscale / variation task_types.
- Webhook didn't fire: confirm endpoint returns
2xx quickly — PiAPI retries
every 5s up to 3 attempts only.
References
