API de upscaling de imagens: Guia de integração para desenvolvedores

Integrar upscaling de imagens no seu app costumava significar treinar modelos de IA do zero. Meses de trabalho e um orçamento pesado em GPUs. Com a API do UpscaleIMG, você envia uma imagem e recebe uma versão nítida e ampliada em segundos.

Este guia mostra como integrar o UpscaleIMG no seu projeto. Com exemplos de código reais e todas as opções disponíveis.

O que a API do UpscaleIMG pode fazer?

A API do UpscaleIMG usa Real-ESRGAN. É um modelo de IA poderoso feito para super-resolução de imagens. Você envia uma foto e a IA adiciona detalhes realistas ao ampliar. As bordas ficam nítidas. As texturas parecem naturais. Os rostos mantêm seus traços.

Veja o que você recebe:

• Upscaling 2x e 4x com melhoria de detalhes por IA
• Dimensões personalizadas para um tamanho de saída específico
• Conversão de formato entre PNG, JPG e WebP
• Controle de metadados para remover ou manter dados EXIF
• Até 64 megapixels de resolução de saída

Todo o processamento de IA roda nos nossos servidores. Sem necessidade de GPU do seu lado. Sem configurar modelos. Envie uma requisição HTTP e receba seu resultado.

Como começar com a API?

Você precisa de uma chave API para fazer requisições. Veja como conseguir:

1. Crie uma conta no upscaleimg.app
2. Vá ao seu painel e gere uma chave API
3. Guarde-a com segurança no seu servidor

O endpoint da API é:

POST https://upscaleimg.app/api/v1/upscale

A autenticação usa um token Bearer no header Authorization. Mantenha sua chave API no servidor. Nunca exponha no código do cliente nem faça commit no repositório.

Contas gratuitas têm upscaling 2x. Assinantes desbloqueiam 4x e dimensões personalizadas até 4x o tamanho original.

Como ampliar sua primeira imagem?

A chamada mais simples precisa apenas de uma imagem e um fator de escala. Aqui um exemplo curl para 2x:

curl -X POST https://upscaleimg.app/api/v1/upscale \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@photo.jpg" \
  -F "scale=2"

A API retorna JSON com detalhes da imagem original e ampliada:

{
  "original": {
    "size": 384000,
    "width": 1920,
    "height": 1080,
    "mimeType": "image/jpeg",
    "fileExt": "jpg"
  },
  "result": {
    "size": 1280000,
    "width": 3840,
    "height": 2160,
    "mimeType": "image/png",
    "fileExt": "png",
    "url": "https://..."
  }
}

O campo url fornece um link de download assinado. Baixe imediatamente, pois URLs assinadas expiram rápido.

O mesmo em JavaScript:

const form = new FormData();
form.append('image', fileInput.files[0]);
form.append('scale', '2');

const response = await fetch('https://upscaleimg.app/api/v1/upscale', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: form
});

const data = await response.json();
console.log(`Ampliado para ${data.result.width}x${data.result.height}`);

E em Python:

import requests

with open('photo.jpg', 'rb') as f:
    response = requests.post(
        'https://upscaleimg.app/api/v1/upscale',
        headers={'Authorization': 'Bearer YOUR_API_KEY'},
        files={'image': f},
        data={'scale': '2'}
    )

data = response.json()
print(f"Ampliado para {data['result']['width']}x{data['result']['height']}")

Quais opções a API suporta?

A API aceita vários parâmetros via dados multipart. Aqui a lista completa:

Parâmetro	Obrigatório	Valores	Descrição
image	Sim	Arquivo	Imagem PNG, JPG, JPEG ou WebP
scale	Sim*	2 ou 4	Fator de escala. *Não necessário com dimensões personalizadas.
customWidth	Não	Inteiro	Largura alvo em pixels (máx. 4x original)
customHeight	Não	Inteiro	Altura alvo em pixels (máx. 4x original)
objectFit	Não	cover, contain, fill	Modo de ajuste com dimensões personalizadas. Padrão: cover.
outputFormat	Não	jpg, jpeg, png, webp	Formato de saída. Padrão: png.
removeMetadata	Não	1 ou 0	Remover dados EXIF. Padrão: 0 (manter).

Dimensões personalizadas dão controle preciso. customWidth e customHeight devem ser informados juntos. A saída não pode ser menor que o original nem maior que 4x (2x para contas gratuitas).

Por exemplo, para ampliar para exatamente 3000x2000 em WebP:

curl -X POST https://upscaleimg.app/api/v1/upscale \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@photo.jpg" \
  -F "customWidth=3000" \
  -F "customHeight=2000" \
  -F "objectFit=cover" \
  -F "outputFormat=webp" \
  -F "removeMetadata=1"

O parâmetro objectFit funciona como CSS object-fit. cover preenche as dimensões exatas (pode cortar). contain encaixa dentro das dimensões (pode adicionar margens). fill estica para o tamanho exato.

Como lidar com erros e limites de requisições?

A API retorna códigos HTTP padrão:

Código	Significado
200	Sucesso. Imagem ampliada retornada.
400	Requisição inválida. Imagem ausente, fator inválido ou dimensões fora do limite.
401	Chave API inválida ou ausente.
403	Proibido. Tentativa de 4x sem assinatura ou erro CORS.
429	Limite atingido. Muitas requisições.
500	Erro do servidor. Tente novamente.

Todas as respostas de erro incluem uma mensagem:

{"error": "4x upscaling is only available with an active subscription."}

Para limites de requisições, adicione lógica de retry com backoff:

async function upscaleWithRetry(form, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const res = await fetch('https://upscaleimg.app/api/v1/upscale', {
      method: 'POST',
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
      body: form
    });

    if (res.status === 429) {
      await new Promise(r => setTimeout(r, 2000 * (i + 1)));
      continue;
    }

    return await res.json();
  }
  throw new Error('Max retries reached');
}

Quais são os melhores casos de uso?

A API do UpscaleIMG se encaixa perfeitamente em vários workflows.

Plataformas de e-commerce usam para melhorar fotos de produtos de vendedores. Muitos uploads são pequenos ou de baixa qualidade. Upscaling automático torna cada anúncio mais profissional. Saiba mais sobre aumentar a escala sem perder qualidade.

Serviços de impressão sob demanda precisam de arquivos em alta resolução. Clientes enviam imagens boas na tela mas pequenas para imprimir. Você pode até ampliar direto para 4K.

Apps de restauração de fotos combinam upscaling com outras melhorias. Fotos antigas ou desfocadas são corrigidas e ampliadas. A API faz o trabalho pesado de IA.

Sistemas de gerenciamento de conteúdo podem melhorar imagens automaticamente no upload. Cada imagem fica acima de um padrão mínimo de qualidade.

Sites de imóveis se beneficiam de qualidade fotográfica uniforme. Corretores enviam com câmeras diferentes. Upscaling automático cria uma aparência profissional.

Para processamento em lote, confira nosso guia sobre automatizar o upscaling de imagens. Você também pode comparar os melhores upscalers.

Pronto para começar?

Você terá uma integração funcionando em menos de uma hora. Crie sua conta no upscaleimg.app, pegue sua chave API e envie sua primeira imagem de teste.

Comece com 2x em algumas imagens para verificar a qualidade. Depois integre no seu pipeline. O guia completo de ampliação de imagens cobre tudo sobre upscaling com IA.

O plano gratuito basta para testar e construir seu proof of concept. Quando estiver pronto para 4x e volumes maiores, migre para um plano pago.