Remove BG

Visão geral

O Remove BG remove o fundo de qualquer imagem e retorna um PNG transparente. Um endpoint, um campo obrigatório, um formato de resposta. Projetado para páginas de produto, ferramentas de design, pipelines de criativos para anúncios e qualquer fluxo de trabalho que precise de recortes limpos em escala.

Endpoint

POSThttps://api.codia.ai/v1/open/remove_bg

A autenticação é via bearer token. Obtenha uma chave em codia.ai/dashboard/developer.

Requisição

Campo	Tipo	Obrigatório	Descrição
`image_url`	string	sim	URL publicamente acessível da imagem de origem.

Exemplo

bash

curl 'https://api.codia.ai/v1/open/remove_bg' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -H 'Content-Type: application/json' \
  --data '{
    "image_url": "your image url"
  }'

Resposta

json

{
  "code": 0,
  "message": "ok",
  "data": {
    "image_url": "https://processed-image-url.com/result.png"
  }
}

Campo	Descrição
`code`	`0` em caso de sucesso. Valores diferentes de zero indicam erros de entrada ou processamento.
`message`	Status legível por humanos.
`data.image_url`	URL CDN do PNG resultante com fundo transparente. Baixe e armazene do seu lado; as URLs não são de longa duração.

Características da saída

Formato — PNG com canal alfa.
Resolução — corresponde à entrada até o máximo do plano (HD em todos os tiers).
Qualidade de borda — matting subpixel, descontaminação de cor no primeiro plano, sem borrão de sombra do fundo.
Auto-sombras no sujeito — mantidas (ex.: lado sombreado de baixo de uma caneca).

Desempenho

Configuração	Valor
Tempo de processamento típico	~600 ms
Latência ponta a ponta	800 – 1200 ms
Concorrência	Depende do plano; planos típicos suportam centenas de requisições paralelas

Entradas suportadas

Entrada	Recomendação
Formatos comuns	JPEG, PNG, WEBP
Resolução mínima	400 px no lado maior
Tamanho máximo	Depende do plano; padrão de 25 MB
Imagens com alfa existente	Achate sobre branco antes de chamar para preservar a transparência pretendida
Motion blur extremo	Funciona, mas as bordas ficam mais suaves
Colisão de cor sujeito / fundo (ex.: branco sobre branco)	Utilizável, mas considere revisão humana

Códigos de erro

`code`	Significado
`0`	Sucesso.
`40001`	`image_url` ausente ou inacessível.
`40002`	Formato não suportado.
`40003`	Imagem excede o limite de tamanho.
`42900`	Limite de taxa excedido — aguarde e tente novamente.
`50000`	Erro transitório do servidor — tente novamente com backoff.

Sempre trate code diferente de zero como sinal para ramificar: retry em erros transitórios, falha rápida em erros de entrada.

Padrões de integração

Upload de produto (síncrono)

const res = await fetch('https://api.codia.ai/v1/open/remove_bg', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${CODIA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ image_url: sourceUrl }),
}).then((r) => r.json())

if (res.code === 0) {
  await saveToBucket(res.data.image_url)
}

Ingestão em lote (assíncrona)

Para catálogos grandes, execute um pool de workers no limite de concorrência do seu plano e faça retry em falhas transitórias. Pule imagens abaixo da resolução mínima em vez de desperdiçar chamadas.

Composição

Faça a composição do PNG retornado sobre um fundo escuro (ex.: #111) durante o desenvolvimento para identificar franjas nas bordas. Recortes limpos se sustentam; se você vir um halo, inspecione a entrada.

FAQ

Posso fazer upload em vez de passar uma URL?

O endpoint atual requer uma URL. Se você precisa de upload multipart, entre em contato com [email protected] — está no roadmap e disponível hoje para planos enterprise.

As URLs de saída são permanentes?

Não. Baixe o resultado e armazene em seu próprio bucket — as URLs são válidas por tempo suficiente para recuperação, mas expiram.

O preço varia pelo tamanho da imagem?

Não. O preço é por chamada bem-sucedida, fixo.

Existe rollover para créditos não utilizados?

Sim — créditos não utilizados acumulam mensalmente em planos pagos. Veja preços.

Posso manter sombras projetadas?

O padrão remove todo o fundo, incluindo sombras projetadas. Manter sombras está disponível em implantações enterprise com um flag de configuração.

Próximos passos

PDF to Visual Struct — conversão estrutural de documentos PDF.
Visual Struct — conversão estrutural de imagens.
Referência completa do endpoint em /api#remove-background.