how-tos

Fundo transparente na MAI Image 2.7 API: recursos PNG e WebP

Poyo.ai Team
8 min read
Share:

Recursos PNG e WebP transparentes com a MAI Image 2.7 API

A MAI Image 2.7 API consegue devolver imagens com um canal alfa real, por isso recortes de produto, logótipos, ícones e stickers saem prontos a colocar sobre qualquer fundo, sem passo de máscara. Na PoYo bastam dois campos, background e output_format, tanto no mai-image-2.7 como no mai-image-2.7-flash. No nosso teste do dia do lançamento, um PNG transparente de 1024x1024 no Flash fica em 2.062 créditos às tarifas atuais, cerca de $0.0103. Experimente-o na página do modelo MAI Image 2.7 antes de o integrar no código.

O que a Microsoft diz sobre a transparência

O anúncio de lançamento da Microsoft diz que «ambos os modelos suportam fundos transparentes para imagens de produto prontas a usar», e refere logótipos, ícones e ilustrações como outras utilizações. A documentação do Foundry da Microsoft indica o fundo transparente como uma capacidade que o MAI-Image-2.7 acrescenta em relação aos modelos de imagem MAI anteriores, «para recursos como imagens de produto, logótipos, ícones e elementos de design que têm de ser colocados sobre outro conteúdo». O MAI Image 2.6 não tem essa opção.

Os dois campos

CampoValoresPredefiniçãoRegra
backgroundopaque, transparentopaquetransparent devolve uma imagem com canal alfa
output_formatpng, jpeg, webppngtransparent exige png ou webp

Como as predefinições são opaque e png, tem de enviar background explicitamente para obter transparência. output_format pode ser omitido para PNG, mas enviá-lo torna a intenção evidente nos logs. "background": "transparent" com "output_format": "jpeg" é inválido, porque o JPEG não tem canal alfa; valide essa combinação do seu lado para que falhe antes da submissão.

Todos os outros campos funcionam como habitualmente: size (1:1 por predefinição, qualquer proporção predefinida ou um WIDTHxHEIGHT personalizado até 4,194,304 píxeis), resolution (1K ou 2K) e um callback_url opcional. As regras completas dos campos estão na referência da API.

Corpos de pedido

PNG transparente com a MAI Image 2.7 API

Um sticker quadrado em 1K no Flash, com as mesmas definições de campos da nossa execução medida (o prompt é um exemplo):

curl https://api.poyo.ai/api/generate/submit \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mai-image-2.7-flash",
    "input": {
      "prompt": "A cute cartoon sticker of a smiling coffee cup with a thick white outline, centered, no background",
      "size": "1:1",
      "resolution": "1K",
      "background": "transparent",
      "output_format": "png"
    }
  }'

Logótipo WebP transparente

O exemplo da documentação da PoYo, no modelo principal:

{
  "model": "mai-image-2.7",
  "input": {
    "prompt": "A flat vector logo of a red fox head, clean edges, no background",
    "background": "transparent",
    "output_format": "webp"
  }
}

O WebP também suporta canal alfa e costuma gerar ficheiros mais leves do que o PNG, o que se adequa a páginas web. O PNG é a escolha mais segura para fluxos de impressão e ferramentas de design que o esperam.

Ambos os pedidos devolvem um task_id. Consulte GET https://api.poyo.ai/api/generate/status/{task_id} até status ser finished e depois descarregue data.files[0].file_url. O guia da MAI Image 2.7 API inclui um ciclo de polling completo.

Medido: um sticker transparente no dia do lançamento

A equipa da PoYo executou este pedido na API de produção da PoYo a 19 de novembro de 2026:

DefiniçãoValor
Modelomai-image-2.7-flash
Campossize: "1:1", resolution: "1K", background: "transparent", output_format: "png"
SaídaPNG de 1024x1024, RGBA
FundoAlfa real: totalmente transparente à volta do motivo
Custo às tarifas atuais2.062 créditos (cerca de $0.0103)
TempoCerca de 42 s, da submissão ao resultado com polling a cada poucos segundos

Estimativa derivada: 1024x1024 corresponde a cerca de 1,024 tokens de saída a 2,000 créditos por 1M, ou seja, 2.048 créditos; os 0.014 créditos restantes equivalem a cerca de 40 tokens de prompt a 350 créditos por 1M. Por outras palavras, a imagem transparente foi cobrada como qualquer outra imagem desse tamanho. A tabela de preços não tem sobretaxa por transparência.

Verificar o canal alfa no código

Não confie na extensão do ficheiro: confirme que a imagem descarregada tem realmente píxeis transparentes antes de entrar na sua biblioteca de recursos. Com Pillow:

import io
import requests
from PIL import Image

def check_transparency(file_url):
    data = requests.get(file_url, timeout=60).content
    img = Image.open(io.BytesIO(data))
    if img.mode != "RGBA":
        img = img.convert("RGBA")
    alpha = img.getchannel("A")
    lo, hi = alpha.getextrema()
    clear = sum(1 for a in alpha.getdata() if a == 0)
    share = clear / (img.width * img.height)
    print(img.size, img.mode, "alpha range", (lo, hi), f"{share:.0%} fully transparent")
    return lo == 0 and share > 0.05

Um resultado com lo == 0 e uma parte significativa de píxeis totalmente transparentes indica um recorte utilizável. A imagem de um padrão em xadrez mostraria lo == 255, com todos os píxeis opacos. Escolha o limiar de acordo com os seus próprios recursos: uma ilustração que ocupa todo o enquadramento terá menos espaço vazio do que um ícone centrado.

Prompts para recortes limpos

O modelo trata do canal alfa; o prompt continua a decidir quão fácil é isolar o motivo.

  • Diga que o motivo está sozinho. O exemplo da documentação da PoYo termina com "clean edges, no background". O exemplo do Foundry da Microsoft para uma imagem transparente usa "full body, centered, no shadow".
  • Evite palavras de cena. "On a table", "in a studio" ou "with a shadow" pedem elementos que ficam fora do motivo.
  • Peça um contorno nos stickers. Uma borda branca grossa destaca-se bem tanto em fundos claros como escuros.
  • Coloque o texto entre aspas. Se o recurso incluir uma palavra ou o texto de um logótipo, coloque-o entre aspas, como a documentação recomenda para o texto na imagem.

Custo de recursos transparentes em volume

Os tokens de saída dependem apenas do número de píxeis, por isso a transparência custa o mesmo que uma saída opaca. Custo dos tokens de saída por imagem:

TamanhoMAI Image 2.7MAI Image 2.7 Flash
1024x1024 (1:1, 1K)6.96 créditos ($0.0348)2.05 créditos ($0.0102)
2048x2048 (1:1, 2K)27.85 créditos ($0.1393)8.19 créditos ($0.0410)

Aos 2.062 créditos medidos por sticker no Flash, 1,000 stickers ficam em cerca de 2,062 créditos, aproximadamente $10.31. Use o Flash para conjuntos de ícones e recortes de catálogo, e o MAI Image 2.7 quando um único recurso, como o logótipo de uma marca ou uma fotografia hero de produto, tem de ficar o melhor possível. O artigo de preços e a comparação Flash vs 2.7 aprofundam o tema.

Definições para trabalhos comuns com recursos transparentes

TrabalhoModelosize / resolutionoutput_format
Stickers para chat ou aplicações em massamai-image-2.7-flash1:1, 1Kpng ou webp
Ícones e ilustrações para websitesmai-image-2.7-flash1:1, 1Kwebp
Recortes de produto para e-commercemai-image-2.71:1 ou 3:4, 2Kpng
Logótipo de marca para impressão e apresentaçõesmai-image-2.71:1, 2Kpng
Elemento de banner largo para sobrepor a um heromai-image-2.7Personalizado, p. ex. 3072x1344webp

São pontos de partida, não regras: cada linha usa apenas os campos documentados, por isso pode mover um trabalho entre níveis ou tamanhos sem alterar mais nada no pedido. Execute a verificação alfa no primeiro lote de cada novo tipo de trabalho.

Edição com resultado transparente

O esquema também permite background: "transparent" em conjunto com image_urls, por exemplo para transformar uma fotografia de produto num recorte ou para alterar o estilo de um sticker existente mantendo o canal alfa. Ainda não medimos essa combinação, por isso teste-a com algumas das suas imagens e execute a verificação alfa acima antes de confiar nela em produção.

Perguntas frequentes

Como obtenho um fundo transparente com a MAI Image 2.7 API? Envie "background": "transparent" e "output_format": "png" (ou "webp") dentro de input. A predefinição é um PNG opaco.

A MAI Image 2.7 API consegue devolver um JPEG transparente? Não. O JPEG não tem canal alfa, por isso transparent exige PNG ou WebP.

O MAI Image 2.7 Flash suporta fundos transparentes? Sim. O nosso teste do dia do lançamento no mai-image-2.7-flash devolveu um PNG RGBA de 1024x1024 com fundo totalmente transparente por 2.062 créditos às tarifas atuais.

Um fundo transparente custa mais na MAI Image 2.7 API? Não. É cobrado às mesmas tarifas de tokens de texto, entrada de imagem e saída que qualquer outra imagem do mesmo tamanho.

O MAI Image 2.6 consegue criar PNG transparentes? Não. A transparência é uma novidade do MAI Image 2.7. Veja MAI Image 2.7 API vs MAI Image 2.6 API para as restantes alterações de campos.

Share: