Piapi

PiAPI

PiAPI is a unified async-task gateway for many third-party generative models. Every media request goes through one envelope:

POST /api/v1/task
{
  "model": "<vendor-or-family>",
  "task_type": "<task>",
  "input": { ... },
  "config": { "service_mode": "public", "webhook_config": { ... } }
}

Polling and result fetching are uniform via GET /api/v1/task/{task_id}. The LLM API at POST /v1/chat/completions is the only synchronous surface and is OpenAI-compatible (including streaming).

When to use

• Generate images (Midjourney, Flux, Gemini Nano Banana).
• Generate video (Kling, Luma, Hailuo, Veo 3, Seedance, Hunyuan).
• Generate music (Suno, Udio via music-u, MMAudio for sfx).
• TTS / voice (F5-TTS).
• 3D assets (Trellis).
• Faceswap (Qubico/image-toolkit, Qubico/video-toolkit).
• LLM chat completions (any model exposed under PiAPI's OpenAI proxy).
• Webhook handlers that consume PiAPI callbacks.

When NOT to use

• The user wants direct vendor access (use the vendor's own API/SDK).
• The user wants WaveSpeedAI, Replicate, or fal.ai — different platforms.
• The user only needs ChatGPT/Claude prompt completion with no media generation and you already have a direct API for that LLM.

Prereqs

export PIAPI_API_KEY="pk-..."     # required, sent as x-api-key header
export PIAPI_WEBHOOK_SECRET="..." # only when verifying inbound webhooks

The shim piapi-cli runs the bundled Python in its own venv at ~/.local/share/piapi-skill/venv. Do not pip-install piapi — there is no official SDK; the CLI uses pure requests.

Quick reference

Image — Midjourney imagine

piapi-cli imagine \
  "ultrarealistic mediterranean coast, sunset" \
  --aspect-ratio 16:9 --process-mode fast --wait

Image — Flux text-to-image

piapi-cli flux \
  --prompt "neon-lit cyberpunk alley, rain reflections" \
  --model Qubico/flux1-schnell --width 1024 --height 1024 --wait

Video — Kling image-to-video

piapi-cli kling \
  --image-url https://example.com/in.jpg \
  --prompt "camera dolly forward, soft cinematic" \
  --duration 5 --aspect-ratio 16:9 --wait

Music — Suno

piapi-cli suno \
  --prompt "warm lo-fi hip hop, vinyl crackle, mellow" \
  --custom-mode false --make-instrumental false --wait

Faceswap — single image

piapi-cli faceswap \
  --target-url https://example.com/target.jpg \
  --swap-url   https://example.com/face.jpg \
  --wait

Generic submit / wait / cancel

piapi-cli submit --model midjourney --task-type imagine \
  --input '{"prompt":"a samurai cat","aspect_ratio":"3:2","process_mode":"fast"}' \
  --webhook-url https://yourapp/api/piapi --webhook-secret "$PIAPI_WEBHOOK_SECRET"

piapi-cli result <task_id>
piapi-cli wait   <task_id> --timeout 1800 --poll-interval 2
piapi-cli cancel <task_id>     # only valid while status is pending

One-shot run (submit + wait)

piapi-cli run --model Qubico/flux1-schnell --task-type txt2img \
  --input '{"prompt":"misty forest","width":1024,"height":1024}'

LLM chat completion

piapi-cli llm --model gpt-4o-mini \
  --message 'system:You are concise.' \
  --message 'user:Summarize Stoicism in one sentence.'

piapi-cli llm --model claude-3-5-sonnet --stream --message 'user:Hi'

Verify a webhook

piapi-cli verify-webhook \
  --header-secret "$X_WEBHOOK_SECRET_FROM_REQUEST" \
  --expected      "$PIAPI_WEBHOOK_SECRET"

REST primitives

Auth header (lowercase canonical):

x-api-key: <PIAPI_API_KEY>

Status enum drift (important)

Different model families return different status casing. The CLI normalizes every status to lowercase before comparing:

• Capitalized family (Midjourney, Kling, Faceswap): Pending | Processing | Staged | Completed | Failed
• Lowercase family (Flux, Veo 3, Gemini, Suno): pending | starting | processing | success | failed | retry

Treat as terminal-success: completed | complete | success | succeeded. Treat as terminal-failure: failed | failure | error | canceled | cancelled | rejected. Anything else = still running, 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.

Set via --public / --private on submit and run, or include {"config":{"service_mode":"private"}} in raw payloads.

Frequently-used model · task_type

Latency knobs

• Midjourney: process_mode = fast | turbo | relax. fast is the default rate; turbo costs more but is roughly half the wait; relax is cheapest but can sit minutes in queue.
• Flux: flux1-schnell ≈ 4 steps, fastest; flux1-dev ≈ 28 steps, higher quality.
• Kling: mode = std | pro and duration = 5 | 10 seconds.
• Suno: custom_mode = true lets you pin lyrics + style; otherwise PiAPI fills both.

Error surface

• 400 — bad input shape. Check model + task_type combo first; many failures are wrong task_type for the family.
• 401 — missing or invalid x-api-key.
• 402 — out of credits or no active plan.
• 429 — concurrency cap or RPM cap exceeded for the tier.
• 500 / 502 — upstream model error. Retry with backoff; PiAPI returns retry status for transient cases.

Tier rate limits (snapshot, verify in pricing page)

References

• Overview & quickstart: https://piapi.ai/docs/overview
• Per-model docs: https://piapi.ai/docs/{midjourney,kling,suno,flux,faceswap,...}
• LLM API: https://piapi.ai/docs/llm-api
• MCP server: https://piapi.ai/docs/mcp-server
• Pricing: https://piapi.ai/pricing