AI Product Photography Studio: guia completo

Apresentação

O AI Product Photography Studio transforma uma fotografia de produto sobre fundo branco em cenários profissionais gerados por IA (Flux Kontext Pro através do fal.ai ou do Replicate). O produto mantém-se rigorosamente igual de um cenário para o outro: só o ambiente muda. O plugin integra-se diretamente na ficha de produto do WooCommerce através de uma metabox dedicada, e as gerações correm em segundo plano graças ao Action Scheduler.

Requisitos

• WordPress 6.4 ou superior
• WooCommerce 8.0 ou superior (Action Scheduler incluído)
• PHP 8.1 ou superior
• Um site acessível em HTTPS: os fornecedores de IA têm de conseguir descarregar as suas imagens de origem através de um URL público
• Uma conta fal.ai ou Replicate com uma chave de API ativa

Instalação

1. Descarregue o ficheiro df-ai-product-photography.zip a partir da sua conta DataFirefly.
2. No WordPress, vá a Plugins → Adicionar → Carregar plugin.
3. Selecione o ZIP, clique em Instalar agora e depois em Ativar.
4. Aparece um novo submenu WooCommerce → AI Photo Studio: é a página de definições do plugin.

Na ativação, o plugin verifica que o PHP 8.1+ e o WooCommerce estão presentes. Se uma das condições não estiver cumprida, a ativação é recusada com uma mensagem explícita.

Obter uma chave de API

Opção A: fal.ai (recomendado em produção)

1. Crie uma conta em fal.ai.
2. Abra o dashboard e depois a secção Keys.
3. Gere uma nova chave e copie-a (formato xxxxxxxx-xxxx-...:yyyyyyyy).
4. Acrescente crédito à sua conta (faturação ao uso, cerca de 0,04 € por imagem).

Opção B: Replicate

1. Crie uma conta em replicate.com.
2. Vá a Account → API tokens.
3. Gere um token (formato r8_...) e copie-o.
4. Indique um meio de pagamento (cerca de 0,06 € por imagem).

Configuração

Vá a WooCommerce → AI Photo Studio. A página de definições tem quatro separadores.

Separador Fornecedor de IA

• Escolha do fornecedor: selecione o fal.ai ou o Replicate através dos cartões de opção. Ambos usam o mesmo modelo Flux Kontext Pro.
• Chave de API fal.ai / Token de API Replicate: cole a chave correspondente. Só é necessária a chave do fornecedor selecionado.
• Botão Testar: verifica que a chave está mesmo preenchida para o fornecedor escolhido.

Separador Parâmetros de geração

• Proporção da imagem: Igual à origem (predefinido), 1:1, 4:3, 3:4, 16:9, 9:16, 3:2 ou 2:3.
• Formato de saída: JPEG (predefinido) ou PNG.
• Tolerância de moderação: de 1 (muito estrita) a 6 (muito permissiva). O valor 2 é recomendado para o comércio eletrónico.
• Guidance: força de aderência ao prompt, de 1 a 10 (apenas no fal.ai). 3.5 por predefinição.
• Galeria automática: se estiver assinalado, cada imagem gerada é acrescentada de imediato à galeria do produto sem intervenção manual.

Separador Cenários personalizados

Além dos 12 cenários integrados, pode declarar os seus próprios cenários em formato JSON:

[
  {
    "key": "loft_industrial",
    "label": "Loft industrial",
    "category": "lifestyle",
    "icon": "🏭",
    "description": "Cenário cru de metal e betão",
    "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 em minúsculas e sem espaços (obrigatório)
• label: nome apresentado no seletor
• category: lifestyle, packshot, context ou seasonal
• prompt: instrução em inglês, idealmente a começar por «Place this product…» (obrigatório)

Separador Avançado

• Nível de registo: Desativado, Apenas erros (predefinido) ou Verbose. Os registos podem ser consultados em WooCommerce → Estado → Registos, origem df-ai-product-photography.
• Um bloco de informações técnicas mostra as versões do PHP, do WordPress e do WooCommerce e a presença do Action Scheduler.

Gerar cenários

Abra qualquer produto em Produtos → Todos os produtos. A metabox 🎨 AI Product Photography Studio aparece por baixo do editor. O fluxo decorre em três etapas:

Etapa 1: fotografia de origem

Escolha a imagem de partida, através de Escolher da biblioteca de multimédia ou de Usar a imagem principal, que retoma a imagem de destaque do produto. Uma fotografia nítida sobre fundo branco ou neutro dá os melhores resultados, e um smartphone recente chega.

Etapa 2: seleção dos cenários

Assinale os cenários pretendidos nos cartões, organizados por categoria (Lifestyle, Packshot, Contexto de utilização, Sazonal). As ligações rápidas + Todos Lifestyle, + Todos Packshot, Selecionar tudo e Limpar aceleram a seleção. Um lote está limitado a um máximo de 20 cenários.

Etapa 3: lançamento

Acrescente, se quiser, instruções adicionais (por exemplo «iluminação quente, cores de outono, estilo de revista») que serão aplicadas a todos os cenários do lote, e clique em ✨ Gerar os cenários.

A coluna da direita 🖼️ Gerações mostra o estado de cada trabalho em tempo real: Em fila → Envio → Geração → Terminado ou Falhou. O estado é atualizado automaticamente a cada 3,5 segundos. Conte geralmente com 10 a 30 segundos por imagem.

Usar as imagens geradas

Cada imagem terminada propõe três ações:

• + Galeria: acrescenta a imagem à galeria do produto WooCommerce (sem substituir as imagens existentes).
• Ver: abre a imagem em resolução total num novo separador.
• ×: retira a entrada da lista (a imagem permanece na biblioteca de multimédia).

Todas as imagens geradas são importadas para a biblioteca de multimédia do WordPress com metadados de rastreabilidade: _df_aipp_generated, _df_aipp_scene (nome do cenário) e _df_aipp_origin_product (produto de origem). Pode assim voltar a encontrá-las e reutilizá-las livremente.

Funcionamento técnico

As gerações são assíncronas: ao clicar em Gerar, o plugin cria um trabalho por cenário e agenda-o através do Action Scheduler (hook df_aipp_submit_job). Cada trabalho submete o pedido ao fornecedor, obtém um identificador, e depois um segundo hook (df_aipp_poll_job) consulta o estado a cada 5 segundos, até 60 tentativas (cerca de 5 minutos). Em caso de erro de rede transitório, o trabalho é repetido até 3 vezes antes de ser marcado como falhado.

Pode observar e relançar as ações em WooCommerce → Estado → Ações agendadas, grupo df-ai-product-photography.

Resolução de problemas

O botão Gerar está desativado

O fornecedor selecionado não tem chave de API preenchida. Vá a WooCommerce → AI Photo Studio → Fornecedor de IA e cole a sua chave.

Os trabalhos ficam bloqueados em «Em fila»

O Action Scheduler não está a correr. Verifique que o WP-Cron funciona (visite o site no front-end, ou configure um verdadeiro cron de servidor a apontar para o wp-cron.php). Consulte WooCommerce → Estado → Ações agendadas para ver as ações pendentes.

Erro «Imagem de origem não encontrada» ou falha imediata

O fornecedor não consegue descarregar a sua imagem. Causas frequentes: site local não acessível publicamente, proteção por htpasswd, proteção contra hotlink ao nível do servidor, ou CDN a bloquear os pedidos externos. Teste o URL da imagem numa janela de navegação privada.

Erro 401 ou 403 devolvido pelo fornecedor

Chave de API inválida, expirada, ou conta sem crédito. Regenere a chave no dashboard do fornecedor e verifique o seu saldo.

A geração conclui mas a imagem é recusada (safety)

O modelo considerou o conteúdo sensível. Aumente a Tolerância de moderação nas definições (experimente 3 ou 4), ou reformule o prompt do seu cenário personalizado.

Onde encontrar os registos detalhados?

Coloque o Nível de registo em Verbose no separador Avançado, volte a lançar uma geração, e consulte WooCommerce → Estado → Registos selecionando a origem df-ai-product-photography.

Desinstalação

A desativação, por si só, não elimina nada. A remoção do plugin aciona o uninstall.php, que apaga as definições globais, as metas de trabalhos nos produtos e as ações agendadas que restarem. As imagens geradas já presentes na biblioteca de multimédia são conservadas.

FAQ

Posso usar os dois fornecedores em paralelo?

O fornecedor ativo é global (apenas um de cada vez), mas pode alternar a qualquer momento nas definições: as novas gerações passam a usar o fornecedor recém-selecionado.

As imagens geradas estão livres de direitos?

Segundo as condições do fal.ai e do Replicate, os resultados gerados com a sua conta pertencem-lhe e podem ser usados comercialmente. Verifique os termos e condições do seu fornecedor para o seu caso de utilização.

O plugin funciona com produtos variáveis?

Sim. A metabox está disponível em todos os tipos de produto do WooCommerce. As imagens são associadas à galeria do produto principal.