AI Product Photography Studio — Guía completa

Presentación

AI Product Photography Studio convierte una foto de producto sobre fondo blanco en escenas profesionales generadas por IA (Flux Kontext Pro vía fal.ai o Replicate). El producto permanece rigurosamente idéntico de una escena a otra: solo cambia el entorno. El plugin se integra directamente en la ficha de producto de WooCommerce mediante una meta box dedicada, y las generaciones se ejecutan en segundo plano gracias a Action Scheduler.

Requisitos

• WordPress 6.4 o superior
• WooCommerce 8.0 o superior (Action Scheduler incluido)
• PHP 8.1 o superior
• Un sitio accesible por HTTPS — los proveedores IA deben poder descargar tus imágenes fuente mediante una URL pública
• Una cuenta fal.ai o Replicate con una clave API activa

Instalación

1. Descarga el archivo df-ai-product-photography.zip desde tu cuenta DataFirefly.
2. En WordPress, ve a Plugins → Añadir nuevo → Subir plugin.
3. Selecciona el ZIP, haz clic en Instalar ahora y luego Activar.
4. Aparece un nuevo submenú WooCommerce → AI Photo Studio: es la página de ajustes del plugin.

Al activarse, el plugin comprueba que PHP 8.1+ y WooCommerce estén presentes. Si alguna condición no se cumple, la activación se rechaza con un mensaje claro.

Obtener una clave API

Opción A — fal.ai (recomendado en producción)

1. Crea una cuenta en fal.ai.
2. Abre el dashboard y luego la sección Keys.
3. Genera una nueva clave y cópiala (formato xxxxxxxx-xxxx-...:yyyyyyyy).
4. Añade crédito a tu cuenta (pago por uso, unos 0,04 € por imagen).

Opción B — Replicate

1. Crea una cuenta en replicate.com.
2. Ve a Account → API tokens.
3. Genera un token (formato r8_...) y cópialo.
4. Añade un método de pago (unos 0,06 € por imagen).

Configuración

Ve a WooCommerce → AI Photo Studio. La página de ajustes tiene cuatro pestañas.

Pestaña Proveedor IA

• Selección del proveedor: elige fal.ai o Replicate mediante las tarjetas radio. Ambos usan el mismo modelo Flux Kontext Pro.
• Clave API fal.ai / Token API Replicate: pega la clave correspondiente. Solo se requiere la clave del proveedor seleccionado.
• Botón Probar: verifica que la clave está presente para el proveedor elegido.

Pestaña Parámetros de generación

• Relación de imagen: Igual que la fuente (por defecto), 1:1, 4:3, 3:4, 16:9, 9:16, 3:2 o 2:3.
• Formato de salida: JPEG (por defecto) o PNG.
• Tolerancia de moderación: de 1 (muy estricto) a 6 (muy permisivo). Se recomienda 2 para e-commerce.
• Guidance: fuerza de adherencia al prompt, de 1 a 10 (solo fal.ai). 3,5 por defecto.
• Galería automática: si está marcado, cada imagen generada se añade inmediatamente a la galería del producto sin intervención manual.

Pestaña Escenas personalizadas

Además de las 12 escenas integradas, puedes declarar tus propias escenas en JSON:

[
  {
    "key": "loft_industrial",
    "label": "Loft industrial",
    "category": "lifestyle",
    "icon": "🏭",
    "description": "Decorado bruto metal y hormigón",
    "prompt": "Place this product in a modern industrial loft setting with exposed brick walls, concrete floor, large factory windows, dramatic natural light"
  }
]

• key: identificador único en minúsculas sin espacios (obligatorio)
• label: nombre mostrado en el selector
• category: lifestyle, packshot, context o seasonal
• prompt: instrucción en inglés, idealmente empezando por «Place this product…» (obligatorio)

Pestaña Avanzado

• Nivel de registro: Desactivado, Solo errores (por defecto) o Detallado. Los registros se consultan en WooCommerce → Estado → Registros, fuente df-ai-product-photography.
• Un bloque de información técnica muestra las versiones PHP / WordPress / WooCommerce y la presencia de Action Scheduler.

Generar escenas

Abre cualquier producto en Productos → Todos los productos. La meta box 🎨 AI Product Photography Studio aparece bajo el editor. El flujo de trabajo tiene tres pasos:

Paso 1 — Foto fuente

Elige la imagen de partida: bien mediante Elegir de la mediateca, bien mediante Usar la imagen principal que reutiliza la imagen destacada del producto. Una foto nítida sobre fondo blanco o neutro da los mejores resultados — un smartphone reciente basta.

Paso 2 — Selección de escenas

Marca las escenas deseadas entre las tarjetas, organizadas por categoría (Lifestyle, Packshot, Contexto de uso, Estacional). Los enlaces rápidos + Todas Lifestyle, + Todas Packshot, Seleccionar todo y Limpiar aceleran la selección. Un lote está limitado a 20 escenas.

Paso 3 — Lanzamiento

Añade opcionalmente instrucciones adicionales (ej. «iluminación cálida, colores otoñales, estilo revista») aplicadas a todas las escenas del lote, y haz clic en ✨ Generar escenas.

La columna derecha 🖼️ Generaciones muestra el estado de cada job en tiempo real: En cola → Enviando → Generando → Listo o Fallo. El estado se refresca automáticamente cada 3,5 segundos. Cuenta generalmente de 10 a 30 segundos por imagen.

Usar las imágenes generadas

Cada imagen terminada ofrece tres acciones:

• + Galería: añade la imagen a la galería del producto WooCommerce (sin sobrescribir las imágenes existentes).
• Ver: abre la imagen a resolución completa en una nueva pestaña.
• ×: retira la entrada de la lista (la imagen permanece en la mediateca).

Todas las imágenes generadas se importan a la biblioteca multimedia de WordPress con metadatos de trazabilidad: _df_aipp_generated, _df_aipp_scene (nombre de la escena) y _df_aipp_origin_product (producto de origen). Puedes encontrarlas y reutilizarlas libremente.

Funcionamiento técnico

Las generaciones son asíncronas: al hacer clic en Generar, el plugin crea un job por escena y lo planifica vía Action Scheduler (hook df_aipp_submit_job). Cada job envía la petición al proveedor, obtiene un identificador, y un segundo hook (df_aipp_poll_job) consulta el estado cada 5 segundos, hasta 60 intentos (~5 minutos). En caso de error de red transitorio, el job se reintenta hasta 3 veces antes de marcarse como fallido.

Puedes observar y relanzar las acciones en WooCommerce → Estado → Acciones programadas, grupo df-ai-product-photography.

Solución de problemas

El botón Generar está deshabilitado

El proveedor seleccionado no tiene clave API configurada. Ve a WooCommerce → AI Photo Studio → Proveedor IA y pega tu clave.

Los jobs se quedan bloqueados en «En cola»

Action Scheduler no se ejecuta. Verifica que WP-Cron funciona (visita el sitio por el front, o configura un cron real de servidor apuntando a wp-cron.php). Consulta WooCommerce → Estado → Acciones programadas para ver las acciones pendientes.

Error «Imagen de origen no encontrada» o fallo inmediato

El proveedor no puede descargar tu imagen. Causas frecuentes: sitio local no accesible públicamente, protección htpasswd, hotlink protection a nivel de servidor o un CDN bloqueando peticiones externas. Prueba la URL de la imagen en una ventana de navegación privada.

Error 401 / 403 devuelto por el proveedor

Clave API inválida, caducada o cuenta sin crédito. Regenera la clave en el dashboard del proveedor y verifica tu saldo.

La generación termina pero la imagen es rechazada (safety)

El modelo consideró el contenido sensible. Aumenta la Tolerancia de moderación en los ajustes (prueba 3 o 4), o reformula el prompt de tu escena personalizada.

¿Dónde están los registros detallados?

Pon el Nivel de registro en Detallado en la pestaña Avanzado, relanza una generación, y consulta WooCommerce → Estado → Registros seleccionando la fuente df-ai-product-photography.

Desinstalación

La desactivación sola no elimina nada. La eliminación del plugin ejecuta uninstall.php, que borra los ajustes globales, los metadatos de jobs en los productos y las acciones programadas restantes. Las imágenes generadas ya presentes en la mediateca se conservan.

FAQ

¿Puedo usar ambos proveedores en paralelo?

El proveedor activo es global (uno a la vez), pero puedes cambiar en cualquier momento en los ajustes: las nuevas generaciones usarán el proveedor recién seleccionado.

¿Las imágenes generadas están libres de derechos?

Según las condiciones de fal.ai y Replicate, las salidas generadas con tu cuenta te pertenecen y son utilizables comercialmente. Verifica los términos de tu proveedor para tu caso de uso.

¿Funciona el plugin con productos variables?

Sí. La meta box está disponible en todos los tipos de producto WooCommerce. Las imágenes se adjuntan a la galería del producto padre.