
Esta guía de la MAI Image 2.7 API te lleva de una clave de API a una imagen terminada con cURL y Python, y después cubre todos los modos de entrada que acepta el esquema de PoYo: text-to-image, edición de una sola imagen, composición de varias imágenes, tamaños personalizados, salida 2K y PNG o WebP transparente. Todos los cuerpos de abajo usan el ID de modelo mai-image-2.7; cámbialo por mai-image-2.7-flash para el nivel más barato, ya que los dos esquemas de MAI Image 2.7 son idénticos salvo por el ID.
Las reglas de los campos proceden de la referencia de la API de PoYo. Para saber qué es el modelo y cómo se compara, empieza por la introducción a la MAI Image 2.7 API.
Paso 1: enviar una solicitud a la MAI Image 2.7 API con cURL
Crea una clave en el panel de PoYo y expórtala como POYO_API_KEY. Guárdala en tu servidor, no en el código del 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"
}
}'
Un envío correcto devuelve code: 200 y un objeto data con task_id, status: "not_started" y created_time. Es una tarea en cola, todavía no una imagen. Comprueba code en el cuerpo siempre: algunos errores de validación llegan con HTTP 200 y code: 400.
Paso 2: consultar el estado de la tarea
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
El estado pasa por not_started, running y después finished o failed. Una tarea terminada incluye la imagen en data.files como un objeto con file_url y file_type: "image", e informa del cobro en credits_amount. Una tarea fallida explica el motivo en error_message.
Paso 3: un bucle de polling en Python con límite
Este bucle comprueba tanto el estado HTTP como el code del cuerpo, se detiene en failed y se rinde a los 10 minutos sin volver a enviar. En nuestra prueba de lanzamiento del 19 de noviembre de 2026, una imagen 2K en 16:9 tardó unos 66 segundos en MAI Image 2.7 y unos 42 segundos en Flash, así que un intervalo de polling de 5 segundos es más 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)
Un timeout significa «vuelve a consultar el mismo ID de tarea más tarde». Volver a enviar iniciaría una segunda tarea facturable.
Todos los modos de entrada de la MAI Image 2.7 API
Todos los campos van dentro de input. El ID de modelo y un callback_url opcional van en el nivel superior.
Text-to-image
Solo prompt es obligatorio. Sin size, la salida es 1:1; sin resolution, es 1K (1024x1024 para un cuadrado).
{
"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 una imagen
Pasa una URL en image_urls. Tiene que ser un array incluso para una sola imagen.
{
"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"]
}
}
Sin size, la edición mantiene la relación de aspecto de la primera imagen de referencia a aproximadamente 1 megapíxel. Añade size si quieres otra relación o un tamaño personalizado.
Combinar de 2 a 5 imágenes
Varias URL se combinan en una imagen nueva. Menciónalas en el prompt por su función para que el modelo sepa qué aporta cada imagen.
{
"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"
}
}
Las imágenes de referencia se usan hasta aproximadamente 1 megapíxel, así que no hace falta enviar archivos mucho más grandes.
Tamaño personalizado
Una cadena WIDTHxHEIGHT se usa exactamente como se indica.
{
"model": "mai-image-2.7",
"input": {
"prompt": "A wide panoramic banner of a mountain range at sunrise",
"size": "3072x1344"
}
}
Fondo transparente y formato de salida
{
"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 también funciona en imágenes opacas: envía "jpeg" para archivos fotográficos más ligeros. La guía de fondo transparente cubre las comprobaciones del canal alfa y nuestra prueba medida con un sticker.
Reglas de validación de campos
Valida en tu lado antes de enviar para que las solicitudes incorrectas fallen rápido:
| Campo | Regla |
|---|---|
model | mai-image-2.7 o mai-image-2.7-flash |
prompt | Obligatorio, de 1 a 32,000 caracteres, no solo espacios |
image_urls | Array de 1 a 5 URL HTTP o HTTPS públicas, JPEG, PNG o WebP |
size | 1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16 o WIDTHxHEIGHT |
| Tamaño personalizado | Ambos lados divisibles por 16, cada lado de al menos 768, ancho x alto como máximo 4,194,304 |
resolution | 1K (unos 1 MP) o 2K (unos 4 MP, 16:9 es 2720x1536); se aplica a los tamaños por relación de aspecto |
background | opaque o transparent; transparent requiere output_format png o webp |
output_format | png, jpeg o webp |
| Campos desconocidos | Rechazados; el esquema no admite propiedades adicionales, así que elimina campos como enable_web_search de las solicitudes de MAI Image 2.6 |
Ejemplos: 2048x2048 y 3072x1344 son válidos; 3000x1400 falla (no son múltiplos de 16); 640x1600 falla (un lado por debajo de 768); 2400x2400 falla (5,760,000 píxeles). "background": "transparent" con "output_format": "jpeg" falla porque JPEG no tiene canal alfa.
Errores que conviene gestionar
code | Significado | Qué hacer |
|---|---|---|
| 400 | Parámetros no válidos | Corrige el cuerpo; no reintentes sin cambios |
| 401 | Clave de API ausente o no válida | Revisa la cabecera Authorization: Bearer |
| 402 | Créditos insuficientes | Recarga y vuelve a enviar |
| 429 | Límite de frecuencia superado | Espera y reintenta más tarde |
| 500, 502, 503 | Error del servidor, del proveedor o de disponibilidad | Reintenta con backoff; comprueba antes si ya se devolvió un ID de tarea |
Una tarea que llega a failed después del envío indica el motivo en error_message, por ejemplo un rechazo por la política de contenido. Consulta los códigos de error para ver la lista completa. Si tu aplicación acepta imágenes subidas por usuarios como image_urls, revisarlas antes evita tareas fallidas; la guía de moderación de imágenes muestra una forma de hacerlo.
Usar un callback en lugar de polling
Añade "callback_url": "https://your-app.example.com/poyo-webhook" en el nivel superior del cuerpo. Cuando la tarea termina o falla, PoYo envía por POST los datos de la tarea (con la misma forma que el data de la respuesta de estado) a esa URL, firmados con HMAC-SHA256 en la cabecera X-Webhook-Signature. La documentación de webhooks explica la regla de firma. Mantén un polling lento de respaldo para los callbacks que nunca llegan.
Cómo se calcula tu primera factura
La MAI Image 2.7 API cobra tokens: entrada de texto, entrada de imagen (para image_urls) y salida de imagen. En PoYo, la salida equivale a aproximadamente un token por cada 1,024 píxeles.
| Modelo | Entrada de texto | Entrada de imagen | Salida de imagen (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) |
Nuestra prueba del día del lanzamiento (API de producción de PoYo, 19 de noviembre de 2026) muestra lo que eso significa en la práctica. La misma solicitud 2K en 16:9 de la cafetería devolvió 2720x1536 en ambos niveles y, a las tarifas actuales, sale por 27.802 créditos (unos $0.139) en mai-image-2.7 y 8.1803 créditos (unos $0.041) en mai-image-2.7-flash. Estimación derivada: 2720x1536 son 4,177,920 píxeles, unos 4,080 tokens de salida, lo que explica 27.744 y 8.16 créditos; el pequeño resto en cada caso corresponde a unos 58 tokens de prompt. El artículo de precios tiene tablas de coste para cada tamaño.
Preguntas frecuentes
¿La MAI Image 2.7 API es compatible con el SDK de OpenAI?
No. Es una API de tareas asíncronas: envía a /api/generate/submit y después consulta /api/generate/status/{task_id} o recibe un callback. Basta con requests, fetch o cURL.
¿Cómo edito una imagen con la MAI Image 2.7 API?
Añade image_urls con una URL de imagen pública y describe el cambio en prompt. Con 2 a 5 URL, las imágenes se combinan.
¿Puedo fijar un tamaño exacto en píxeles en la MAI Image 2.7 API?
Sí, envía size como WIDTHxHEIGHT con ambos lados divisibles por 16, cada uno de al menos 768, y como máximo 4,194,304 píxeles en total.
¿Cuántas imágenes devuelve una solicitud a la MAI Image 2.7 API? Una. Envía varias tareas en paralelo para obtener variaciones.
¿La MAI Image 2.7 API devuelve JPEG?
Sí, con "output_format": "jpeg", siempre que background sea opaque. PNG es el formato por defecto y WebP también está disponible.