MAI Image Models: Microsoft's Own Text-to-Image Family in Foundry

Why a second image family exists

It is easy to assume that image generation in Foundry means one provider and one API. It does not. Foundry Models is a catalogue, and alongside the OpenAI-provided GPT-Image series sits a family built by Microsoft AI itself: the MAI image models. They deliver text-to-image generation, and several of them also perform image-to-image edits. They are sold by Azure and reached through the same enterprise-grade Foundry surface.

Understanding that there are two families — with different endpoints, different parameters, and different limits — is the point of this slice. A learner who knows only one of them will write code that fails against the other for reasons that look like authentication bugs.

The line-up and what separates the members

Every current MAI image model is in preview, which is the first fact to carry into any planning conversation.

MAI-Image-2 is the text-to-image baseline: a diffusion-based generator that progressively refines an image so the result aligns closely with the input text, tuned for diverse and coherent output across creative and design scenarios.

MAI-Image-2e produces the same quality of generation but runs up to 22% faster and four times more efficiently than MAI-Image-2. It is the volume choice — product imagery at scale, marketing variations, branded assets, anywhere cost per image is the deciding factor.

MAI-Image-2.5, MAI-Image-2.5-Flash, and MAI-Image-2.5-Pro add image-to-image editing on top of generation. The 2.5 model is characterised by precise, surgical edits with consistency across iterations. Flash is the balanced generation-and-editing option. Pro is aimed at the hardest compositions, with object consistency across dense scenes, character consistency across poses and lighting, material and physical-property accuracy, and spatial reasoning that keeps scale, perspective, and occlusion credible.

The 2.5 family also claims two capabilities worth knowing by name because they map onto real product requirements: high-fidelity portraits with accurate facial structure and lighting, and accurate text rendering inside generated images — labels, posters, packaging, signage. Text inside generated imagery has historically been a weak point for diffusion models, so a model that advertises it is a meaningful selection criterion for anyone generating marketing assets.

Two endpoints, one resource

After deployment you work against Microsoft-managed endpoints that are distinct from the Azure OpenAI image routes. Generation goes to a /mai/v1/images/generations path on your services endpoint and returns a PNG. Editing goes to /mai/v1/images/edits, accepts a JPEG or PNG, and also returns a PNG.

The request shapes differ from each other in a way that catches people out. Generation takes a JSON body. Editing does not — an edit request carries the source image as multipart form data, so the content type, the client code, and the way you attach the file all change. Both APIs return the result in a base64 field that you decode and write to disk yourself.

Sizing rules with real arithmetic

MAI generation does not offer a menu of preset sizes. You pass explicit width and height in pixels, and three rules govern them.

Each dimension must be at least 768 pixels. The product of width and height must not exceed 1,048,576 — the same pixel count as a 1024x1024 square. And the output format is always PNG regardless of what you asked for.

The consequence is a budget rather than a list. Either dimension may exceed 1024 as long as the total pixel count stays inside the limit, so a wider image must be a shorter one. A 400 Bad Request on this API is nearly always one of those two rules being broken, and knowing that turns a mystifying error into a five-second fix.

The prompt itself has generous headroom — up to 32,000 tokens of context — which matters for the long, heavily specified prompts that branding work tends to produce.

Deployment, auth, and quota realities

MAI image models deploy as global standard deployments in a specific set of regions, and deploying them requires the Cognitive Services Contributor role on the Foundry resource. You can do it in the portal or with a single Azure CLI deployment command.

Authentication accepts either a Microsoft Entra ID bearer token scoped to the Cognitive Services audience or an API key header. Prefer the token: it removes a secret from your configuration and is the pattern the rest of the platform is moving toward.

Rate limits are expressed in requests per minute and organised into tiers, and the free tier is zero requests per minute for every MAI image model. That is not a typo and it is not a soft limit — a free-tier subscription cannot call these models at all.

Common mistakes

Assuming one image API covers every model in the catalogue, and pointing OpenAI-shaped client code at a MAI endpoint.

Sending an edit request as JSON. Edits are multipart.

Treating preview status as a formality when planning a production launch.

Picking a width and height that each look reasonable but multiply past the pixel budget.

And expecting the free tier to be enough for a proof of concept.