
Este guia da MAI Image 2.7 API leva-o de uma chave de API a uma imagem concluída em cURL e Python e, depois, cobre todos os modos de entrada que o esquema 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-o por mai-image-2.7-flash para o nível mais barato, já que os dois esquemas do MAI Image 2.7 são idênticos exceto no ID.
As regras dos campos vêm da referência da API da PoYo. Para saber o que é o modelo e como se compara, comece pela visão geral da MAI Image 2.7 API.
Passo 1: submeter um pedido à MAI Image 2.7 API com cURL
Crie uma chave no painel da PoYo e exporte-a como POYO_API_KEY. Mantenha-a no seu servidor, não no código do browser.
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"
}
}'
Uma submissão bem-sucedida devolve code: 200 e um objeto data com task_id, status: "not_started" e created_time. Trata-se de uma tarefa em fila, ainda não de uma imagem. Verifique sempre o code no corpo: alguns erros de validação chegam com HTTP 200 e code: 400.
Passo 2: consultar o estado da tarefa
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
O estado 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 indica o valor cobrado em credits_amount. Uma tarefa falhada explica o motivo em error_message.
Passo 3: um ciclo de polling em Python com limite
Este ciclo verifica tanto o estado HTTP como o code do corpo, para em failed e desiste ao fim de 10 minutos sem voltar a submeter. No nosso teste de lançamento de 19 de novembro de 2026, uma imagem 2K em 16:9 demorou cerca de 66 segundos no MAI Image 2.7 e cerca de 42 segundos no Flash, por isso um intervalo de polling de 5 segundos é mais do 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 «voltar a consultar o mesmo ID de tarefa mais tarde». Submeter novamente iniciaria uma segunda tarefa faturá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 um URL em image_urls. Tem de 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 a cerca de 1 megapíxel. Acrescente size se quiser outra proporção ou um tamanho personalizado.
Combinar 2 a 5 imagens
Vários URLs são combinados numa nova imagem. Refira-os no prompt pela sua função, 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 megapíxel, por isso não é preciso enviar ficheiros muito maiores do que isso.
Tamanho personalizado
Uma string WIDTHxHEIGHT é usada exatamente como indicada.
{
"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 ficheiros fotográficos mais leves. O guia de fundo transparente aborda 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 submeter, para que os pedidos inválidos falhem logo:
| Campo | Regra |
|---|---|
model | mai-image-2.7 ou mai-image-2.7-flash |
prompt | Obrigatório, de 1 a 32,000 caracteres, não apenas espaços |
image_urls | Array de 1 a 5 URLs HTTP ou HTTPS públicos, JPEG, PNG ou WebP |
size | 1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16 ou WIDTHxHEIGHT |
| Tamanho personalizado | Ambos os 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); aplica-se a 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 esquema não permite propriedades adicionais, por isso remova campos como enable_web_search dos pedidos do MAI Image 2.6 |
Exemplos: 2048x2048 e 3072x1344 são válidos; 3000x1400 falha (não são múltiplos de 16); 640x1600 falha (um lado abaixo de 768); 2400x2400 falha (5,760,000 píxeis). "background": "transparent" com "output_format": "jpeg" falha porque o JPEG não tem canal alfa.
Erros a tratar
code | Significado | O que fazer |
|---|---|---|
| 400 | Parâmetros inválidos | Corrigir o corpo; não repetir sem alterações |
| 401 | Chave de API em falta ou inválida | Verificar o cabeçalho Authorization: Bearer |
| 402 | Créditos insuficientes | Carregar saldo e voltar a submeter |
| 429 | Limite de pedidos excedido | Aguardar e tentar novamente mais tarde |
| 500, 502, 503 | Erro do servidor, do fornecedor a montante ou de disponibilidade | Repetir com backoff; verificar primeiro se já foi devolvido um ID de tarefa |
Uma tarefa que chega a failed após a submissão indica o motivo em error_message, por exemplo uma rejeição pela política de conteúdo. Consulte os códigos de erro para a lista completa. Se a sua aplicação aceita imagens enviadas pelos utilizadores como image_urls, analisá-las primeiro evita tarefas falhadas; o guia de moderação de imagens mostra uma forma de o fazer.
Usar um callback em vez de polling
Acrescente "callback_url": "https://your-app.example.com/poyo-webhook" no nível superior do corpo. Quando a tarefa termina ou falha, a PoYo envia por POST os dados da tarefa (com a mesma estrutura do data da resposta de estado) para esse URL, assinados com HMAC-SHA256 no cabeçalho X-Webhook-Signature. A documentação de webhooks indica a regra de assinatura. Mantenha um polling lento como alternativa para callbacks que nunca chegam.
Como é calculada a sua primeira fatura
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 por cada 1,024 píxeis.
| 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) |
O nosso teste do dia do lançamento (API de produção da PoYo, 19 de novembro de 2026) mostra o que isto significa na prática. O mesmo pedido 2K 16:9 do café devolveu 2720x1536 em ambos os níveis e, às tarifas atuais, fica em 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 píxeis, 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 artigo de preços tem tabelas de custos 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: submeta para /api/generate/submit e depois consulte /api/generate/status/{task_id} ou receba um callback. Basta requests, fetch ou cURL.
Como edito uma imagem com a MAI Image 2.7 API?
Acrescente image_urls com um URL de imagem público e descreva a alteração em prompt. Com 2 a 5 URLs, as imagens são combinadas.
Posso definir um tamanho exato em píxeis na MAI Image 2.7 API?
Sim, envie size como WIDTHxHEIGHT com ambos os lados divisíveis por 16, cada um com pelo menos 768, e no máximo 4,194,304 píxeis no total.
Quantas imagens devolve um pedido à MAI Image 2.7 API? Uma. Submeta várias tarefas em paralelo para obter variações.
A MAI Image 2.7 API devolve JPEG?
Sim, com "output_format": "jpeg", desde que background seja opaque. O PNG é o formato predefinido e o WebP também está disponível.