Build · Automação de Ghost Mannequin

Automatize a extração de ghost mannequin para o seu catálogo

Em uma frase

Busque o delta do catálogo desde a última execução, faça um POST de um array product_images (cada item contendo uma URL de imagem e uma back_image opcional) com um style para /api/v1/ghost-mannequin/batch, faça polling do ID do lote a cada 3 segundos até que cada item esteja como completed ou failed e, em seguida, atualize cada linha de produto com sua output_url. Lotes concorrentes são limitados por plano.

Obter uma chave de APIVeja a API de ghost mannequin
  • Credits: 4 credits em 2K · 5 credits em 4K
  • Tempo típico: 1.5–4 min
  • Processamento: assíncrono, polling

Todos os números nesta página vêm de a documentação da API da Photta · verificado

Remova o manequim de todas as fotos de PDP sem envolver um designer. O endpoint de ghost mannequin da Photta processa lotes naturalmente — um cron noturno transforma um feed de 50K-SKU em um catálogo com manequim invisível em horas, não semanas.

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/ghost-mannequin \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
  "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
  "image_side": "front",
  "angle": "side",
  "style": "3d",
  "background_color": "white",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "closed front, cream interior lining",
  "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

Como funciona

Execução noturna em todo o catálogo

Cinco peças necessárias para uma automação executada sem supervisão.

  1. Passo 1

    Mapeie seu catálogo

    Saiba quais linhas de produtos precisam de uma imagem de ghost mannequin, quais já possuem uma e quais têm categorias restritas. Armazene um timestamp last_photographed_at para que o job noturno processe apenas o delta.

  2. Passo 2

    Escolha 3D ou flat-lay por categoria

    `3d` para peças que precisam de volume — agasalhos, jeans, peças de alfaiataria. `flat_lay` para acessórios e malhas que fotografam melhor dobrados sobre uma superfície plana. Armazene o estilo por categoria de produto para que o criador de lotes selecione o correto sem ajustes manuais.

  3. Passo 3

    Envie o delta em lote

    Faça um POST em /api/v1/ghost-mannequin/batch com um array product_images — cada item carrega image, back_image opcional e image_side — além de um style, background_color e resolução para todo o lote. Mantenha seu próprio mapeamento da posição do array para o ID do produto; a resposta retorna um ID de geração por item na mesma ordem.

  4. Passo 4

    Faça polling do lote pai

    O endpoint de lote retorna contadores agregados (total, processing, completed, failed). Faça polling a cada 3 segundos até que completed + failed seja igual a total. A Photta processa itens em paralelo dentro do lote, então você não precisa fazer polling de gerações individuais.

  5. Passo 5

    Persista no seu banco de dados

    Itere sobre status.data.items em ordem — o lote preserva a ordem do seu array — e atualize cada linha de produto com sua output_url. Registre as falhas em log — elas quase sempre indicam uma foto de origem com problemas no seu feed, que você pode corrigir e reenviar na próxima execução.

Três passos em Python

Extração de delta, envio em lote, polling pai — o mínimo viável de automação de catálogo.

from datetime import datetime, timedelta

yesterday = datetime.utcnow() - timedelta(days=1)
rows = db.execute(
    "SELECT id, source_image_url FROM products WHERE updated_at > %s",
    (yesterday,),
).fetchall()
import os, requests

res = requests.post(
    "https://api.photta.app/api/v1/ghost-mannequin/batch",
    headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
    json={
      "product_images": [
        {
          "image": "https://cdn.yourstore.com/products/jacket-front.jpg",
          "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
          "image_side": "front"
        },
        {
          "image": "https://cdn.yourstore.com/products/shirt-front.jpg",
          "image_side": "front"
        },
        {
          "image": "https://cdn.yourstore.com/products/trousers-front.jpg",
          "image_side": "front"
        }
      ],
      "style": "3d",
      "background_color": "white",
      "resolution": "2K",
      "aspect_ratio": "3:4",
      "user_instruction": "closed front, buttoned up",
      "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
    },
)
data = res.json()["data"]  # data["id"], data["status"]
import os, time, requests

BASE = "https://api.photta.app/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"}
# data["items"] comes back in the order of the product_images you submitted.
batch_id = data["batch_id"]
for _ in range(240):  # 240 × 3s = 12 minutes
    status = requests.get(f"{BASE}/ghost-mannequin/batch/{batch_id}", headers=HEADERS).json()["data"]
    if status["completed"] + status["failed"] == status["total"]:
        break
    time.sleep(3)

for row, item in zip(rows, status["items"]):
    if item["status"] == "completed":
        db.execute(
            "UPDATE products SET ghost_image_url = %s WHERE id = %s",
            (item["output_url"], row.id),
        )

Dúvidas frequentes de desenvolvedores

Executando ghost mannequin em escala de catálogo

Qual pode ser o tamanho de um único lote?

O endpoint de lote aceita até algumas centenas de itens por chamada, de acordo com a documentação. Para uma execução noturna de 50K-SKU, divida o delta em lotes de 100–200 e envie-os sequencialmente para permanecer confortavelmente abaixo do rate limit do plano.

Um lote pode mesclar 3D e flat-lay?

Sim — style é um campo por item, então um único lote pode conter ambos. Na prática, a maioria das equipes divide por categoria de qualquer forma, pois a lógica de persistência downstream fica mais simples quando todas as linhas de um lote vão para a mesma coluna do banco de dados.

O que acontece com os itens com falha?

Itens com falha em um lote têm seus credits reembolsados automaticamente e trazem um error_code + error_message no payload final do item. Registre as falhas em log e tente novamente na noite seguinte, após sua equipe ter a chance de corrigir a foto de origem ou marcar a linha como entrada permanentemente inválida.

Como mapeio os resultados de volta para os IDs dos meus produtos?

Mantenha seu próprio mapeamento da posição do array para o ID do produto ao enviar: a resposta do lote retorna um ID de geração por item na mesma ordem de product_images, e o status do lote também lista os itens nessa ordem.

Posso agendar isso como um cron diário?

Sim — um cron diário simples que busca o delta das últimas 24 horas, divide em partes, envia os lotes e grava os resultados no seu banco de dados é um padrão estrutural para equipes que lidam com escala de catálogo. Mantenha o runner idempotente para que uma falha noturna possa ser reexecutada com segurança.

Páginas relacionadas

Referência

Todos os números nesta página vêm de a documentação da API da Photta · verificado

Implemente manequim invisível em escala de catálogo hoje à noite

Três funções Python, um cron, 50K fotos. Obtenha uma chave de API e aponte para o seu catálogo.

Obter uma chave de APILeia o quickstart