# 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…

- Página: <https://www.datafirefly.com/es/documentation/df-ai-product-photography/>
- Idioma: es
- Actualizado el: 2026-07-01
- Otros idiomas: [fr](https://www.datafirefly.com/documentation/df-ai-product-photography/index.md), [en](https://www.datafirefly.com/en/documentation/df-ai-product-photography/index.md), [de](https://www.datafirefly.com/de/documentation/df-ai-product-photography/index.md), [it](https://www.datafirefly.com/it/documentation/df-ai-product-photography/index.md), [pl](https://www.datafirefly.com/pl/documentation/df-ai-product-photography/index.md), [nl](https://www.datafirefly.com/nl/documentation/df-ai-product-photography/index.md), [pt](https://www.datafirefly.com/pt/documentation/df-ai-product-photography/index.md)
- Índice: <https://www.datafirefly.com/es/documentation/llms.txt>

## 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

**Importante:** los sitios en local (localhost, .test, .local) no funcionarán: el proveedor IA no puede alcanzar la URL de tu imagen fuente. Usa un entorno de staging accesible públicamente o un túnel (ngrok, Cloudflare Tunnel).

## 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](https://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](https://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)

**Consejo:** redacta tus prompts en inglés y describe el entorno, la iluminación y el estilo fotográfico. El plugin añade automáticamente una salvaguarda para preservar el producto y evitar texto y marcas de agua.

### 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.