Uma API entediante de propósito
As melhores APIs de imagem são entediantes. Você dá a elas uma imagem, recebe um resultado e segue em frente com seu produto. A Remove BG foi projetada com esse padrão em mente.
curl 'https://api.codia.ai/v1/open/remove_bg' \
-H 'Authorization: Bearer {codia_api_key}' \
-H 'Content-Type: application/json' \
--data '{ "image_url": "https://example.com/product.jpg" }'{
"code": 0,
"message": "ok",
"data": {
"image_url": "https://processed-image-url.com/result.png"
}
}É isso. Um endpoint. Um campo obrigatório. Um formato de resposta. O restante deste post é sobre o que trocamos para manter a superfície tão pequena, e como a API se comporta dentro de um pipeline de imagem real.
O que "limpo" significa para um recorte
A versão preguiçosa de um pipeline de remoção de fundo retorna uma imagem com um canal alfa suave que parece ok no tamanho de miniatura e desmorona sob um fundo claro ou um layout de catálogo nítido. Remove BG mira no oposto: recortes que se sustentam quando um cliente dá zoom em uma página de produto.
Concretamente, a passada de qualidade de borda faz três coisas que importam:
- Alfa subpixel no contorno. A máscara é matted, não thresholded — cabelos finos na borda, fios de joalheria finos, renda e bordas de vidro mantêm bordas suaves em vez de serem cortados no pixel inteiro mais próximo.
- Descontaminação de cor no primeiro plano. Pixels perto da borda frequentemente carregam vazamento verde ou vermelho do fundo original. A API remove essa tonalidade para que o sujeito faça composição limpa em qualquer novo fundo sem halo.
- Sem borrão de sombra. Se o original tem uma sombra projetada em uma superfície branca, a sombra vai com o fundo. Se você quer manter sombras (algumas equipes de e-commerce querem), a auto-sombra do sujeito sobre si mesmo — o lado sombreado de baixo de um sapato, o lado escuro de uma caneca — permanece no lugar.
O teste prático: faça a composição do PNG retornado em um fundo #111. Se você vê uma franja brilhante, o recorte não está limpo. Remove BG deve passar neste teste em produtos, pessoas, animais, comida, móveis e veículos. Vai ter dificuldade com sujeitos em motion blur e em imagens onde o sujeito compartilha uma paleta de cores com um fundo complexo.
Orçamento de latência
O tempo de processamento anunciado é de cerca de 600 ms. Esse número é o tempo de inferência do modelo mais I/O leve; a latência ponta a ponta desde sua requisição até a URL retornada é mais próxima de 800 a 1200 ms dependendo do tamanho da imagem e da região. Para cargas de trabalho em lote, a API paraleliza bem — você pode enviar centenas de requisições concorrentemente de uma única chave antes que os limites de taxa entrem em ação, o que é tipicamente suficiente para fluxos interativos de upload de produto.
Se você está integrando em uma UI síncrona — um usuário arrasta uma imagem e quer ver o resultado imediatamente — 800 ms é uma boa sensação. Se você está ingerindo um catálogo de 50.000 SKUs durante a noite, execute um pool de workers, faça retry em falhas transientes e dimensione sua concorrência pelo limite de taxa.
Onde a API se encaixa
Cinco padrões de integração que aparecem:
1. Upload de produto em e-commerce. Quando um lojista faz upload de uma foto de produto, chame Remove BG, armazene o PNG transparente junto ao original e deixe seu sistema de templates fazer composição contra fundos de marca (branco para listagens, gradiente para hero shots, cor sazonal para páginas de campanha). Você nunca roda o modelo novamente.
2. Pipeline de assets de ferramenta de design. Arraste uma imagem para um canvas, o fundo some. Este é o modelo Figma / Canva, e o orçamento de latência para o qual otimizamos.
3. Apps de foto. Modelos on-device estão ficando bons, mas são grandes, lentos em hardware mais antigo e caros de atualizar. Se seu app já tem um round-trip de rede para outras coisas, um recorte via API é frequentemente a decisão certa — binário menor, melhores resultados, mais fácil de melhorar.
4. Automação de criativos para anúncios. Templates de anúncios com fundo variável alimentados por um feed de produtos: remova o fundo uma vez, faça composição N vezes, entregue N criativos. Remove BG é a etapa do "uma vez".
5. Pipelines de geração por IA. Um gerador produz um sujeito em um fundo simples, um segundo pipeline faz composição dele em uma cena. Alfa limpo nesta etapa é a diferença entre saída utilizável e borrão de IA óbvio.
Modos de falha e como lidar
Toda API de imagem tem entradas que ela não gosta. As que merecem atenção:
- Imagens de resolução muito baixa (abaixo de ~400px no lado maior). O modelo precisa de sinal suficiente para fazer matte de uma borda; abaixo disso, o recorte fica quantizado. Se você está construindo um produto voltado ao usuário, rejeite imagens muito pequenas antes de chamar.
- Entradas transparentes. Se a fonte já tem um canal alfa, o modelo vai interpretar as regiões transparentes como fundo. Se você quer preservar a transparência existente, achate sobre branco primeiro.
- Motion blur extremo. Carros de corrida, esportes de ação. O modelo mantém o sujeito mas suaviza as bordas mais do que uma captura mais nítida faria.
- Colisão de cor sujeito-fundo. Vestido branco em lençol branco; cachorro preto em sofá preto. Os resultados ainda são utilizáveis, mas a confiança nas bordas cai. Estes são os casos que valem uma etapa de revisão humana.
A resposta inclui um campo code. 0 é sucesso. Valores diferentes de zero (junto com uma message legível por humanos) sinalizam problemas na entrada — URLs inacessíveis, formatos não suportados, imagens muito grandes, limites de taxa atingidos. Trate valores diferentes de zero como sinal para fazer retry (erros de rede) ou falhar rápido com o usuário (erros de entrada).
Preços e notas operacionais
Os planos públicos são medidos por chamada bem-sucedida, com créditos acumuláveis para que volume não utilizado de um mês não evapore. Para uso de alto volume — pense em dezenas de milhões de imagens por mês — o tier enterprise é um compromisso de tarifa fixa com chave dedicada, limites de taxa customizados e fila prioritária. Não existe tier por tamanho no plano gratuito: a qualidade é a mesma em todos os planos, as únicas variáveis são volume e SLA.
As imagens de saída são servidas de uma URL CDN que é válida por tempo suficiente para você baixar e fazer cache. Não faça hot-link; baixe o resultado, armazene em seu próprio bucket e sirva de lá. As URLs são limitadas à requisição, não são de longa duração.
Comece rápido
- Chave em codia.ai/dashboard/developer.
- Execute o
curlacima com qualquer foto de produto. - Baixe a
data.image_url, faça composição sobre um fundo escuro, dê zoom na borda. - Se parecer bom — e deve — conecte ao seu pipeline como a etapa pós-upload.
Referência completa, códigos de erro e preços por volume em /api#remove-background.
O objetivo era uma API entediante. Um endpoint, um recorte rápido e limpo, confiável sob carga. Se você não precisa pensar na coisa depois de conectá-la, esse é o ganho.