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

- Página: <https://www.datafirefly.com/pt/documentation/df-ai-product-photography/>
- Idioma: pt
- Atualizado em: 2026-09-02
- Outros 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), [es](https://www.datafirefly.com/es/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)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

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

**Importante:** os sites locais (localhost, .test, .local) não funcionam, porque o fornecedor de IA não consegue alcançar o URL da sua imagem de origem. Use um ambiente de staging acessível publicamente ou um túnel (ngrok, Cloudflare Tunnel).

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

**Dica:** redija os prompts em inglês e descreva o ambiente, a luz e o estilo fotográfico. O plugin acrescenta automaticamente uma salvaguarda para preservar o produto e evitar texto e marcas de água.

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