# Piapi

> PiAPI inference gateway — image, video, music, 3D, audio, and LLM generation through one async-task envelope and an OpenAI-compatible LLM proxy.

- **Type:** Skill
- **Install:** `agentstack add skill-wesleysimplicio-piapi-skills-cursor`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [wesleysimplicio](https://agentstack.voostack.com/s/wesleysimplicio)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [wesleysimplicio](https://github.com/wesleysimplicio)
- **Source:** https://github.com/wesleysimplicio/PiAPI-Skills/tree/main/agents/cursor

## Install

```sh
agentstack add skill-wesleysimplicio-piapi-skills-cursor
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# PiAPI (Cursor)

Single envelope:

```
POST /api/v1/task    { model, task_type, input, config? }
GET  /api/v1/task/{task_id}
DELETE /api/v1/task/{task_id}     # only while status is pending
POST /v1/chat/completions          # OpenAI-compatible LLM
```

Auth header (lowercase): `x-api-key: `.

## When to invoke

User asks for media generation (Midjourney, Suno, Kling, Luma, Hailuo, Flux,
Veo 3, Gemini Nano Banana, Seedance, Hunyuan, MMAudio, F5-TTS, Trellis,
Faceswap), or for an OpenAI-compatible LLM call routed through PiAPI, or for
PiAPI webhook verification.

## Setup

```bash
export PIAPI_API_KEY="pk-..."
export PIAPI_WEBHOOK_SECRET="..."   # optional
piapi-cli --help
```

There is no official PiAPI SDK. The CLI uses pure HTTP via `requests`.

## Cheatsheet

```bash
# Generic
piapi-cli submit  --model  --task-type  --input ''
piapi-cli result  
piapi-cli wait     --timeout 1800 --poll-interval 2
piapi-cli cancel  
piapi-cli run     --model  --task-type  --input ''

# Shortcuts
piapi-cli imagine "prompt" --aspect-ratio 16:9 --process-mode fast --wait
piapi-cli flux    --prompt "..." --model Qubico/flux1-schnell --wait
piapi-cli kling   --image-url URL --prompt "..." --duration 5 --wait
piapi-cli suno    --prompt "lofi instrumental" --wait
piapi-cli faceswap --target-url T --swap-url F --wait

# LLM
piapi-cli llm --model gpt-4o-mini \
  --message 'system:You are concise.' --message 'user:Hello.'

# Webhook verify (no HMAC — string compare against echoed secret)
piapi-cli verify-webhook --header-secret "$RAW_HEADER" --expected "$PIAPI_WEBHOOK_SECRET"
```

## Status enum drift

Lowercase the `status` field before comparing.

Terminal-success: `completed`, `complete`, `success`, `succeeded`.
Terminal-failure: `failed`, `failure`, `error`, `canceled`, `cancelled`,
`rejected`.

## Common model · task_type

| Family | model | task_type |
|---|---|---|
| Midjourney | `midjourney` | `imagine`, `upscale`, `variation`, `inpaint`, `blend`, `describe` |
| Flux | `Qubico/flux1-schnell` / `Qubico/flux1-dev` | `txt2img`, `img2img`, `inpaint`, `controlnet-lora` |
| 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` |
| 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` |

## Refs

- https://piapi.ai/docs/overview
- https://piapi.ai/docs/llm-api
- https://piapi.ai/pricing

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [wesleysimplicio](https://github.com/wesleysimplicio)
- **Source:** [wesleysimplicio/PiAPI-Skills](https://github.com/wesleysimplicio/PiAPI-Skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-wesleysimplicio-piapi-skills-cursor
- Seller: https://agentstack.voostack.com/s/wesleysimplicio
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.