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
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')const res = await fetch("https://api.photta.app/api/v1/ghost-mannequin", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"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"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/ghost-mannequin",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"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"
},
)
data = res.json()["data"] # data["id"], data["status"]
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')const res = await fetch("https://api.photta.app/api/v1/ghost-mannequin", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"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"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/ghost-mannequin",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"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"
},
)
data = res.json()["data"] # data["id"], data["status"]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"
}{
"data": {
"id": "gm_d4e5f6",
"status": "completed",
"style": "3d",
"angle": "side",
"background_color": "white",
"resolution": "2K",
"aspect_ratio": "3:4",
"output_url": "https://cdn.photta.app/generated/gm_d4e5f6.jpg",
"thumbnail_url": "https://cdn.photta.app/generated/gm_d4e5f6-thumb.jpg",
"credits_used": 4,
"created_at": "2026-04-10T16:00:00Z",
"completed_at": "2026-04-10T16:00:48Z",
"duration_ms": 48000
},
"request_id": "req_gm002"
}Parâmetros da requisição
product_imageTipo: stringObrigatório
URL or base64 data URI of the garment photo (front or back, on a mannequin or flat).
back_imageTipo: 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_sideTipo: string
Which side product_image represents.
= front
Valores:frontbackangleTipo: 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:straightbacksidestyleTipo: string
Output style: "3d" (ghost mannequin with 3D body shape) or "flat_lay" (garment laid flat, mannequin removed).
= 3d
Valores:3dflat_laybackground_colorTipo: string
Background color.
= white
Valores:whitegraybeigeblackresolutionTipo: 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:2K4Kaspect_ratioTipo: 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:9user_instructionTipo: 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_idTipo: 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
- 400
invalid_request_error - The request is malformed or contains invalid parameters.
- 401
authentication_error - The API key is missing, invalid, or expired.
- 402
insufficient_credits_error - Your account does not have enough credits.
- 404
not_found_error - The requested resource does not exist.
- 409
conflict_error - The request conflicts with current state — e.g. your concurrent-batch cap is reached.
- 429
rate_limit_error - Too many requests. Slow down and retry.Retry-After: 30
- 500
api_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.
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.
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.
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.
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.
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.
O mesmo endpoint em Node.js, Python e cURL
Node.js
API de manequim invisível em Node.js
Chame aPI de manequim invisível da Photta a partir de um backend em Node.js com fetch nativo. Nenhum SDK é necessário: armazene sua chave, envie o job e faça polling pelo resultado.
LerPython
API de manequim invisível em Python
Chame aPI de manequim invisível do Photta em Python com a biblioteca requests. Wrapper de trinta linhas, compatível com async via httpx, funciona em Django, FastAPI e Celery.
LercURL
API de manequim invisível com cURL
Chame a aPI de manequim invisível da Photta diretamente do shell com cURL. Envie, faça polling, baixe — todos os snippets funcionam com o jq para pipelines em script.
Ler
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
Recursos
API de try-on virtual para roupas
API REST que veste roupas em manequins de IA. Assíncrona, geração em 1.5–4 minutos, 5 credits em 2K, 6 em 4K. Exemplos em cURL, Node.js e Python.
Ver o endpointRecursos
API de try-on de joias para colares, anéis, pulseiras e brincos
Insira colares, anéis, pulseiras e brincos em modelos de IA via REST. 5 credits em 2K, manequins em close-up integrados, renderização sensível a reflexos direto da documentação da Photta.
Ver o endpointConstruir
Automatize a extração de ghost mannequin para o seu catálogo
Receita de automação noturna de catálogo: busque as atualizações de produtos de ontem, envie em lote para a API de ghost mannequin da Photta, faça o polling do lote pai e persista no seu banco de dados.
Ver o endpointComparar
Photta vs Pixazo — pipeline próprio ou agregador de modelos
Comparativo Photta vs Pixazo: pipeline proprietário de moda vs agregador multi-modelo. Endpoints, latência, plano gratuito e trade-offs. Dados obtidos em 2026-04-19.
Ver o endpointInício rápido
Primeira imagem no Photta em menos de cinco minutos.
Cadastre-se, gere uma chave de API, execute sua primeira chamada cURL, faça polling até a conclusão, persista o resultado. Cinco etapas, documentadas de ponta a ponta.
Ver o endpointReferência
Erros da Photta API
A lista completa de tipos de erro da Photta API com seus status codes, o formato do corpo de erro e quais falhas valem a pena tentar novamente.
Ver o endpointReferência
Rate limits da API Photta
O rate limit da API Photta, sua janela, o header Retry-After, o intervalo de polling e os limites de simultaneidade por plano, tudo extraído da documentação da API.
Ver o endpoint
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