StoryReel AI — Backend Service

Concepto

StoryReel AI es una plataforma SaaS B2B que convierte guiones de texto en vídeos de marketing listos para redes sociales. Inspirado en Zebracat, resuelve el cuello de botella que enfrentan equipos de marketing, pymes y freelancers al producir vídeos de calidad de forma rápida y económica.

---

Arquitectura

┌─────────────┐   REST/JSON   ┌──────────────────────────────────────────────┐
│  Frontend   │ ────────────▶ │              Spring Boot 4 API               │
│  (React /   │               │                                              │
│   Mobile)   │ ◀──────────── │  AuthController  ProjectController  Library  │
└─────────────┘   JWT Bearer  │       │               │               │      │
                              │  AuthService   VideoProjectService   Enum    │
                              │       │               │             Catalog  │
                              │  JwtUtil     VideoGenerationService          │
                              │              (Virtual Threads @Async)        │
                              │         ┌───────────────────────────┐        │
                              │         │  StockVideoService        │        │
                              │         │  TextToSpeechService      │        │
                              │         │  StorageService           │        │
                              │         └────────┬──────────────────┘        │
                              └──────────────────┼────────────────────────── ┘
                                                 │
                              ┌──────────────────┼───────────────────────────┐
                              │  External APIs   │                           │
                              │  ┌───────────────▼──────┐                   │
                              │  │  Pexels Video API    │  (stock clips)     │
                              │  ├──────────────────────┤                   │
                              │  │  ElevenLabs TTS API  │  (narration audio) │
                              │  ├──────────────────────┤                   │
                              │  │  AWS S3 / GCS        │  (video storage)   │
                              │  └──────────────────────┘                   │
                              └─────────────────────────────────────────────┘

Capas

Capa	Paquete	Responsabilidad
Controller	controller	REST endpoints, validación de entrada, resolución del principal JWT
Service	service	Lógica de negocio, orchestración de pipeline, verificación de límites de plan
Async	%%INLINE2%%	Pipeline de rendering en virtual threads (%%INLINE3%%)
Feign	feign	Clientes declarativos para Pexels y ElevenLabs
Security	security	JwtUtil · JwtAuthFilter · UserDetailsServiceImpl
Model	%%INLINE6%%	Entidades JPA: %%INLINE7%%, VideoProject
Repository	repository	Spring Data JPA interfaces

---

Endpoints

Autenticación (público — no requiere JWT)

Método	Path	Descripción
%%INLINE10%%	%%INLINE11%%	Registro de nuevo usuario (plan FREE)
%%INLINE12%%	%%INLINE13%%	Login con e-mail + password → JWT

Request – Register:

{
  "email": "ana@startup.com",
  "password": "SuperSecret1!",
  "displayName": "Ana García"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "email": "ana@startup.com",
  "displayName": "Ana García",
  "plan": "FREE"
}

---

Proyectos (requiere Authorization: Bearer <token>)

Método	Path	Descripción
%%INLINE15%%	%%INLINE16%%	Crea proyecto y lanza pipeline asíncrono
%%INLINE17%%	%%INLINE18%%	Lista proyectos del usuario autenticado
%%INLINE19%%	%%INLINE20%%	Estado de un proyecto (polling para saber si está COMPLETED)
%%INLINE21%%	%%INLINE22%%	Actualiza logo y color de marca

Request – Create Project:

{
  "title": "Lanzamiento Producto Q1",
  "script": "Presentamos nuestro nuevo software que revoluciona la gestión de proyectos. Con IA integrada, tu equipo será 3x más productivo.",
  "voice": "NOVA",
  "musicTrack": "UPBEAT_CORPORATE",
  "logoUrl": "https://mybrand.com/logo.png",
  "brandColor": "#1A73E8"
}

Response – Project (PENDING / PROCESSING / COMPLETED):

{
  "id": 42,
  "title": "Lanzamiento Producto Q1",
  "status": "COMPLETED",
  "downloadUrl": "https://cdn.storyreel.ai/videos/project-42/output.mp4",
  "exportResolution": "720p",
  "watermarked": true,
  "voice": "NOVA",
  "musicTrack": "UPBEAT_CORPORATE",
  "logoUrl": "https://mybrand.com/logo.png",
  "brandColor": "#1A73E8",
  "createdAt": "2026-05-30T10:00:00",
  "updatedAt": "2026-05-30T10:00:02"
}

---

Librería (público — no requiere JWT)

Método	Path	Descripción
%%INLINE23%%	%%INLINE24%%	Lista pistas de música disponibles
%%INLINE25%%	%%INLINE26%%	Lista voces de IA disponibles

---

Pipeline de Generación Asíncrona

POST /projects
     │
     ├─ 1. Valida límite mensual del plan (FREE: 3, CREATOR: 20, BUSINESS: 100)
     ├─ 2. Persiste VideoProject con status=PENDING
     ├─ 3. Retorna 202 Accepted inmediatamente al cliente
     │
     └─ [Virtual Thread — videoTaskExecutor]
          ├─ 4. Extrae palabras clave del guion por frase
          ├─ 5. Busca clips en Pexels API (una consulta por keyword)
          ├─ 6. Genera audio TTS vía ElevenLabs API
          ├─ 7. Simula render FFmpeg (combina clips + audio + música + logo)
          ├─ 8. Sube MP4 a AWS S3 / GCS
          └─ 9. Actualiza status=COMPLETED + downloadUrl

El cliente hace polling a %%INLINE27%% hasta que %%INLINE28%%.

---

Planes y Monetización

Plan	Videos/mes	Marca de agua	Resolución	Precio
FREE	3	✅ Sí	720p	Gratis
CREATOR	20	❌ No	1080p	~$29/mes
BUSINESS	100	❌ No	4K	~$99/mes

---

Features MVP Implementadas

Feature	Implementación
Texto-a-Video	%%INLINE29%% → %%INLINE30%% → Pexels API
TTS con IA	TextToSpeechService → ElevenLabs API, 6 voces disponibles
Kit de Marca	%%INLINE32%%, campos %%INLINE33%% + %%INLINE34%% en %%INLINE35%%
Música de Fondo	Enum %%INLINE36%% con 5 pistas, %%INLINE37%%
Exportación HD	Resolución derivada del plan (%%INLINE38%% / %%INLINE39%% / 4K), marca de agua en FREE
Autenticación JWT	Spring Security 7 + JJWT 0.12.6, stateless
Jobs en Background	@Async("videoTaskExecutor") con virtual threads de Java 25

---

Stack Técnico

• Java 25 — Records, Virtual Threads, var, text blocks, pattern matching
• Spring Boot 4.0.4 + Spring Framework 7.x
• Spring Security 7 — JWT stateless, SecurityFilterChain
• Spring Data JPA + Jakarta Persistence 3 — PostgreSQL en producción
• Spring Cloud OpenFeign 4.2.1 — clientes declarativos para APIs externas
• JJWT 0.12.6 — firma HS256
• Jackson 3 (tools.jackson.*) — serialización JSON
• MapStruct 1.6.3 — soporte para mapping (preparado para expansión)

---

Cómo Ejecutar

Pre-requisitos

• Java 25
• PostgreSQL 16+ (o H2 para desarrollo)
• Maven 3.9+

Variables de entorno / application.yml

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/storyreel
    username: storyreel
    password: changeme
  jpa:
    hibernate:
      ddl-auto: create-drop   # update en producción

app:
  jwt:
    secret: TuSecreto256BitsParaHMAC_SHA256
    expiration-ms: 86400000        # 24 horas
  pexels:
    base-url: https://api.pexels.com
    api-key: TU_PEXELS_API_KEY
  elevenlabs:
    base-url: https://api.elevenlabs.io
    api-key: TU_ELEVENLABS_API_KEY
  storage:
    base-url: https://cdn.storyreel.ai

Compilar y ejecutar

# Compilar
mvn clean compile

# Ejecutar
mvn spring-boot:run

# O con Docker
docker build -t storyreel-api .
docker run -p 8080:8080 \
  -e SPRING_DATASOURCE_URL=jdbc:postgresql://host:5432/storyreel \
  storyreel-api

Flujo de prueba rápido

# 1. Registrar usuario
curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@test.com","password":"Password1!","displayName":"Dev User"}'

# 2. Login → obtener token
TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@test.com","password":"Password1!"}' | jq -r .token)

# 3. Ver voces disponibles (público)
curl http://localhost:8080/api/v1/library/voices

# 4. Crear proyecto (lanza pipeline asíncrono)
PROJECT=$(curl -s -X POST http://localhost:8080/api/v1/projects \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Mi primer video",
    "script": "Bienvenidos a StoryReel AI. La plataforma que convierte tus ideas en videos virales.",
    "voice": "NOVA",
    "musicTrack": "UPBEAT_CORPORATE",
    "brandColor": "#FF5733"
  }')
PROJECT_ID=$(echo $PROJECT | jq -r .id)

# 5. Polling hasta COMPLETED
curl http://localhost:8080/api/v1/projects/$PROJECT_ID \
  -H "Authorization: Bearer $TOKEN"

---

Referencias

• Inspiración: Zebracat.ai
• Product Hunt (Jun 2024): Leaderboard
• Pexels Video API
• ElevenLabs TTS API
• Spring Boot 4 Docs
• JJWT 0.12.x

---

FinOps Analysis para StoryReel AI

Resumen de Costos y Rentabilidad

StoryReel AI, con su propuesta de valor de generación de video automatizada, presenta una estructura de costos que, aunque intensiva en APIs externas, permite un margen de beneficio saludable incluso en sus etapas iniciales con una base de clientes modesta. La clave del éxito FinOps residirá en la gestión proactiva de los costos de las APIs y la infraestructura cloud.

• Ingreso Mensual Estimado: $870 (basado en 20 clientes iniciales distribuidos entre planes 'Creator' y 'Business').
• Costo Mensual Total Estimado: $374

- LLM (Análisis de Guiones): $20 (estimado para ~5M tokens/mes usando gpt-4o-mini o similar para extracción de palabras clave y análisis de guiones). - Infraestructura Cloud (AWS/GCP/Azure): $75 - Compute (ej. AWS t3.small): ~$30 - Base de Datos (ej. AWS RDS db.t3.micro PostgreSQL): ~$15 - Almacenamiento (ej. AWS S3 para 100GB de videos): ~$3 - Transferencia de Datos (Egress para descargas de video): ~$9 - CDN (ej. AWS CloudFront básico para optimizar entrega): ~$18 - APIs Externas: $279 - Text-to-Speech (ej. OpenAI TTS para 600K tokens): ~$9 - Stock Video API (ej. suscripción básica a Storyblocks o similar): ~$100 - Servicio de Renderizado de Video (ej. Shotstack o similar para 3000 minutos de video HD): ~$170

• Margen de Beneficio Estimado: 57%

Desglose Detallado y Consideraciones

Los costos operativos se centran principalmente en las integraciones con APIs de terceros, especialmente para la obtención de contenido de video (stock footage) y el renderizado final del video. La infraestructura base para el servicio Spring Boot es relativamente económica, pero el manejo de tareas de procesamiento intensivo como el renderizado de video puede escalar rápidamente si no se optimiza.

El LLM para el análisis del guion es un costo menor, pero es crítico para la calidad de la selección de clips. La estimación de 5M tokens es generosa para un MVP, incluyendo desarrollo y pruebas.

Estrategias de Optimización FinOps

1. Optimización de APIs Externas:

* Caché Inteligente: Implementar un sistema de caché para las búsquedas de stock de video y resultados de análisis LLM. Si un guion o conjunto de palabras clave se repite, o si se buscan temas populares, se pueden reutilizar los resultados y clips ya obtenidos, reduciendo las llamadas a la API y sus costos asociados. * Monitoreo de Uso y Costos: Establecer alertas de presupuesto y monitorear de cerca el consumo de cada API externa. Esto permitirá identificar picos de uso inesperados o patrones de gasto ineficientes. * Selección de Proveedor: Evaluar continuamente proveedores de APIs para TTS, stock de video y renderizado. A medida que el volumen crece, se pueden encontrar proveedores con mejores tarifas por volumen o modelos de precios más adecuados. * Políticas de Uso de la Freemium: Definir claramente los límites del plan gratuito para evitar abusos y asegurar que los usuarios de pago aporten suficiente ingreso para cubrir sus costos de API.

1. Optimización de Infraestructura Cloud:

* Almacenamiento de S3: Configurar políticas de ciclo de vida en los buckets de S3 para mover videos generados a clases de almacenamiento más baratas (S3 Infrequent Access, S3 Glacier) después de un período de tiempo, o eliminarlos si son videos de prueba o temporales. * Renderizado de Video: Si el renderizado se realiza con FFMPEG auto-hospedado, considerar el uso de instancias spot para las cargas de trabajo de renderizado, que son significativamente más baratas que las instancias on-demand. Otra opción es evaluar soluciones serverless (ej. AWS Lambda con FFMPEG) para cargas de trabajo esporádicas, pagando solo por el tiempo de cómputo real. * Base de Datos: Monitorear el uso de la base de datos y escalar o reducir la instancia de RDS según sea necesario. Para un MVP, una db.t3.micro es a menudo suficiente. * CDN: Monitorear el tráfico del CDN. Si el volumen de descargas es bajo, se podría considerar una configuración más básica o incluso servir directamente desde S3 para los primeros meses, aunque esto impactaría la experiencia del usuario.

1. Monitoreo y Reportes:

* Implementar dashboards de FinOps que muestren el desglose de costos en tiempo real, la rentabilidad por cliente o por proyecto, y el ROI de las características. Esto permitirá tomar decisiones informadas sobre dónde invertir o reducir gastos.

Conclusión

StoryReel AI tiene un modelo de negocio con un potencial de margen saludable si se gestionan eficazmente los costos de las APIs externas, que son el principal motor de gasto. La implementación de prácticas FinOps desde el principio será crucial para escalar de manera rentable y asegurar la sostenibilidad a largo plazo.