how-tos

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

Poyo.ai Team
8 min read
Share:

Assets PNG e WebP transparentes com a MAI Image 2.7 API

A MAI Image 2.7 API pode retornar imagens com um canal alfa de verdade, então recortes de produto, logos, ícones e stickers já saem prontos para ir sobre qualquer fundo, sem etapa de máscara. Na PoYo bastam dois campos, background e output_format, tanto no mai-image-2.7 quanto no mai-image-2.7-flash. No nosso teste do dia do lançamento, um PNG transparente de 1024x1024 no Flash sai por 2.062 créditos nas tarifas atuais, cerca de $0.0103. Teste na página do modelo MAI Image 2.7 antes de integrar no código.

O que a Microsoft diz sobre transparência

O anúncio de lançamento da Microsoft diz que "os dois modelos suportam fundos transparentes para imagens de produto prontas para uso", e cita logos, ícones e ilustrações como outros usos. A documentação do Foundry da Microsoft lista o fundo transparente como um recurso que o MAI-Image-2.7 acrescenta em relação aos modelos de imagem MAI anteriores, "para assets como imagens de produto, logos, ícones e elementos de design que precisam ser colocados sobre outro conteúdo". O MAI Image 2.6 não tem essa opção.

Os dois campos

CampoValoresPadrãoRegra
backgroundopaque, transparentopaquetransparent retorna uma imagem com canal alfa
output_formatpng, jpeg, webppngtransparent exige png ou webp

Como os padrões são opaque e png, você precisa enviar background explicitamente para ter transparência. output_format pode ser omitido para PNG, mas enviá-lo deixa a intenção clara 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 ela falhe antes do envio.

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

Corpos de requisição

PNG transparente com a MAI Image 2.7 API

Um sticker quadrado em 1K no Flash, com as mesmas configuraçõ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"
    }
  }'

Logo 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 arquivos menores que o PNG, o que funciona bem em páginas web. O PNG é a opção mais segura para fluxos de impressão e ferramentas de design que esperam esse formato.

As duas requisições retornam um task_id. Faça polling em GET https://api.poyo.ai/api/generate/status/{task_id} até status ser finished e então baixe data.files[0].file_url. O guia da MAI Image 2.7 API tem um loop de polling completo.

Medido: um sticker transparente no dia do lançamento

A equipe da PoYo executou esta requisição na API de produção da PoYo em 19 de novembro de 2026:

ConfiguraçãoValor
Modelomai-image-2.7-flash
Campossize: "1:1", resolution: "1K", background: "transparent", output_format: "png"
SaídaPNG de 1024x1024, RGBA
FundoAlfa de verdade: totalmente transparente ao redor do objeto
Custo nas tarifas atuais2.062 créditos (cerca de $0.0103)
TempoCerca de 42 s, do envio ao resultado com polling a cada poucos segundos

Estimativa derivada: 1024x1024 dá cerca de 1,024 tokens de saída a 2,000 créditos por 1M, ou seja, 2.048 créditos; o 0.014 crédito restante equivale a cerca de 40 tokens de prompt a 350 créditos por 1M. Em 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.

Checar o canal alfa no código

Não confie na extensão do arquivo: confirme que a imagem baixada tem mesmo pixels transparentes antes de ela entrar na sua biblioteca de assets. 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 parcela relevante de pixels totalmente transparentes indica um recorte utilizável. A imagem de um fundo quadriculado mostraria lo == 255, com todos os pixels opacos. Escolha o limite de acordo com os seus próprios assets: uma ilustração que ocupa o quadro inteiro tem menos espaço vazio do que um ícone centralizado.

Prompts para recortes limpos

O modelo cuida do canal alfa; o prompt continua decidindo o quanto é fácil isolar o objeto.

  • Diga que o objeto 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 coisas que ficam fora do objeto.
  • Peça um contorno nos stickers. Uma borda branca grossa fica boa tanto em fundos claros quanto escuros.
  • Coloque o texto entre aspas. Se o asset tiver uma palavra ou o texto de um logo, coloque entre aspas, como a documentação recomenda para texto na imagem.

Custo de assets transparentes em volume

Os tokens de saída dependem só do número de pixels, então 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)

Com os 2.062 créditos medidos por sticker no Flash, 1,000 stickers saem por 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 asset, como o logo de uma marca ou uma foto hero de produto, precisa ficar o melhor possível. O post de preços e a comparação Flash vs 2.7 aprofundam o assunto.

Configurações para jobs comuns com assets transparentes

JobModelosize / resolutionoutput_format
Stickers para chat ou app em massamai-image-2.7-flash1:1, 1Kpng ou webp
Ícones e ilustrações para sitesmai-image-2.7-flash1:1, 1Kwebp
Recortes de produto para e-commercemai-image-2.71:1 ou 3:4, 2Kpng
Logo da marca para impressão e apresentaçõesmai-image-2.71:1, 2Kpng
Elemento de banner largo para sobrepor a um heromai-image-2.7Personalizado, por ex. 3072x1344webp

São pontos de partida, não regras: cada linha usa só os campos documentados, então você pode mover um job entre níveis ou tamanhos sem mudar mais nada na requisição. Rode a checagem alfa no primeiro lote de cada novo tipo de job.

Edição com resultado transparente

O schema também permite background: "transparent" junto com image_urls, por exemplo para transformar uma foto de produto em recorte ou para mudar o estilo de um sticker existente mantendo o canal alfa. Ainda não medimos essa combinação, então teste com algumas das suas imagens e rode a checagem alfa acima antes de confiar nela em produção.

Perguntas frequentes

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

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

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

Fundo transparente custa mais na MAI Image 2.7 API? Não. Ele é cobrado pelas 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 gerar PNGs transparentes? Não. A transparência é novidade do MAI Image 2.7. Veja MAI Image 2.7 API vs MAI Image 2.6 API para as outras mudanças de campos.

Share: