Cómo añadir filtros de fotos para adultos a tu app

Añadir un filtro de fotos para adultos a un producto parece un problema de imagen y acaba siendo un problema de fontanería. El trabajo del modelo se compra en una sola llamada. Lo que consume el sprint es todo lo que hay alrededor: subidas que expiran, trabajos que terminan cuando ya nadie escucha, reintentos que te facturan dos veces en silencio y una cola de soporte preguntando dónde ha ido a parar un resultado. Esta guía recorre la integración de principio a fin y señala los puntos donde los equipos pierden tiempo de forma sistemática.

En qué consiste realmente la integración

Una API de transformación de imágenes es asíncrona por naturaleza. La generación tarda lo suficiente como para que mantener abierta una conexión HTTP sea mala idea: las redes móviles se caen, los balanceadores cortan conexiones inactivas y tus propios tiempos de espera empiezan a jugar en tu contra. Por eso la forma es siempre la misma: envías el trabajo, recibes un identificador y recoges el resultado más tarde.

1. Envía la foto y el preset que quieres, y recibe un identificador de trabajo.
2. Sigue el trabajo, mediante sondeo o suscribiéndote a eventos.
3. Descarga la imagen terminada cuando el trabajo informe de éxito.
4. Gestiona los caminos de error y reintento, que es donde está el trabajo de verdad.

Paso uno: enviar el trabajo

El envío es una petición multipart que lleva la imagen, el identificador del preset y una confirmación de que tienes los derechos y el consentimiento para procesar la foto. Manda con ella una clave de idempotencia. Esa única cabecera marca la diferencia entre una integración limpia y un problema de soporte, y añadirla no cuesta nada.

curl -X POST https://api.example/api/v1/jobs \
  -H "X-API-Key: $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F image=@photo.jpg \
  -F feature=bikini \
  -F consent=confirmed

La respuesta trae el identificador del trabajo y su estado inicial. Guarda ese identificador junto al registro de tu usuario o sesión de inmediato, antes de hacer cualquier otra cosa. Si tu proceso muere al segundo siguiente, esa fila es lo único que te permite volver a encontrar el trabajo.

Paso dos: seguir el progreso

Hay dos formas de seguir un trabajo, y las integraciones maduras usan ambas. Una conexión WebSocket te da cambios de estado y progreso en vivo, que es justo lo que quieres para mover una barra de progreso en la interfaz. El sondeo del endpoint del trabajo es el respaldo que hace el sistema correcto y no solo agradable: los sockets se caen, los teléfonos se duermen y una consulta cada pocos segundos apenas cuesta nada.

Trata el WebSocket como una optimización y el sondeo como la fuente de verdad. Los equipos que invierten esto acaban con trabajos que terminaron perfectamente en el servidor y aparecen bloqueados para siempre en el cliente, porque el único evento que importaba llegó mientras el socket se reconectaba.

Paso tres: recoger el resultado

Cuando el trabajo informa de éxito, incluye una lista de salidas. Cada salida se descarga con la misma clave de API que creó el trabajo, así que los resultados nunca son públicamente direccionables ni adivinables a partir de una URL. Descarga la imagen a tu propio almacenamiento en cuanto la recibas si tu producto necesita mostrarla después: una API de imágenes es un servicio de procesamiento, no una fototeca, y los resultados no se conservan indefinidamente.

Paso cuatro: errores, reintentos y la trampa de la doble facturación

El fallo interesante no es aquel en el que la API devuelve un error. Es el ambiguo: tu petición salió, la red se cortó y no tienes ni idea de si el trabajo llegó a crearse. Si lo reintentas sin más, has pagado dos veces y has producido dos resultados para una sola acción del usuario.

Eso es lo que resuelve la clave de idempotencia. Repite la petición con la misma clave y recibes el trabajo original en lugar de uno nuevo, por muchas veces que se dispare el reintento. Genera la clave cuando ocurre la acción del usuario, guárdala con el registro del trabajo y reutilízala en cada reintento de esa misma acción; no una nueva por intento, porque eso anula todo el mecanismo.

Dónde suelen atascarse las integraciones

• Validar las subidas solo en el cliente. Comprueba el archivo en el servidor por su contenido, no por la extensión, antes de gastar una llamada a la API.
• Construir todo el flujo de forma síncrona y descubrir después que los clientes móviles pierden la conexión mucho antes de que termine la generación.
• Tratar el WebSocket como único canal de progreso, sin sondeo de respaldo.
• No guardar nada localmente, de modo que un reinicio pierde la correspondencia entre tus usuarios y los trabajos en curso.
• Olvidar que los resultados son transitorios y esperar que la API funcione como almacenamiento permanente.

Un orden de trabajo sensato

Pasa una foto por todo el recorrido con curl antes de escribir una línea de código de aplicación: enviar, sondear, descargar. Después cablea esas mismas cuatro llamadas en tu backend con persistencia. Añade el WebSocket al final, únicamente como mejora de la barra de progreso sobre un sistema que ya funciona sin él. En ese orden la integración es un día de trabajo; en el orden inverso son dos semanas de depuración.

Preguntas frecuentes