Capability · Manequim invisível

API de manequim invisível para fotos de produtos em manequim invisível

Em uma frase

A API de manequim invisível da Photta recebe a foto de uma roupa no manequim e retorna a imagem em manequim invisível com o interior da peça reconstruído. Escolha o estilo 3d ou flat_lay, envie via POST, faça polling a cada 3 segundos e baixe quando estiver concluído.

  • Tempo típico: 1.5–4 min
  • Credits: 4 credits em 2K · 5 credits em 4K
  • Processamento: assíncrono, polling
  • Limites: 600 requisições/min
  • Autenticação: Chave Bearer

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

POST/api/v1/ghost-mannequin
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')
A garment shown without its mannequin by the ghost mannequin API
Exemplo de saída

Visão geral

Visão geral

Endpoint
POST /api/v1/ghost-mannequin
Autenticação
API key Bearer
Processamento
Assíncrono — faça polling no endpoint de status
Tempo típico
1.5–4 min
Credits
4 credits em 2K · 5 credits em 4K
Proporções de tela
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Limites de entrada
Até 10 MB por imagem; JPEG, PNG, WebP
Idempotente
Não

Requisição e resposta

Requisição

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')

202 Accepted / Concluído

{
  "data": {
    "id": "gm_d4e5f6",
    "status": "processing",
    "style": "3d",
    "angle": "side",
    "background_color": "white",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "credits_used": 4,
    "created_at": "2026-04-10T16:00:00Z"
  },
  "request_id": "req_gm001"
}

Parâmetros da requisição

product_image

Tipo: stringObrigatório

URL or base64 data URI of the garment photo (front or back, on a mannequin or flat).

back_image

Tipo: string

URL or base64 data URI of the opposite side — helps the AI reconstruct the interior of the garment for a more realistic 3D effect.

image_side

Tipo: string

Which side product_image represents.

= front

Valores: frontback
angle

Tipo: string

Camera angle for the output. "side" is worth calling out: the side view is reconstructed from the front photo (plus the back photo when provided), giving you a third catalog view without a third photoshoot — and it works well even on textured garments (crochet, lace, embroidery).

= straight

Valores: straightbackside
style

Tipo: string

Output style: "3d" (ghost mannequin with 3D body shape) or "flat_lay" (garment laid flat, mannequin removed).

= 3d

Valores: 3dflat_lay
background_color

Tipo: string

Background color.

= white

Valores: whitegraybeigeblack
resolution

Tipo: string

Output resolution. "2K" costs 4 credits per image; "4K" costs 5 credits per image. 4K is produced natively in a single generation — pick it upfront; the resolution cannot be changed after creation. Note: 4K cannot be combined with aspect_ratio 1:1 — that combination returns 400.

= 2K

Valores: 2K4K
aspect_ratio

Tipo: string

Output aspect ratio. Note: 1:1 is not available at 4K resolution — 1:1 combined with 4K returns 400.

= 3:4

Valores: 3:41:14:39:1616:9
user_instruction

Tipo: string

Optional free-form note, max 400 characters (anything longer is silently truncated). A guarded steer for ambiguous rendering choices — e.g. "closed front", "cream interior lining", "buttoned up" — it never overrides the source garment, brand label, or structural reconstruction, and it is explicitly NOT a determinism/seed control.

brand_label_id

Tipo: string

Brand label UUID returned by the Brand Labels API. Applied to the generated garment when present. API v1 request fields use snake_case; use brand_label_id.

Erros

400invalid_request_error
The request is malformed or contains invalid parameters.
401authentication_error
The API key is missing, invalid, or expired.
402insufficient_credits_error
Your account does not have enough credits.
404not_found_error
The requested resource does not exist.
409conflict_error
The request conflicts with current state — e.g. your concurrent-batch cap is reached.
429rate_limit_error
Too many requests. Slow down and retry.Retry-After: 30
500api_error
An internal server error occurred. Retry later.

Limites

  • 600 requisições por minuto por API key (Janela fixa; o limite é o mesmo em todos os planos)
  • Um 429 retorna Retry-After: 30 segundos
  • Até 10 MB por imagem
  • Formatos: JPEG, PNG, WebP
  • Batches concorrentes por plano: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Apenas polling — a API não envia webhooks.

Entra uma foto, sai uma foto com manequim invisível

Faça o upload da origem, escolha um estilo, envie, faça polling, baixe.

  1. Passo 1

    Gerar uma chave de API

    O ghost mannequin usa as mesmas credenciais de qualquer outra funcionalidade da Photta — uma chave, um saldo de credits.

  2. Passo 2

    Fazer o upload da foto de origem

    Passe uma URL pública ou uma data URI em base64 em `product_image`; adicione `back_image` quando tiver uma visão traseira. JPEG, PNG e WebP de até 10 MB por imagem.

  3. Passo 3

    Enviar o job de ghost mannequin via POST

    Faça um POST para `/api/v1/ghost-mannequin` com `product_image`, `style` (`3d` ou `flat_lay`) e os parâmetros opcionais `angle`, `background_color`, `resolution`. Polling é o único sinal de conclusão — a API não envia webhooks.

  4. Passo 4

    Fazer polling até que o job seja concluído

    Faça GET em `/api/v1/ghost-mannequin/:id` a cada 3 segundos até que `data.status` seja `completed` ou `failed`; o tempo típico de conclusão é de 1.5 a 4 minutos.

  5. Passo 5

    Baixar e persistir

    A saída é um PNG com o manequim removido e o interior da peça reconstruído. Ideal para fotos ghost de PDP, galerias de produtos com aspecto 3D e inserções flat-lay.

Perguntas que desenvolvedores fazem antes de colocar o ghost mannequin em produção

O que é fotografia ghost mannequin?

Um tratamento para PDP no qual a peça de roupa parece flutuar em um corpo invisível, exibindo formato e construção interna simultaneamente. Historicamente, é montada a partir de várias fotos de estúdio; a API da Photta produz isso em uma única chamada a partir de uma foto no manequim.

Quanto custa o ghost mannequin?

4 credits em 2K, 5 credits em 4K — um credit mais barato em cada nível em comparação com o try-on. Jobs com falha são reembolsados automaticamente.

Qual é a diferença entre os estilos 3D e flat-lay?

O estilo `3d` mantém o formato tridimensional do corpo do manequim — a peça retém volume, ombros e mangas se apresentam de forma natural, e o interior é reconstruído. O `flat_lay` achata a peça em uma disposição 2D limpa, ideal para coleções-cápsula ou listagens em marketplaces que exigem um formato frontal padronizado.

Posso processar várias fotos em lote?

Sim. Faça um POST para `/api/v1/ghost-mannequin/batch` com um array de imagens de origem. A resposta retorna um ID de lote mais IDs de geração individuais por item. Faça polling em `/api/v1/ghost-mannequin/batch/:id` para obter o status agregado ou em cada item individualmente.

Ele preserva costuras e etiquetas internas?

Sim — o modelo reconstrói o interior da peça (parte interna da gola, interior dos punhos, forro da cintura) em vez de alucinar uma superfície genérica. Etiquetas e tags impressas visíveis na foto original são mantidas quando possível.

Como faço polling para obter o resultado?

Faça GET em `/api/v1/ghost-mannequin/:id` a cada 3 segundos. Jobs em lote consultam um endpoint pai que retorna um status agregado mais o detalhamento por item.

Funcionalidades relacionadas

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

Experimente a API em cinco minutos

Gere uma chave de API do Photta, cole o snippet de cURL acima e você terá sua primeira imagem com modelo antes que o café termine de passar.

  • 1.5–4 min
  • 4 credits em 2K · 5 credits em 4K
  • assíncrono, polling
  • 600 requisições/min
  • Chave Bearer