
Este guia da MAI Image 2.7 API leva você de uma chave de API até uma imagem pronta com cURL e Python e, depois, cobre todos os modos de entrada que o schema da PoYo aceita: text-to-image, edição de uma única imagem, composição de várias imagens, tamanhos personalizados, saída 2K e PNG ou WebP transparente. Todos os corpos abaixo usam o ID de modelo mai-image-2.7; troque por mai-image-2.7-flash para o nível mais barato, já que os dois schemas do MAI Image 2.7 são idênticos exceto pelo ID.
As regras dos campos vêm da referência da API da PoYo. Para entender o que é o modelo e como ele se compara, comece pela visão geral da MAI Image 2.7 API.
Passo 1: enviar uma requisição à MAI Image 2.7 API com cURL
Crie uma chave no painel da PoYo e exporte-a como POYO_API_KEY. Mantenha a chave no seu servidor, não no código do navegador.
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",
"input": {
"prompt": "A university campus poster at dusk with the title \"Open Day 2026\", photorealistic, cinematic light",
"size": "16:9",
"resolution": "2K"
}
}'
Um envio bem-sucedido retorna code: 200 e um objeto data com task_id, status: "not_started" e created_time. É uma tarefa na fila, ainda não uma imagem. Verifique o code no corpo toda vez: alguns erros de validação voltam com HTTP 200 e code: 400.
Passo 2: fazer polling do status da tarefa
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
O status passa por not_started, running e depois finished ou failed. Uma tarefa concluída lista a imagem em data.files como um objeto com file_url e file_type: "image" e informa a cobrança em credits_amount. Uma tarefa com falha explica o motivo em error_message.
Passo 3: um loop de polling em Python com limite
Este loop verifica tanto o status HTTP quanto o code do corpo, para em failed e desiste depois de 10 minutos sem reenviar. No nosso teste de lançamento de 19 de novembro de 2026, uma imagem 2K em 16:9 levou cerca de 66 segundos no MAI Image 2.7 e cerca de 42 segundos no Flash, então um intervalo de polling de 5 segundos é mais que suficiente.
import os
import time
import requests
BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]
def checked(response):
body = response.json()
if response.status_code >= 400 or body.get("code") != 200:
error = body.get("error") or {}
raise RuntimeError(f"PoYo error {body.get('code')}: {error.get('message', body)}")
return body["data"]
def generate(input_body, model="mai-image-2.7", max_wait=600):
task = checked(session.post(BASE + "/api/generate/submit",
json={"model": model, "input": input_body},
timeout=60))
task_id = task["task_id"]
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
time.sleep(5)
task = checked(session.get(BASE + "/api/generate/status/" + task_id, timeout=60))
if task["status"] == "failed":
raise RuntimeError(task.get("error_message") or "generation failed")
if task["status"] == "finished":
images = [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "image"]
return images[0], task.get("credits_amount")
raise TimeoutError("Still running, check this task later: " + task_id)
url, credits = generate({
"prompt": "A rainy-night cafe with a neon sign reading \"OPEN LATE\"",
"size": "16:9",
"resolution": "2K",
})
print(url, credits)
Um timeout significa "consulte o mesmo ID de tarefa de novo mais tarde". Reenviar iniciaria uma segunda tarefa cobrável.
Todos os modos de entrada da MAI Image 2.7 API
Todos os campos ficam dentro de input. O ID de modelo e um callback_url opcional ficam no nível superior.
Text-to-image
Só prompt é obrigatório. Sem size, a saída é 1:1; sem resolution, é 1K (1024x1024 para um quadrado).
{
"model": "mai-image-2.7",
"input": {
"prompt": "A university campus poster at dusk with the title \"Open Day 2026\", photorealistic, cinematic light",
"size": "16:9",
"resolution": "2K"
}
}
Editar uma imagem
Passe uma URL em image_urls. Precisa ser um array mesmo para uma única imagem.
{
"model": "mai-image-2.7",
"input": {
"prompt": "Change the bicycle to blue and add a small dog next to it",
"image_urls": ["https://example.com/bicycle.png"]
}
}
Sem size, a edição mantém a proporção da primeira imagem de referência em cerca de 1 megapixel. Adicione size quando quiser outra proporção ou um tamanho personalizado.
Combinar de 2 a 5 imagens
Várias URLs são combinadas em uma nova imagem. Cite-as no prompt pela função de cada uma, para que o modelo saiba o que cada imagem fornece.
{
"model": "mai-image-2.7",
"input": {
"prompt": "Place the sneaker from image 1 on the wooden boards from image 2, at the pier from image 3, golden hour",
"image_urls": [
"https://example.com/sneaker.png",
"https://example.com/boards.png",
"https://example.com/pier.png"
],
"size": "16:9"
}
}
As imagens de referência são usadas até cerca de 1 megapixel, então não é preciso enviar arquivos muito maiores do que isso.
Tamanho personalizado
Uma string WIDTHxHEIGHT é usada exatamente como informada.
{
"model": "mai-image-2.7",
"input": {
"prompt": "A wide panoramic banner of a mountain range at sunrise",
"size": "3072x1344"
}
}
Fundo transparente e formato de saída
{
"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"
}
}
output_format também funciona em imagens opacas: envie "jpeg" para arquivos fotográficos menores. O guia de fundo transparente cobre as verificações do canal alfa e o nosso teste medido com um sticker.
Regras de validação dos campos
Valide do seu lado antes de enviar, para que requisições inválidas falhem rápido:
| Campo | Regra |
|---|---|
model | mai-image-2.7 ou mai-image-2.7-flash |
prompt | Obrigatório, de 1 a 32,000 caracteres, não só espaços |
image_urls | Array de 1 a 5 URLs HTTP ou HTTPS públicas, JPEG, PNG ou WebP |
size | 1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16 ou WIDTHxHEIGHT |
| Tamanho personalizado | Os dois lados divisíveis por 16, cada lado com pelo menos 768, largura x altura no máximo 4,194,304 |
resolution | 1K (cerca de 1 MP) ou 2K (cerca de 4 MP, 16:9 é 2720x1536); vale para tamanhos definidos por proporção |
background | opaque ou transparent; transparent exige output_format png ou webp |
output_format | png, jpeg ou webp |
| Campos desconhecidos | Rejeitados; o schema não permite propriedades extras, então remova campos como enable_web_search das requisições do MAI Image 2.6 |
Exemplos: 2048x2048 e 3072x1344 passam; 3000x1400 falha (não são múltiplos de 16); 640x1600 falha (um lado abaixo de 768); 2400x2400 falha (5,760,000 pixels). "background": "transparent" com "output_format": "jpeg" falha porque o JPEG não tem canal alfa.
Erros que vale a pena tratar
code | Significado | O que fazer |
|---|---|---|
| 400 | Parâmetros inválidos | Corrija o corpo; não tente de novo sem alterar |
| 401 | Chave de API ausente ou inválida | Verifique o cabeçalho Authorization: Bearer |
| 402 | Créditos insuficientes | Recarregue e envie de novo |
| 429 | Limite de requisições excedido | Aguarde e tente mais tarde |
| 500, 502, 503 | Erro do servidor, do provedor upstream ou de disponibilidade | Tente de novo com backoff; antes, verifique se um ID de tarefa já foi retornado |
Uma tarefa que chega a failed depois do envio informa o motivo em error_message, por exemplo uma rejeição pela política de conteúdo. Veja os códigos de erro para a lista completa. Se o seu app aceita uploads de usuários como image_urls, fazer uma triagem antes evita tarefas com falha; o guia de moderação de imagens mostra uma forma de fazer isso.
Usar callback em vez de polling
Adicione "callback_url": "https://your-app.example.com/poyo-webhook" no nível superior do corpo. Quando a tarefa termina ou falha, a PoYo envia via POST os dados da tarefa (no mesmo formato do data da resposta de status) para essa URL, assinados com HMAC-SHA256 no cabeçalho X-Webhook-Signature. A documentação de webhooks traz a regra de assinatura. Mantenha um polling lento como fallback para callbacks que nunca chegam.
Como sua primeira cobrança é calculada
A MAI Image 2.7 API cobra tokens: entrada de texto, entrada de imagem (para image_urls) e saída de imagem. Na PoYo, a saída corresponde a cerca de um token a cada 1,024 pixels.
| Modelo | Entrada de texto | Entrada de imagem | Saída de imagem (por 1M de tokens) |
|---|---|---|---|
mai-image-2.7 | 1,000 créditos ($5.00) | 1,600 créditos ($8.00) | 6,800 créditos ($34.00) |
mai-image-2.7-flash | 350 créditos ($1.75) | 500 créditos ($2.50) | 2,000 créditos ($10.00) |
Nosso teste do dia do lançamento (API de produção da PoYo, 19 de novembro de 2026) mostra o que isso significa na prática. A mesma requisição 2K 16:9 do café retornou 2720x1536 nos dois níveis e, nas tarifas atuais, sai por 27.802 créditos (cerca de $0.139) no mai-image-2.7 e 8.1803 créditos (cerca de $0.041) no mai-image-2.7-flash. Estimativa derivada: 2720x1536 são 4,177,920 pixels, cerca de 4,080 tokens de saída, o que explica 27.744 e 8.16 créditos; o pequeno resto em cada caso corresponde a cerca de 58 tokens de prompt. O post de preços tem tabelas de custo para todos os tamanhos.
Perguntas frequentes
A MAI Image 2.7 API é compatível com o SDK da OpenAI?
Não. É uma API de tarefas assíncronas: envie para /api/generate/submit e depois faça polling em /api/generate/status/{task_id} ou receba um callback. Basta usar requests, fetch ou cURL.
Como edito uma imagem com a MAI Image 2.7 API?
Adicione image_urls com uma URL de imagem pública e descreva a alteração em prompt. Com 2 a 5 URLs, as imagens são combinadas.
Posso definir um tamanho exato em pixels na MAI Image 2.7 API?
Sim, envie size como WIDTHxHEIGHT com os dois lados divisíveis por 16, cada um com pelo menos 768, e no máximo 4,194,304 pixels no total.
Quantas imagens uma requisição à MAI Image 2.7 API retorna? Uma. Envie várias tarefas em paralelo para ter variações.
A MAI Image 2.7 API retorna JPEG?
Sim, com "output_format": "jpeg", desde que background seja opaque. PNG é o padrão e WebP também está disponível.