API PARA PROGRAMADORES · BETA PÚBLICA

API do MegaPotato

Amplia fotos a partir do teu código com o mesmo modelo e os mesmos preços em batatinhas do site. Dois pedidos: envias uma foto e depois obténs o resultado. Na nossa comparação de 18 ampliadores de imagem com IA de outubro de 2026, o modelo ficou em primeiro lugar e foi o mais barato entre os líderes.

Nesta página

Guia rápido

Cria uma chave na página da tua conta, coloca-a na variável de ambiente MEGAPOTATO_API_KEY e executa:

shell
# 1. Enviar uma foto
curl https://megapotato.app/v1/upscale \
  -H "Authorization: Bearer $MEGAPOTATO_API_KEY" \
  -H "Idempotency-Key: photo-001" \
  -F file=@photo.jpg \
  -F upscale=4
# → {"id": "6f6f4c1e-…", "status": "queued", "upscale": 4, "cost_chips": 2}

# 2. Esperar pelo resultado (o servidor mantém o pedido aberto até 55 s)
curl "https://megapotato.app/v1/jobs/6f6f4c1e-…?wait=55" \
  -H "Authorization: Bearer $MEGAPOTATO_API_KEY"
# → {"status": "completed", "result_url": "https://…", …}

Experimenta sem chave

Sem conta e sem chave: envia uma foto para /v1/try e consulta periodicamente /v1/try/{id}. É uma tarefa real no mesmo modelo; cost_chips indica o custo com chave e não há cobranças. As tarefas de experimentação ficam atrás de todas as tarefas com chave na fila, por isso podem demorar mais quando o serviço está ocupado. A experimentação tem um orçamento limitado: 429 significa que deves esperar o tempo indicado em Retry-After ou obter uma chave; 403 significa que está indisponível. Indisponível de momento; usa uma chave de teste ou uma chave API da página da tua conta.

shell
# 1. Enviar uma foto (sem conta nem chave)
curl https://megapotato.app/v1/try -F file=@photo.jpg -F upscale=4
# → {"id": "6f6f4c1e-…", "status": "queued", "upscale": 4, "cost_chips": 2}

# 2. Esperar pelo resultado (o servidor mantém o pedido aberto até 55 s)
curl "https://megapotato.app/v1/try/6f6f4c1e-…?wait=55"
# → {"status": "completed", "result_url": "https://…", …}

Chaves de teste

Queres preparar a integração antes de comprares batatinhas? Qualquer conta com sessão iniciada pode criar uma chave de teste (mp_test_…) na página da conta. Percorre todo o processo — as imagens são verificadas e o preço é calculado tal como com uma chave de produção — mas nada é processado nem cobrado: cada tarefa devolve completed com uma imagem de exemplo em result_url e result_jpeg_url, e jpeg_status é sempre ready, quer envies jpeg=true quer não. Repetir o pedido com a mesma Idempotency-Key e foto devolve o mesmo ID de tarefa; reutilizar uma chave para outra foto só é rejeitado (422) com chaves de produção. Muda para uma chave de produção quando estiveres pronto. As chaves de produção ficam disponíveis com o teu primeiro pack de batatinhas.

Autenticação

Envia a tua chave em cada pedido no cabeçalho Authorization: Bearer mp_live_…. As chaves só são mostradas uma vez, ao criá-las; guardamos apenas um hash. Mantém-nas no teu servidor — nunca numa app móvel, página web ou repositório. Se uma chave for exposta, revoga-a na página da tua conta; deixa de funcionar de imediato.

Consultar o preço — POST /v1/quote

Envia o tamanho de entrada e o fator de ampliação para obteres o preço. Não é carregada nenhuma imagem nem há cobranças.

shell
curl https://megapotato.app/v1/quote \
  -H "Authorization: Bearer $MEGAPOTATO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"width": 4032, "height": 3024, "upscale": 2}'
# → {"cost_chips": 5, "output_width": 8064, "output_height": 6048, "upscale": 2}

Ampliar uma foto — POST /v1/upscale

Formulário multipart com file (PNG, JPG, WEBP e HEIC, até 40 MB) e upscale: 1 (Refinar, mesmo tamanho), 2, 4 ou 8. A imagem de entrada pode ter até 6 000 px no lado maior e o resultado até 16 400 px — escolhe um fator menor para fotos grandes.

response
{"id": "6f6f4c1e-…", "status": "queued", "upscale": 4, "cost_chips": 2}

O valor de cost_chips é reservado no teu saldo de imediato e cobrado quando a foto fica pronta. Se o processamento falhar, as batatinhas são devolvidas automaticamente.

A opção jpeg=true acrescenta um JPEG do resultado com as mesmas dimensões do resultado (qualidade 92, sem subamostragem de crominância) ao PNG, sem custo extra. Um PNG 16K sem perdas pode ocupar várias centenas de MB; o JPEG do mesmo resultado costuma ocupar uma pequena fração disso. A tarefa passa a incluir result_jpeg_url e jpeg_status. Reutilizar uma Idempotency-Key com outra foto, upscale ou jpeg resulta num 422.

Obter o resultado — GET /v1/jobs/{id}

Adiciona ?wait=55 e o servidor mantém o pedido aberto até a tarefa terminar ou passarem 55 segundos — o que acontecer primeiro. Uma chamada costuma cobrir toda a tarefa.

A maioria das fotos fica pronta em segundos. Quando a procura aumenta, adicionamos capacidade e os primeiros pedidos podem demorar alguns minutos — depois tudo corre à velocidade máxima. Continua a consultar com ?wait=55; não precisas de fazer mais nada.

response
{
  "id": "6f6f4c1e-…",
  "status": "completed",          // queued → running → completed | failed
  "result_url": "https://…",      // PNG; link válido por cerca de uma hora, sem necessidade de cabeçalho de autenticação
  "error": null,                  // o motivo em caso de falha, com «as tuas batatinhas foram reembolsadas»
  "upscale": 4,
  "created_at": "2026-09-15T10:00:00Z",
  "eta_seconds": null,            // uma estimativa enquanto está na fila ou em curso
  "result_jpeg_url": "https://…", // com jpeg=true: o JPEG com as mesmas dimensões do resultado, com as mesmas regras de result_url
  "jpeg_status": "ready"          // null sem jpeg=true; pending → ready | unavailable
}

Consulta a tarefa de novo para obteres um result_url atualizado. Os resultados ficam disponíveis durante 90 dias.

jpeg_status é pending enquanto a tarefa está na fila ou em curso, ready quando result_jpeg_url está definido e unavailable se a tarefa terminou sem JPEG (o PNG continua disponível), falhou ou expirou. Sem jpeg=true, ambos os campos são null. As chaves de teste são a exceção: ambos os URLs contêm a imagem de exemplo e jpeg_status é sempre ready.

Uma tarefa completed pode ainda indicar pending enquanto o JPEG é carregado — normalmente durante segundos, em casos raros até cerca de uma hora: result_url já funciona e uma nova consulta devolve result_jpeg_url (ou unavailable se não ficar disponível).

Erros

Todos os erros têm a mesma estrutura:

response
{"error": {"type": "insufficient_credits", "message": "insufficient chips: available 0, needed 2"}}
  • 400 · invalid_request_error
    Não é possível descodificar a imagem ou o tamanho excede os limites.
  • 401 · authentication_error
    A chave está em falta, incorreta ou revogada.
  • 402 · insufficient_credits
    Não tens batatinhas suficientes para esta foto — a mensagem indica quantas são necessárias.
  • 404 · invalid_request_error
    A tarefa não existe (ou não é tua).
  • 413 · invalid_request_error
    O ficheiro excede o limite de carregamento.
  • 415 · invalid_request_error
    Formato de imagem não suportado.
  • 422 · invalid_request_error
    Valor inválido de upscale ou jpeg, ficheiro em falta ou Idempotency-Key reutilizada com outra foto, upscale ou jpeg.
  • 429 · rate_limit_error
    Demasiados pedidos ou fotos em curso ao mesmo tempo. Respeita Retry-After.
  • 422 · content_not_allowed
    A nossa verificação automática de conteúdo bloqueou a imagem (consulta os Termos). Não houve cobranças.
  • 429 · spend_limit_reached
    Atingiste o limite diário de gastos da API. É reposto às 00:00 UTC.
  • 500 · server_error
    A falha é nossa. Tenta de novo — com a mesma Idempotency-Key nos carregamentos.
  • 503 · service_unavailable
    Não podemos aceitar imagens de momento. Não houve cobranças; tenta de novo após o tempo indicado em Retry-After.

Limites

  • Até 10 fotos em curso ao mesmo tempo por conta. Acima disso, um novo carregamento recebe 429 e não há cobranças.
  • Até 100 carregamentos por minuto por chave; os pedidos de estado têm limites mais generosos.
  • Um limite diário de gastos pela API (dia UTC) impede que uma chave exposta esgote o teu saldo — por predefinição, 5 000 batatinhas por dia. Podes definir um limite inferior na página da tua conta.

Preços

A API custa exatamente o mesmo que o site para a mesma foto e fator, com pagamento a partir do mesmo saldo de batatinhas. O preço aumenta com o tamanho do resultado: uma foto de 1 MP a ×4 custa cerca de 2 batatinhas; uma foto de telemóvel de 12 MP a ×2, cerca de 5 batatinhas. Cada batatinha custa $0.033–0.05, consoante o pack. Consulta qualquer tamanho com /v1/quote; uma tarefa que falhe é reembolsada automaticamente. Compra batatinhas na página de preços; nunca expiram.

Novas tentativas

  • Envia sempre uma Idempotency-Key (até 128 caracteres, única por foto) nos carregamentos. Repetir o pedido com a mesma chave devolve a mesma tarefa e cobra apenas uma vez — podes repetir um pedido que excedeu o tempo de espera sem risco de nova cobrança.
  • Se receberes 429, espera o tempo indicado em Retry-After. Com 5xx ou um erro de rede, tenta de novo com pausas crescentes (1 s, 2 s, 4 s…). Repetir outros erros 4xx não resolve — corrige o pedido.
  • Consulta com ?wait=55 em vez de fazeres uma chamada a cada segundo.

Beta e versões

A API está em beta pública: ainda não há garantia de disponibilidade e avisamos-te por email sobre alterações planeadas. Na versão /v1, só acrescentamos elementos — novos campos, novos tipos de erro — por isso ignora os campos que não conheces. Qualquer alteração que quebre uma integração será lançada como /v2, com aviso de pelo menos 90 dias.

Utilização aceitável

Os resultados pertencem-te. Usa a API apenas para imagens que tens o direito de processar. Não a uses para conteúdos ilegais, conteúdos sexuais que envolvam menores ou imagens íntimas de alguém sem o seu consentimento. As contas que violem estas regras ou os Termos são bloqueadas. Denuncia abusos para abuse@megapotato.app; envia dúvidas para support@megapotato.app.

Obter a tua chave API

Especificação, exemplos, nó