API de MAI Image 2.6: generar, editar y consultar tareas

La primera decisión al integrar MAI Image 2.6 es qué contrato de servicio usa tu aplicación. Microsoft documenta la generación y la edición mediante Foundry. En reAPI, ambas operaciones usan el endpoint de generación de imágenes: añade URL de referencia para editar y consulta después el ID de tarea recibido. El nombre del modelo es parecido entre servicios, pero la autenticación, los cuerpos de solicitud y las respuestas no son intercambiables.^[1]

Esta guía sigue el contrato de reAPI para mai-image-2.6. Empieza con una solicitud solo de texto antes de añadir referencias o encuadre automático. Así tendrás una integración pequeña que revisar si una solicitud falla. Mantén la referencia completa de parámetros junto a tu implementación; el playground de MAI Image 2.6 ofrece los mismos controles y las estimaciones actuales.^[2]

Puntos esenciales

• Envía mai-image-2.6 con un prompt no vacío al endpoint de imágenes. Una solicitud produce una imagen.^[2]
• Usa una relación con 1K o 2K, o un par válido de dimensiones en píxeles. Este endpoint no acepta 4K.^[2]
• Proporciona hasta cinco URL públicas de imágenes ordenadas para editar con referencias. El modelo elige entonces las dimensiones de salida.^[2]
• Guarda el ID recibido y consúltalo hasta completed o failed. El envío por sí solo no contiene la imagen terminada.^[2]
• Trata el importe mostrado como una estimación. Al completar se ajusta la reserva; puedes consultar la facturación precisa con ?include=billing.^[2]

Envía la primera solicitud de MAI Image 2.6

Crea una clave de reAPI y guárdala en el entorno de tu servidor como REAPI_API_KEY. La solicitud necesita un modelo y un prompt no vacío. Este ejemplo pide una imagen cuadrada con dimensiones explícitas para facilitar la comprobación del lienzo previsto. Es una solicitud de ejemplo, sin prometer que cada objeto generado siga perfectamente la descripción.

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer $REAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mai-image-2.6",
    "prompt": "A matte ivory ceramic teapot on a pale blue table, soft daylight, product photography.",
    "width": 1024,
    "height": 1024,
    "n": 1
  }'

El ID de la API contiene un punto antes del 6. La URL de la página usa /models/mai-image-2-6; copiar ese slug con guiones en la solicitud produce otra cadena. Guarda el id de tarea en cuanto el envío tenga éxito. Lo usarás para recuperar el resultado, identificar un fallo o retomar el proceso tras una desconexión del cliente. Una solicitud produce una imagen; aumentar n no crea un lote admitido.^[2]

Mantén la clave fuera del código del navegador. El frontend puede enviar la descripción al backend, que añade el token Bearer y envía la solicitud. Devuelve al frontend el identificador de trabajo de tu aplicación o el ID de tarea según tu diseño de acceso. Evita incluir la clave en parámetros de URL, capturas de pantalla o informes de error copiados.

Consulta la tarea que ya enviaste

Un envío correcto es una confirmación, no la imagen terminada. Consulta GET /api/v1/tasks/:id hasta que el estado sea completed o failed. Una tarea completada expone la imagen en output.image_urls; una fallida expone error. El valor anterior usage.credits se redondea a créditos enteros. Para una contabilidad precisa, usa ?include=billing y revisa billing.credits_exact y billing.cost_usd, además de los datos de importes cobrados y faltantes cuando existan. Consultar la tarea original no envía otra generación.^[2]

const taskId = submittedTask.id;
const headers = { Authorization: `Bearer ${process.env.REAPI_API_KEY}` };
const deadline = Date.now() + 5 * 60 * 1000;

while (Date.now() < deadline) {
  const response = await fetch(
    `https://reapi.ai/api/v1/tasks/${encodeURIComponent(taskId)}`,
    { headers },
  );
  if (!response.ok) {
    throw new Error(`Task lookup failed: HTTP ${response.status}; task ${taskId}`);
  }
  const task = await response.json();
  if (task.status === 'completed') {
    console.log(task.output.image_urls, task.usage);
    break;
  }
  if (task.status === 'failed') {
    throw new Error(JSON.stringify({ taskId, error: task.error }));
  }
  await new Promise((resolve) => setTimeout(resolve, 3000));
}

Aquí submittedTask es la respuesta analizada de un envío correcto. El plazo de cinco minutos es un ejemplo de aplicación, no una garantía de latencia. Si vence, conserva taskId e indica que la aplicación dejó de esperar. No marques la generación como fallida salvo que la tarea informe de un fallo. En un cliente de producción, devuelve un estado de tiempo de espera agotado distinto tras el bucle y ofrece actualizar el estado de esa misma tarea.

Un error de red después del envío genera otra ambigüedad: el servidor puede haber aceptado la solicitud antes de que se cortara la conexión. Repetir automáticamente cada POST puede crear tareas facturables adicionales. Separa el envío de las consultas y conserva cualquier ID recibido antes de realizar acciones opcionales de interfaz.

Elige un tamaño que acepte el endpoint

Para una solicitud de MAI Image 2.6 solo de texto, usa una relación con un nivel de resolución o dimensiones explícitas. El endpoint acepta 1K y 2K, no 4K. Cada lado explícito debe medir al menos 768 píxeles y el área total no puede superar 2.359.296 píxeles. Las relaciones usan enteros positivos y van de 1:4 a 4:1.^[2]

El ancho y el alto juntos tienen prioridad sobre las dimensiones en píxeles de size, que a su vez tienen prioridad sobre la relación y la resolución. Usa un único método claro cuando puedas. Por ejemplo, width: 1024, height: 1024 junto con size: "16:9" expresa intenciones contradictorias, aunque la precedencia documentada resuelva la solicitud. Tu formulario puede evitar esa confusión.

Las dimensiones se redondean hacia abajo a múltiplos de 32. Una solicitud de 1000 × 1000 corresponde por tanto a 992 × 992 según esta regla. Si el diseño necesita un tamaño de entrega exacto, solicita múltiplos válidos y revisa las dimensiones del archivo descargado. Trata el recorte o el cambio de tamaño posterior como un paso separado de tu aplicación.^[2]

Pasa de la generación a la edición con referencias

Añade image_urls a la solicitud de MAI Image 2.6 para aportar referencias visuales. El endpoint de reAPI acepta hasta cinco URL HTTP(S) públicas de imágenes. El prompt sigue siendo obligatorio. Mantén el orden y explica qué referencia aporta la escena, el sujeto o el estilo.^[2]

{
  "model": "mai-image-2.6",
  "prompt": "Use the first image as the room and the second as the chair. Replace the chair beside the window. Preserve the floor, window, and camera view.",
  "image_urls": [
    "https://example.com/room.jpg",
    "https://example.com/chair.jpg"
  ],
  "web_grounding": false
}

Sustituye las URL de ejemplo por archivos de imagen accesibles, preferiblemente JPEG o PNG. Una URL que solo funciona tras iniciar sesión no es una referencia adecuada. Comprueba que devuelva los datos de la imagen esperada, en lugar de un visor HTML o una página de acceso caducado.

La edición con referencias sigue otra regla de tamaño: el modelo elige las dimensiones de salida y size, resolution, width y height no las controlan. Añadir referencias a una solicitud que antes era solo de texto cambia más que el contexto visual. También modifica lo que tu aplicación puede prometer sobre el lienzo devuelto.^[2]

No interpretes «mantén la habitación igual» como una garantía de identidad píxel a píxel. Revisa el objeto editado, los bordes cercanos, los reflejos y los elementos que debían conservarse. En un flujo de producto, comprueba por separado logos, etiquetas y proporciones físicas. Son controles de aceptación sugeridos, sin afirmar que esta guía haya medido la precisión del modelo en esas tareas.

Usa el encuadre automático y el contexto web con intención

auto_aspect_ratio: true pide a MAI Image 2.6 que deduzca un encuadre del prompt, igual que size: "auto". Es útil al explorar composiciones y menos adecuado si el siguiente paso exige un lienzo fijo. La elección automática también hace incierto el número de píxeles antes de completar.

web_grounding es un booleano independiente y vale false por defecto. Microsoft describe el contexto web como parte de las entradas creativas del modelo, pero activar el control no convierte cada etiqueta o hecho representado en información fiable. Revisa la información relevante para la pieza final.^[3]

Ninguno de los controles sustituye un prompt claro. Indica primero el sujeto, la composición, los materiales y el cambio previsto. Después activa los ajustes que sirvan a esa descripción. Registrar los valores enviados permite distinguir una revisión del prompt de un cambio de configuración.

Entiende la estimación antes de automatizar reintentos

El precio de MAI Image 2.6 depende de las entradas y los píxeles generados. reAPI reserva un importe estimado al enviar y ajusta el cargo tras completar. El importe final puede ser menor o mayor. Las referencias y las dimensiones elegidas por el modelo impiden tratar la estimación como un precio fijo por imagen.^[2]

Usa la estimación actual de la página del modelo para la solicitud prevista. La guía de precios y Flash explica por qué una imagen cuadrada, una edición con referencias y una imagen panorámica son casos presupuestarios distintos. Este artículo no fija una tarifa en el código de ejemplo.

Las generaciones fallidas se reembolsan según el contrato de tareas. Una imagen completada que no te gusta sigue siendo una generación completada. Presupuesta los intentos creativos repetidos como tareas independientes. Registra los resultados aceptados y el número de intentos necesarios para comparar el coste de una pieza útil, además del precio de un único envío.

Preguntas frecuentes sobre la integración de MAI Image 2.6

¿Qué ID de modelo debo enviar?

Envía mai-image-2.6, con el punto antes del 6. El slug mai-image-2-6 se usa para las URL del sitio y no es el ID de modelo de la solicitud.^[2]

¿Puede una solicitud generar varias imágenes?

No. Este endpoint admite n: 1. Envía solicitudes separadas para más intentos y contabiliza cada tarea por separado.^[2]

¿Puede MAI Image 2.6 crear una imagen 4K mediante este endpoint?

No. Los niveles documentados son 1K y 2K. Las dimensiones explícitas requieren al menos 768 píxeles por lado y un área total de como máximo 2.359.296 píxeles.^[2]

¿Por qué una edición ignora mi ancho y alto?

Las referencias cambian el comportamiento de tamaño. El modelo elige las dimensiones; size, resolution, width y height ya no controlan esa salida. Revisa el archivo devuelto antes de prometer un tamaño de entrega.^[2]

¿Es obligatorio el contexto web?

No. web_grounding vale false por defecto. Actívalo cuando ayude a la descripción y sigue revisando los hechos y las etiquetas de la imagen terminada.^[2][3]

¿Un tiempo de espera agotado al consultar significa que la generación falló?

No. El límite del cliente solo significa que dejó de esperar. Conserva el ID y recupera de nuevo el estado. La generación solo ha fallado cuando la tarea informa de failed.^[2]

Búsquedas de descarga y elección del modelo

Un cliente de API no es un checkpoint de modelo descargable. Esta integración llama a un servicio alojado y no instala pesos. Microsoft documenta despliegues de Foundry para el modelo estándar y Flash; esas instrucciones son independientes del endpoint de reAPI de este artículo.^[1]

El ID mai-image-2.6 selecciona MAI Image 2.6 estándar. No añadas flash ni sustituyas un nombre de despliegue salvo que el servicio documente expresamente ese modelo. Para una primera integración, reúne el ID, el endpoint, el cuerpo de solicitud y el analizador de respuesta en un ejemplo revisado. Añade modelos alternativos solo después de comprobar sus contratos por separado.

Referencias

1. Microsoft Learn. Implementar y usar modelos de imágenes MAI en Microsoft Foundry. Consultado el 9 de octubre de 2026 en learn.microsoft.com/azure/foundry/foundry-models/how-to/use-foundry-models-mai-image.
2. reAPI. Contrato de solicitudes, tamaños, consultas y facturación de MAI Image 2.6. Revisado el 9 de octubre de 2026: reapi.ai/docs/mai-image-2-6.
3. Microsoft AI. MAI-Image-2.6. Consultado el 9 de octubre de 2026 en microsoft.ai/models/mai-image-2-6.