Plataforma de APIs de Freepik/Magnific y Landings Públicas

Contexto

Magnific opera una plataforma pública de APIs de inteligencia artificial que expone modelos multimodales (generación de imagen, text-to-video, image-to-video, generación de audio, upscalers y herramientas de edición) tanto a desarrolladores externos y clientes B2B como a productos internos (como Pikaso y suites creativas).

Al escalar de un conjunto inicial de endpoints a un ecosistema con más de 350 endpoints y decenas de modelos de IA de proveedores punteros e internos, el equipo implementó una arquitectura distribuida, resiliente y fuertemente gobernada. El proyecto abarcó desde el desarrollo del frontend de las landings públicas de producto y tableros de control hasta la infraestructura de gateway, microservicios de gestión en backend con DDD, la especificación de contratos y la automatización del alta de servicios con agentes de IA.

Superficie pública y landings de producto (Frontend)

Como parte central del trabajo de frontend de la API, se desarrollaron y evolucionaron las landings públicas de producto donde los desarrolladores y empresas exploran las capacidades de la plataforma:

• Landing Principal de la API: Puerta de entrada comercial y técnica que presenta la suite completa de modelos, casos de uso, arquitectura de integración y tablas de precios.
• API de Generación de Imágenes: Landing especializada con comparadores visuales interactivos, selectores de estilo, resolución y parámetros de renderizado.
• API de Image Upscaler: Landing enfocada en herramientas de superresolución y mejora de detalle con controles de comparación before/after en tiempo real.
• Playground Interactivo (Next.js) y Documentación (Mintlify): Consola interactiva para probar modelos directamente desde el navegador y referencia técnica unificada para clientes B2B.

El desarrollo frontend se centró en construir componentes reutilizables y de alto rendimiento en Next.js, React y TypeScript, priorizando tiempos de carga mínimos, animaciones fluidas y una presentación clara de parámetros técnicos complejos.

Tableros de gestión de API keys y estadísticas (Full-Stack)

Para que desarrolladores y clientes corporativos pudieran gobernar su integración y supervisar el consumo en tiempo real, se diseñó e implementó la suite de tableros de gestión:

• Frontend (Next.js / React): Panel de control intuitivo y seguro para la generación, rotación y revocación de API keys, visualización de métricas de consumo en tiempo real, desglose analítico de uso por modelo y resolución, y monitorización de cuotas y saldos de facturación.
• Backend (PHP / Domain-Driven Design): Microservicios desacoplados construidos bajo arquitectura hexagonal y patrones de Domain-Driven Design (DDD), encargados de la gobernanza de identidades, auditoría de eventos de consumo, persistencia en MySQL y capas de cache y rate limiting distribuido con Redis sobre infraestructura en Google Cloud Platform (GCP).

Arquitectura y ciclo de vida en 3 fases

La arquitectura de la plataforma se diseñó e implementó estructurada en tres fases desacopladas, orquestadas a partir de una especificación central como contrato estricto (Single Source of Truth):

+-------------------------------------------------------------------------+
|                       FASE 1: DEFINICIÓN (SPEC)                         |
|   Contrato OpenAPI centralizado · Convenciones unificadas · Validaciones |
+-------------------------------------------------------------------------+
                                    |
                  +-----------------+-----------------+
                  |                                   |
                  v                                   v
+-----------------------------------+   +---------------------------------+
|  FASE 2: PUBLICACIÓN & GATEWAY    |   |  FASE 3: CONSUMO ASÍNCRONO      |
|  - APISIX: Auth, Rate Limits,     |   |  - Clientes B2B, Web & SDKs     |
|    reserva/débito créditos (mUSD) |   |  - Patrón 202 Accepted + Task ID|
|  - FastAPI: Server & Validaciones |   |  - Retorno vía Webhook / Polling|
|  - Docs (Mintlify) & Playground   |   |  - Conciliación de wallet       |
+-----------------------------------+   +---------------------------------+

1. Fase 1: Definición (Contract-First OpenAPI)

Toda la plataforma se gobierna a partir del contrato formal de OpenAPI:

• Fuente única de verdad: Los esquemas de petición y respuesta, tipos de datos, parámetros obligatorios/opcionales y metadatos de costes se definen de manera unificada antes de iniciar cualquier desarrollo de backend o gateway.
• Estandarización y consistencia: Convenciones homogéneas de nomenclatura (snake_case), modelos de error HTTP estándar (400, 401, 402, 422, 429, 500) y estructuras de respuesta predecibles en toda la suite.

2. Fase 2: Publicación y Gobierno de Infraestructura

• API Gateway perimetral (Apache APISIX):
  • Autenticación e Identidad: Validación centralizada de credenciales (x-magnific-api-key).
  • Políticas de Rate Limiting: Cuotas de consumo y límites de peticiones concurrentes/diarias diferenciados por nivel de suscripción (Free, Pro, Enterprise).
  • Tarificación y Control de Créditos: Cálculo de costes en unidades base de moneda (mUSD) con reserva preventiva (hold) de créditos al recibir la solicitud y conciliación final post-ejecución.
• Servidor de Aplicación (FastAPI):
  • Controladores y servicios asíncronos en Python con modelos Pydantic derivados de la especificación.
  • Validación estricta de parámetros en tiempo de ejecución, enrutamiento a proveedores de inferencia y persistencia de estados de ejecución.
• Documentación (Mintlify) y Playground (Next.js):
  • Generación automatizada de la documentación de referencia pública y B2B a partir de la especificación.
  • Integración con el Playground interactivo web, asegurando que los formularios y esquemas de prueba coincidan exactamente con las capacidades en producción.

3. Fase 3: Consumo y Ciclo de Vida Asíncrono de Tareas

Las operaciones de IA generativa (como generación de vídeo de alta definición o audio) requieren tiempos de procesamiento no instantáneos. Se estandarizó el patrón de consumo asíncrono para garantizar resiliencia y alta concurrencia:

1. Admisión Inmediata (202 Accepted): El cliente envía la solicitud, el gateway valida la clave y reserva los créditos estimados, y el servidor genera un task_id único devolviendo respuesta inmediata sin bloquear conexiones.
2. Procesamiento y Notificación Dual:
   • Webhooks HTTP: Entrega reactiva del resultado completo en la URL configurada por el cliente apenas finaliza la inferencia.
   • Polling Estructurado: Endpoint específico de consulta por task_id para clientes en navegadores o entornos sin soporte de endpoints públicos entrantes.
3. Liquidación y Conciliación de Créditos: Al completarse la tarea, el sistema liquida con exactitud el coste consumido en la billetera de créditos del usuario; si la tarea falla o expira por timeout del proveedor, los créditos reservados se liberan automáticamente.

Flujo típico para un nuevo modelo

Para llevar un nuevo modelo de IA desde la fase conceptual hasta su disponibilidad pública, el equipo sigue un pipeline sistemático:

1. Investigación del modelo y diseño del contrato: Se analizan las capacidades del proveedor y se redacta la especificación OpenAPI con sus parámetros y tipados.
2. Validación automática: Se ejecutan linters y validadores de esquemas para garantizar que el contrato respeta las directrices globales.
3. Implementación en el servidor: Se desarrollan los controladores asíncronos en FastAPI y se ejecutan las suites de tests unitarios y de integración.
4. Configuración en el Gateway: Se establecen las rutas en APISIX, las políticas de rate limiting y la tarificación en mUSD para el modelo.
5. Generación de Documentación y Playground: Se sincronizan las páginas de referencia en Mintlify y se habilita la interfaz visual en el Playground de Next.js.
6. Integración Continua y Despliegue: Se valida el conjunto completo en el pipeline de CI/CD antes del despliegue a producción.

Desarrollo acelerado mediante agentes de IA especializados

Para escalar la incorporación de modelos y mantener la coherencia en múltiples capas sin fricción manual, el equipo implementó un ecosistema de agentes de IA especializados, donde cada agente opera sobre un dominio específico con supervisión humana (Human-in-the-Loop):

• Agente de Especificaciones: Especializado en el estándar OpenAPI; a partir de la documentación y capacidades del nuevo modelo, redacta y valida la definición formal de esquemas, parámetros y tipos de datos.
• Agente de Backend: Genera los controladores en FastAPI, modelos Pydantic y tests unitarios siguiendo los patrones de diseño y manejo de errores del servidor.
• Agente de Plataforma / Gateway: Configura las reglas de enrutamiento en el gateway, define los permisos asociados, las políticas de cuota y el esquema de tarificación por llamada.
• Agente de Documentación: Genera la documentación técnica de referencia para desarrolladores y clientes B2B, incluyendo descripciones y ejemplos de llamada cURL y SDKs en Mintlify.
• Agente de Frontend: Implementa la interfaz correspondiente en el Playground interactivo, generando los formularios de control validados y los visores multimedia según el tipo de salida (imagen, vídeo, audio).

Este enfoque permite al equipo validar y aprobar cambios completos y coordinados en minutos, manteniendo estándares rigurosos de calidad y evitando cualquier inconsistencia entre la especificación y el runtime.

Para conocer en detalle la arquitectura del orquestador, el diseño de prompts y el flujo de generación por capas, consulta el caso de estudio técnico: Integración de servicios automatizada a través de IA.

Gobernanza multi-repositorio y sincronización continua

Para eliminar la deriva (drift) entre la especificación, el servidor backend, el gateway perimetral, la documentación pública y el frontend de pruebas, se estableció un flujo de propagación automatizado:

• La especificación OpenAPI se integra como submódulo y referencia única en los repositorios de aplicación y documentación.
• Tooling automatizado de validación y generación de tipos que comprueba que ninguna ruta del gateway ni modelo de FastAPI quede desalineado con respecto a la especificación activa.
• Pipelines de CI/CD que ejecutan suites de pruebas unitarias, integración y validación estricta de esquemas antes de cada despliegue a producción.

Resultado e Impacto

• Superficie pública de alto impacto: Landings de producto de alto rendimiento visual en producción (magnific.com/api, image-generation, image-upscaler).
• Tableros de analítica y gestión: Interfaces reactivas y servicios backend DDD de alta disponibilidad para la administración segura de credenciales y estadísticas de consumo.
• Plataforma robusta y escalable: Más de 350 endpoints gobernados y más de 40 modelos multimodales integrados con control de costes en tiempo real y alta disponibilidad.
• Experiencia de desarrollador consistente: Contratos tipados, tiempos de respuesta predecibles mediante patrón asíncrono y documentación pública interactiva que refleja con total fidelidad el estado de producción.
• Onboarding ágil: Proceso repetible y automatizado mediante agentes de IA para incorporar nuevas familias de modelos sin requerir desarrollos manuales ad-hoc en los sistemas de facturación y gateway.