Context and Platform Integration
This initiative was developed as an internal tooling solution within the Freepik/Magnific API Platform. As the platform rapidly integrated new multimodal AI models (image generation, video, audio, and upscalers), the engineering team recognized the need for an automated mechanism to onboard new capabilities without repetitive manual tasks or multi-repository drift.
The Problem
Onboarding a new service into a public API platform is not a single code change: it requires six coordinated artifacts across independent architecture layers:
- The formal OpenAPI specification with typed parameters and schemas.
- The FastAPI controller and business logic implementation on the server.
- Perimeter route definitions, access permissions, and mUSD pricing rules on APISIX Gateway.
- Runtime-validated Pydantic models synchronized with the specification.
- Technical reference documentation for developers and B2B integrators on Mintlify.
- An interactive console entry with visual controls in the Next.js Playground.
Performing this process manually for each model family is viable but slow and prone to inconsistencies (e.g., parameter drift between spec and server, or unpropagated pricing rules on the gateway).
The Solution: Multi-Agent Orchestration
The team designed and built a system of specialized AI agents, where each agent operates as a domain expert across a specific technology stack, governed by a central orchestrator:
+-----------------------------------+
| Service Definition |
| (Single Source of Truth) |
+-----------------------------------+
|
+-----------------+-----------------+
| |
v v
+-----------------------------------+ +---------------------------------+
| Backend & Gateway Agents | | Frontend & Docs Agents |
| - Spec Agent (OpenAPI) | | - Docs Agent (Mintlify) |
| - Backend Agent (FastAPI / Tests)| | - Frontend Agent (Playground) |
| - Gateway Agent (APISIX / Costs) | | |
+-----------------------------------+ +---------------------------------+
|
v
+-----------------------------------+
| Human-in-the-Loop (HITL) |
| Coordinated Pull Request |
+-----------------------------------+
Human-in-the-Loop (HITL) Workflow
The system is deliberately designed around a Human-in-the-Loop (HITL) paradigm:
- Each generated artifact undergoes automated static analysis, type checking, and schema validation before being assembled into a unified change proposal.
- The engineering team reviews, validates, and approves the proposed changes in a secure environment before merging to production, ensuring that critical layers such as pricing, security permissions, and routing policies retain strict human oversight.
Artifacts Generated per Service
From a single formal service definition, the orchestrator coordinates the automated generation of:
- OpenAPI Specification: Standardized request/response schemas, parameters, and error models.
- FastAPI Controller: Typed asynchronous endpoints and parameter mappings to upstream inference providers.
- APISIX Gateway Rules: Routes, rate-limiting policies, and per-call mUSD pricing configurations.
- Pydantic Models: Runtime data validation models strictly synchronized with the OpenAPI spec.
- Public Documentation (Mintlify): Comprehensive reference guides, parameter tables, and cURL / SDK code snippets.
- Playground Console (Next.js): Reactive form components with tailored input controls and multimedia output viewers (image, video, audio).
Impact
- Onboarding Velocity: Reduced new model onboarding time from days to minutes.
- Zero Specification Drift: Guaranteed multi-layer consistency backed by a single authoritative source of truth.
- Ecosystem Standardization: Enforced architectural guidelines and naming conventions across the entire API Platform suite.