Imagens com IA
Remove o fundo de uma foto de produto ou a refaz como uma foto de estúdio limpa, devolvendo a imagem processada sem salvá-la.
O editor de imagens do painel oferece duas ações com inteligência artificial. Nas duas você envia o arquivo e a resposta é o próprio arquivo processado (não um JSON). Nenhuma delas grava nada no produto: depois de conferir o resultado, você envia a imagem pelo fluxo normal de upload e a adiciona à galeria.
Os dois pedidos são multipart/form-data com um único campo de arquivo chamado image, de até 20 MiB. Exigem manage_catalog.
Remover o fundo
/api/v1/admin/images/ai/removebgAdminRemover o fundo da imagem
Recorta o produto e devolve um PNG com fundo transparente. Demora alguns segundos; o servidor espera até 100 s. Útil para preparar fotos para marketplaces que exigem fundo liso.
Corpo da requisição
imagefileobrigatóriomultipart/form-data. Máximo 20 MiB.Padronizar como foto de estúdio
/api/v1/admin/images/ai/professionalizeAdminRefazer a foto como imagem de estúdio
A IA recria a foto no estilo de catálogo: o mesmo produto sobre fundo branco, centralizado e com aparência de estúdio. A saída é quadrada e o formato vem no Content-Type da resposta. Como é uma recriação, confira o resultado: detalhes pequenos do produto podem mudar.
Corpo da requisição
imagefileobrigatóriomultipart/form-data. Máximo 20 MiB.Exemplo de requisição
curl -X POST "$BASE_URL/api/v1/admin/images/ai/removebg" \
-H "Authorization: Bearer $TOKEN" \
-F "image=@foto-produto.jpg" \
-o produto-sem-fundo.pngResposta
O corpo é o arquivo binário da imagem, não JSON. Em removebg o Content-Type é image/png; em professionalize ele acompanha o formato gerado. A resposta leva Cache-Control: no-store.
Erros
| Status | Quando | Corpo de exemplo |
|---|---|---|
| 400 | Não é multipart/form-data, falta o campo image ou o arquivo passa de 20 MiB. | {"error":"invalid image","detail":"parse form: request Content-Type isn't multipart/form-data"} |
| 401 | Sem token ou token expirado. | {"error":"invalid or expired token"} |
| 403 | Sem manage_catalog. | {"error":"insufficient privileges","required":"manage_catalog"} |
| 502 | removebg: o recorte falhou ou devolveu imagem vazia. | {"error":"background removal failed","detail":"..."} |
| 502 | professionalize: a geração falhou. | {"error":"professionalize failed","detail":"..."} |
| 503 | professionalize indisponível: a geração de imagem não está configurada nesta plataforma. | {"error":"AI image edit not configured","detail":"..."} |
| 500 | professionalize gerou um resultado ilegível. | {"error":"decode result","detail":"..."} |