PiAPI

Generates images through Midjourney, Flux, or Hunyuan by translating MCP tool calls into PiAPI requests, handling asynchronous task polling, and returning generated image URLs. Uses a request-response pattern where clients submit structured prompts and receive URLs to completed assets after polling for task completion status.

Generates videos through Kling, Luma Dream Machine, Hunyuan Video, Skyreels, Wan, or Hailuo by submitting text prompts or image-to-video requests to PiAPI and polling for completion. Supports both text-to-video and image-to-video workflows with model-specific parameters (duration, quality, effects).

Validates generation results from PiAPI (image URLs, video URLs, audio URLs, 3D model URLs) against expected formats and accessibility. Checks that URLs are valid HTTPS links, files are accessible, and metadata matches the request. Formats results into MCP-compatible response objects with structured metadata (dimensions, duration, file size, format). Handles missing or malformed results gracefully.

Provides Docker configuration for containerized deployment of the PiAPI MCP server, including Dockerfile, docker-compose.yml, and environment variable templates. Supports both development (with hot-reload) and production (optimized image size) builds. Enables easy deployment to Kubernetes, Docker Swarm, or cloud container services (AWS ECS, Google Cloud Run, Azure Container Instances).

Integrates with the Smithery platform to enable one-click deployment of the PiAPI MCP server to Smithery's managed hosting. Provides Smithery-specific configuration and deployment manifests. Handles authentication, environment variable setup, and server lifecycle management through Smithery's UI.

Provides a TypeScript-based framework for extending the MCP server with new AI generation tools. Developers can add new tools by implementing a standard interface (tool name, description, parameters, handler function) and registering them in the tool registry. Includes utilities for schema generation, parameter validation, and result formatting. Supports both synchronous and asynchronous tool implementations.

Manages PiAPI credentials and server configuration through environment variables, supporting both .env files and system environment variables. Validates required configuration at startup and provides helpful error messages for missing credentials. Supports configuration overrides for different deployment environments (development, staging, production) through environment-specific .env files.

Generates music and audio through Suno, MMAudio, or zero-shot TTS by submitting prompts with style/mood parameters to PiAPI. Supports both standalone music generation and video-synchronized audio generation (MMAudio generates music matching video content). Uses asynchronous task polling to retrieve generated audio files.

Performs image transformations (face swap, background removal, segmentation, upscaling) by submitting images to PiAPI and retrieving processed results. Each operation uses specialized models: face swap uses identity-preserving diffusion, RMBG uses semantic segmentation, upscaling uses super-resolution networks. Operations are stateless and return processed image URLs.

Applies transformations to existing videos (face swap, upscaling) by submitting video URLs to PiAPI and polling for processed results. Uses frame-by-frame processing with temporal consistency to maintain coherence across video frames. Returns processed video URLs with metadata about processing time and output format.

Generates 3D models (in GLB or OBJ format) from text descriptions or reference images using the Trellis model via PiAPI. Submits prompts or image URLs and polls for completion, returning downloadable 3D model files. Supports both text-to-3D and image-to-3D workflows with configurable mesh density and texture quality.

Implements a polling-based task management system where clients submit generation requests and receive task IDs, then poll for completion status until results are ready. Uses exponential backoff and configurable timeout logic to avoid overwhelming the PiAPI backend. Tracks task state (pending, processing, completed, failed) and returns results or error messages based on final status.

Manages a registry of 15+ AI generation tools organized by category (image, video, audio, 3D) with model-specific configuration objects (FLUX_MODEL_CONFIG, KLING_MODEL_CONFIG, etc.). Tools are dynamically loaded from configuration files and exposed as MCP tools with schema validation. Supports enabling/disabling tools and switching between models without code changes through environment variables or config files.

Implements the Model Context Protocol (MCP) server specification, exposing all generation tools as MCP tools with JSON schema definitions for parameters and outputs. Handles MCP request/response serialization, tool invocation, and error handling. Integrates with MCP-compatible clients (Claude Desktop, Cursor IDE) through stdio transport or network sockets, enabling seamless tool calling from AI assistants.

Manages HTTP communication with the PiAPI backend service, handling request serialization, response parsing, and error recovery. Implements timeout and retry logic with exponential backoff for transient failures (network timeouts, rate limits). Translates PiAPI error responses into MCP-compatible error messages. Supports both synchronous requests (tool registration) and asynchronous task polling.