How to Use Microsoft MAI-Image-2.5 Pro: 12 Steps, 100 Min [2026]

Microsoft quietly shipped its strongest image model yet on June 25, 2026, and by August it had climbed to No. 2 on Arena’s Image Edit leaderboard, ahead of Google’s Nano Banana 2. Microsoft AI followed up fast: by September 2026 it had shipped MAI-Image-2.6, which climbed to No. 2 on Arena’s text-to-image leaderboard, a sign Microsoft is now iterating across both the generation and editing sides of Arena rather than just one. MAI-Image-2.5 Pro remains Microsoft’s first-party answer to a crowded field of AI image tools, built for teams that need controllable, consistent edits rather than just pretty text-to-image outputs. If you searched for a Microsoft AI image generator expecting Bing Image Creator or Copilot’s built-in tool, you’re closer than you think: as of July 2026, Microsoft AI confirmed Bing Image Creator now runs 100% in-house, with MAI-Image-2.5 powering it end-to-end, and the same model is the flagship option available directly through Microsoft Foundry (formerly Azure AI Foundry).

This tutorial walks through the entire setup, from creating a Foundry resource to writing your first generation and edit calls, building a small working project, and troubleshooting the errors you’re most likely to hit. By the end, you’ll have a working Python script that generates and edits images through the MAI-Image-2.5 Pro API, plus a clear sense of when this model beats the alternatives and when it doesn’t.

·

Google · Preferred Sources

Don't miss new tech stories on Google

Add Tech Insider once in the Google app and our stories appear in your news suggestions.

Add Now

What Is Microsoft MAI-Image-2.5 Pro?

MAI-Image-2.5 Pro is Microsoft AI’s flagship image generation and editing model, announced alongside the faster MAI-Voice-2-Flash model as part of a July 2026 release wave. It’s the latest step in a fast-moving lineage: Windows Central reported back in May 2025 that Copilot had upgraded to GPT-4o image generation for richer detail and editing support, and by March 2026 The Verge reported Microsoft had already launched a second-generation AI image model, integrating it into both Copilot and Bing Image Creator ahead of this summer’s Foundry-native release. In between, Microsoft Foundry quietly rolled out MAI-Image-2e in April 2026, an efficiency-focused update that ran 22% faster and roughly 4x more efficiently than the original MAI-Image-2, laying the groundwork for the heavier Pro tier that followed. According to Microsoft’s own Azure AI Foundry blog, “MAI-Image-2.5 Pro is our newest high-fidelity image generation model, designed for scenarios where visual accuracy, consistency, and creative control are critical.”

Unlike a chat-app image toy, MAI-Image-2.5 Pro is built as a developer-facing model inside Microsoft Foundry, Microsoft’s unified platform for deploying and calling first-party and partner AI models. That matters for how you’ll use it: instead of typing prompts into a consumer web app, you deploy the model to your own Foundry resource and call it through an API, the same way you’d call GPT Image 2 or Claude through their respective platforms.

Microsoft’s own documentation frames the model’s job in two parts, generation and editing. Per Microsoft Learn, “MAI-Image-2.5-Pro is a text-to-image generation and image-to-image editing model designed to create high-quality, visually rich images from natural language prompts and to perform precise, controllable edits on existing images.” That editing half is the differentiator. Microsoft explicitly benchmarks the model against Arena’s Image Edit leaderboard rather than pure text-to-image rankings, and it’s currently sitting at No. 2, ahead of Nano Banana 2.

Why This Model Matters Right Now

The AI image generator market moved fast through mid-2026. OpenAI’s GPT Image 2 has led the Artificial Analysis Text-to-Image Arena with an Elo score of 1339 since its April 21, 2026 launch. Google answered with Nano Banana 2 (Gemini 3 Pro Image), pitched as capable of 4K-level photorealism. Midjourney pushed out V8.1 in April, then V8.2 as its new default on July 24. Black Forest Labs unveiled FLUX 3 in late July, spanning image, video, and audio, though it remains in limited early access. Meta shipped its first fully in-house model, Muse Image, on July 7. Microsoft itself has been hedging across providers inside Microsoft 365: Copilot added FLUX.2 Flex for image generation in PowerPoint in June 2026, and as of September 2026, Microsoft 365 Copilot release notes show Copilot Cowork can create and modify images using OpenAI’s ChatGPT Images 2.0, alongside its own first-party MAI-Image-2.5 Pro.

Microsoft’s entry stands out for one specific reason: it’s the first Microsoft-built image model to rank near the top of an independent editing benchmark, rather than relying on a licensed DALL-E or partner model under the hood. That’s a meaningful shift for developers already building on Azure or Microsoft Foundry, since it removes a dependency on a third-party API and keeps the entire pipeline, from LLM calls to image generation, inside one billing account and one set of compliance controls. Microsoft AI has also pointed to a concrete efficiency case: in PowerPoint, MAI-Image-2.5 reduces GPU costs by up to 84% compared with running GPT-Image-2 for the same workload, according to Microsoft’s July 2026 statements.

Search interest backs this up. “Microsoft ai image generator” pulls roughly 3,600 monthly searches in the US with low keyword competition, and much of that traffic is still landing on generic Bing Image Creator explainers that don’t mention the new Foundry model at all. If you’re evaluating image APIs for a product, a content pipeline, or an internal tool, this guide gets you past that gap.

Prerequisites

Before you start, get these pieces in place. Skipping any of them is the single biggest source of failed API calls later in this guide.

• An active Microsoft Azure account with billing enabled (a free trial subscription will not have quota for image models)
• Access to Microsoft Foundry (formerly Azure AI Foundry), reachable at ai.azure.com
• Python 3.10 or newer installed locally (3.11 or 3.12 recommended)
• The requests library (version 2.31.0 or newer) or the openai Python SDK (version 1.50.0 or newer), since Foundry model endpoints follow an OpenAI-compatible schema for many models
• A code editor (VS Code 1.90+ is what we used for this tutorial)
• Basic familiarity with REST APIs and JSON
• A payment method attached to your Azure subscription, since MAI-Image-2.5 Pro bills per token, not as a flat monthly fee

Budget at least $10-20 in Azure credit for testing. Between generation and edit calls during this tutorial, you’ll likely spend under $2, but Foundry resources sometimes require a minimum funded balance before they’ll issue an API key.

Step 1: Create or Access a Microsoft Foundry Resource

Go to ai.azure.com and sign in with your Azure account. If you’ve never used Microsoft Foundry before, you’ll be prompted to create a new “Foundry resource” (previously called an “Azure AI Foundry hub”). Choose a subscription, a resource group (create a new one called something like mai-image-tutorial if you don’t have one already), and a region.

Region matters here. MAI-Image-2.5 Pro is not available in every Azure region yet. As of August 2026, East US, West US 3, and Sweden Central have the most consistent availability. If your first region shows the model grayed out in the model catalog, switch regions before troubleshooting anything else.

Step 2: Deploy MAI-Image-2.5 Pro From the Model Catalog

Inside your new Foundry project, click “Model catalog” in the left sidebar. Search for “MAI-Image-2.5”. You should see two entries: MAI-Image-2.5-Pro (the high-fidelity flagship) and a lighter-weight sibling tier for lower-cost workloads; as of September 2026, that sibling slot is filled by MAI-Image-2.6-Flash, which Microsoft pushed into Foundry Public Preview as a faster, cheaper complement to the Pro model. Select the Pro tier for this tutorial since that’s the one benchmarked against Nano Banana 2.

Click “Deploy.” Give the deployment a name you’ll remember, such as mai-image-25-pro-deploy. Leave the default throughput settings unless you already know you need higher rate limits. Deployment typically takes two to five minutes. Once it’s live, Foundry will show you an endpoint URL and give you the option to generate an API key.

Per Microsoft Learn’s own guidance, “After you deploy an MAI image model, use the MAI image generations API to generate images and the MAI image edits API for image-to-image edits.” Note that these are two separate endpoints, not one combined endpoint with a mode flag. Keep both URLs handy.

Step 3: Grab Your API Key and Endpoint

From the deployment details page, copy your endpoint URL and one of the two provided API keys. Store both somewhere safe. Never commit an API key to a public GitHub repo, this is one of the most common ways teams end up with a surprise Azure bill after a scraper bot finds an exposed key.

Set them as environment variables rather than hardcoding them into your script:

export MAI_IMAGE_ENDPOINT="https://your-resource-name.openai.azure.com"
export MAI_IMAGE_API_KEY="your-api-key-here"
export MAI_IMAGE_DEPLOYMENT="mai-image-25-pro-deploy"

On Windows PowerShell, use $env:MAI_IMAGE_ENDPOINT="..." instead. If you’re on a team, put these in a .env file and add that file to .gitignore immediately, before you write a single line of code that uses them.

Step 4: Set Up Your Python Environment

Create a project folder and a virtual environment:

mkdir mai-image-tutorial
cd mai-image-tutorial
python3 -m venv venv
source venv/bin/activate
pip install requests python-dotenv Pillow

We’re using the raw requests library here rather than a heavier SDK, since Foundry’s image endpoints are plain REST and this keeps the example portable to any language. Pillow is only needed so we can quickly preview the generated images locally.

Step 5: Write Your First Text-to-Image Generation Call

Create a file called generate.py:

import os
import base64
import requests
from dotenv import load_dotenv

load_dotenv()

ENDPOINT = os.environ["MAI_IMAGE_ENDPOINT"]
API_KEY = os.environ["MAI_IMAGE_API_KEY"]
DEPLOYMENT = os.environ["MAI_IMAGE_DEPLOYMENT"]

url = f"{ENDPOINT}/openai/deployments/{DEPLOYMENT}/images/generations?api-version=2026-06-01"

headers = {
    "Content-Type": "application/json",
    "api-key": API_KEY,
}

payload = {
    "prompt": "A weathered lighthouse on a rocky Maine coastline at golden hour, "
              "long shadows, photorealistic, shallow depth of field",
    "size": "1536x1024",
    "n": 1,
    "quality": "high",
}

response = requests.post(url, headers=headers, json=payload, timeout=60)
response.raise_for_status()
data = response.json()

image_b64 = data["data"][0]["b64_json"]
with open("lighthouse.png", "wb") as f:
    f.write(base64.b64decode(image_b64))

print("Saved lighthouse.png")

Run it with python generate.py. If everything’s configured correctly, you’ll get a PNG saved locally within a few seconds. The “quality” parameter is worth experimenting with: “high” gives you the fidelity that put this model on the Arena leaderboard, but “standard” is noticeably cheaper for draft iterations.

Step 6: Use the Image Edits API for Controlled Edits

Generation is only half of what makes this model worth using. The edit endpoint is where MAI-Image-2.5 Pro earns its Arena ranking. Create edit.py:

import os
import base64
import requests
from dotenv import load_dotenv

load_dotenv()

ENDPOINT = os.environ["MAI_IMAGE_ENDPOINT"]
API_KEY = os.environ["MAI_IMAGE_API_KEY"]
DEPLOYMENT = os.environ["MAI_IMAGE_DEPLOYMENT"]

url = f"{ENDPOINT}/openai/deployments/{DEPLOYMENT}/images/edits?api-version=2026-06-01"

headers = {"api-key": API_KEY}

with open("lighthouse.png", "rb") as image_file:
    files = {
        "image": ("lighthouse.png", image_file, "image/png"),
    }
    data = {
        "prompt": "Add a small sailboat on the water near the horizon, "
                  "keep the lighthouse and lighting exactly the same",
        "size": "1536x1024",
        "n": "1",
    }
    response = requests.post(url, headers=headers, files=files, data=data, timeout=60)

response.raise_for_status()
result = response.json()

image_b64 = result["data"][0]["b64_json"]
with open("lighthouse_edited.png", "wb") as f:
    f.write(base64.b64decode(image_b64))

print("Saved lighthouse_edited.png")

Notice this call sends the image as multipart form data, not JSON, because you’re uploading a binary file alongside the edit instruction. This is the step where object consistency matters most: Microsoft’s Azure AI Foundry blog specifically claims “the model delivers stronger object consistency, improved alignment with creative intent, and enhanced visual reasoning and world knowledge, making it the ideal choice when quality and fidelity matter more than throughput.” In practice, that means the lighthouse should look identical before and after, only the sailboat gets added.

Step 7: Handle Rate Limits and Retries

Foundry deployments come with a default tokens-per-minute quota, and image models burn through it faster than text models because each output image counts as a large number of image-output tokens. Add basic retry logic before you build anything that calls this in a loop:

import time

def call_with_retry(func, max_retries=5, base_delay=2):
    for attempt in range(max_retries):
        try:
            return func()
        except requests.exceptions.HTTPError as e:
            if e.response.status_code == 429:
                wait = base_delay * (2 ** attempt)
                print(f"Rate limited, waiting {wait}s...")
                time.sleep(wait)
                continue
            raise
    raise RuntimeError("Max retries exceeded")

Wrap your requests.post calls in this helper for any production use. A flat retry with exponential backoff avoids the two most common failure modes: hammering the API immediately after a 429 (which just extends your throttling window) and giving up too early during a brief regional capacity spike.

Step 8: Build a Small Batch Generation Project

Now put it together into something closer to a real workflow: a script that reads a list of prompts from a text file and generates an image for each one, skipping any that already exist locally so you can re-run it safely.

import os
import base64
import requests
from pathlib import Path
from dotenv import load_dotenv

load_dotenv()
ENDPOINT = os.environ["MAI_IMAGE_ENDPOINT"]
API_KEY = os.environ["MAI_IMAGE_API_KEY"]
DEPLOYMENT = os.environ["MAI_IMAGE_DEPLOYMENT"]

URL = f"{ENDPOINT}/openai/deployments/{DEPLOYMENT}/images/generations?api-version=2026-06-01"
HEADERS = {"Content-Type": "application/json", "api-key": API_KEY}

Path("output").mkdir(exist_ok=True)

with open("prompts.txt") as f:
    prompts = [line.strip() for line in f if line.strip()]

for i, prompt in enumerate(prompts):
    out_path = Path("output") / f"image_{i:03d}.png"
    if out_path.exists():
        print(f"Skipping {out_path}, already exists")
        continue

    payload = {"prompt": prompt, "size": "1024x1024", "n": 1, "quality": "high"}
    resp = requests.post(URL, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    image_b64 = resp.json()["data"][0]["b64_json"]
    out_path.write_bytes(base64.b64decode(image_b64))
    print(f"Generated {out_path}")

Create a prompts.txt file with one prompt per line, then run python batch_generate.py. This is the pattern most real projects end up using: product mockups, blog thumbnails, or marketing variations generated overnight in a batch job, then reviewed the next morning.

Step 9: Add Content Safety Filtering

Foundry applies content filtering by default on both the prompt and the output image. If a generation gets blocked, the API returns a 400 error with a content_filter reason rather than an image. Handle this explicitly instead of letting your batch job crash:

try:
    resp = requests.post(URL, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
except requests.exceptions.HTTPError as e:
    if e.response.status_code == 400:
        error_body = e.response.json()
        if "content_filter" in str(error_body).lower():
            print(f"Prompt blocked by content filter: {prompt[:50]}...")
            continue
    raise

For enterprise deployments, Foundry lets admins adjust content filter sensitivity per resource, but the default thresholds are strict enough to catch most edge cases in a batch pipeline. Don’t disable filtering entirely unless you have a specific compliance reason and sign-off from your security team.

Step 10: Compare Output Quality Against Prompt Variations

MAI-Image-2.5 Pro responds noticeably differently to structured prompts versus loose, conversational ones. Test this yourself by generating the same subject three ways: a one-line prompt, a prompt with explicit style and lighting terms, and a prompt with a negative constraint. In our testing, prompts that separated subject, style, and lighting into distinct clauses produced more consistent framing across repeated runs than single-sentence prompts, which matches what Microsoft Learn’s documentation implies about the model’s “enhanced visual reasoning.”

Step 11: Deploy Behind a Simple API Wrapper

If you’re integrating this into a product rather than running one-off scripts, wrap the calls in a minimal FastAPI service so your frontend never sees the Foundry API key directly:

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
import os, base64, requests

app = FastAPI()
ENDPOINT = os.environ["MAI_IMAGE_ENDPOINT"]
API_KEY = os.environ["MAI_IMAGE_API_KEY"]
DEPLOYMENT = os.environ["MAI_IMAGE_DEPLOYMENT"]

class GenerateRequest(BaseModel):
    prompt: str
    size: str = "1024x1024"

@app.post("/generate")
def generate(req: GenerateRequest):
    url = f"{ENDPOINT}/openai/deployments/{DEPLOYMENT}/images/generations?api-version=2026-06-01"
    headers = {"Content-Type": "application/json", "api-key": API_KEY}
    payload = {"prompt": req.prompt, "size": req.size, "n": 1, "quality": "high"}
    resp = requests.post(url, headers=headers, json=payload, timeout=60)
    if resp.status_code != 200:
        raise HTTPException(status_code=resp.status_code, detail=resp.text)
    b64 = resp.json()["data"][0]["b64_json"]
    return {"image_base64": b64}

Run it with uvicorn main:app --reload and your frontend can now call POST /generate without ever touching the Foundry key. Add authentication on this endpoint before exposing it publicly, since every call to it costs you real tokens.

Step 12: Monitor Costs in the Azure Portal

Open Cost Management in the Azure Portal and filter by your Foundry resource group. Set a budget alert at whatever threshold makes sense for your project, $25 is a sane starting point for testing. Image-output tokens are priced far higher than text tokens, so a batch job that generates hundreds of images overnight can burn through budget faster than a text-generation workload of similar API-call volume.

Security and Compliance Considerations

Because MAI-Image-2.5 Pro runs inside Microsoft Foundry rather than a standalone consumer app, it inherits the same identity and access controls as the rest of your Azure environment. That’s a real advantage for regulated teams, but it only helps if you actually configure it. Start by creating a dedicated service principal or managed identity for any production workload that calls the model, rather than reusing a personal Azure account’s credentials. This keeps the API key rotation process independent of any single employee’s access and makes audit logs meaningful when something goes wrong.

Enable Azure Monitor logging on your Foundry resource so every generation and edit call gets a timestamped record, including the prompt text if your compliance policy requires prompt-level auditing. For teams working with user-uploaded images through the edits endpoint, run a quick internal review of your data retention settings, since Foundry resources can be configured to store or discard generated images after the response is returned, and the default behavior varies by region and resource configuration.

If your organization operates under GDPR, HIPAA, or a similar framework, check Microsoft’s current data processing addendum for Foundry models before sending any regulated content through the edits endpoint. Content filtering reduces but doesn’t eliminate the need for this review, since filtering catches policy violations in the prompt or output, not compliance obligations tied to the underlying data you’re uploading. Finally, rotate your API keys on a fixed schedule, quarterly is a reasonable default for most teams, and immediately if a key is ever exposed in a log file, a public repo, or a shared screen during a demo.

Real-World Use Cases for MAI-Image-2.5 Pro

The edit-first design of MAI-Image-2.5 Pro maps onto a handful of workflows better than others. E-commerce teams are an obvious fit: swapping a product’s background, adjusting lighting to match a seasonal campaign, or generating size and color variations from a single hero shot are all edit operations, not fresh generations, and that’s exactly the workload Microsoft benchmarked the model against. Because the edit endpoint preserves object consistency, a shoe photographed once can be placed on ten different backgrounds without the shoe itself drifting in shape or color between calls.

Marketing and content teams get a different benefit: rapid iteration on a single creative concept. Instead of regenerating an entire scene from scratch every time a stakeholder asks for “the same image but with the logo moved” or “the same image but warmer lighting,” the edits API lets you make that specific change while holding everything else steady. That cuts down on the review cycles that usually eat the most time in a creative pipeline, since reviewers are comparing a small, targeted change rather than evaluating an entirely new generation against the original brief.

Internal tooling is a third pattern worth calling out. Teams building admin dashboards, documentation sites, or internal wikis often need placeholder or illustrative imagery that doesn’t require the polish of customer-facing creative. Wiring MAI-Image-2.5 Pro into a CMS or documentation platform through the FastAPI wrapper from Step 11 lets non-technical team members generate and edit supporting images without ever touching the Foundry portal directly, as long as you’ve locked down the wrapper with proper authentication.

MAI-Image-2.5 Pro Pricing and Specs

Spec	MAI-Image-2.5 Pro
Public availability	June 25, 2026, via Microsoft Foundry
Model type	Text-to-image generation + image-to-image editing
Text/image input pricing	$5 per 1M tokens
Image output pricing	$106 per 1M image-output tokens
Arena Image Edit leaderboard rank	No. 2, ahead of Nano Banana 2
Access method	REST API via Foundry deployment (generations + edits endpoints)
Companion model in same release	MAI-Voice-2-Flash (voice, same July 2026 wave)
Primary strength	Object consistency and controllable image-to-image edits

How It Compares to Other 2026 Image Models

No single model wins every job. Here’s how MAI-Image-2.5 Pro stacks up against the models it’s most often compared to in mid-2026 coverage.

Model	Maker	Launched	Strongest at	Access
MAI-Image-2.5 Pro	Microsoft	June 25, 2026	Controllable image edits, object consistency	Microsoft Foundry API
GPT Image 2	OpenAI	April 21, 2026	General production, leads Artificial Analysis Arena at Elo 1339	ChatGPT, OpenAI API
Nano Banana 2 (Gemini 3 Pro Image)	Google	2026	4K photorealism	Gemini app, Google AI API
Midjourney V8.2	Midjourney	July 24, 2026	Artistic, aesthetic-driven work	Discord, web app
Muse Image	Meta	July 7, 2026	Free, in-house, no third-party model underneath	Meta AI apps
FLUX 3	Black Forest Labs	Late July 2026 (limited access)	Multimodal image, video, audio	Limited early access

If your job is a one-off creative image, GPT Image 2 or Midjourney V8.2 will likely get you there faster with less setup. If you’re building a product that needs repeatable, controllable edits inside an existing Azure or Microsoft Foundry pipeline, MAI-Image-2.5 Pro’s edit-focused benchmark position and first-party integration make it worth the extra setup steps above.

Common Pitfalls

• Deploying in a region without model availability. The model catalog will let you attempt a deployment in some regions where MAI-Image-2.5 Pro isn’t actually provisioned yet, and you’ll get a cryptic 404 on your first API call. Check East US, West US 3, or Sweden Central first.
• Confusing the generations and edits endpoints. Sending an edit request (multipart form with an image file) to the /generations endpoint, or vice versa, returns a 400 with a schema mismatch error that doesn’t clearly say which endpoint you meant to hit.
• Forgetting that image-output tokens are priced separately and much higher than input tokens. A batch job of a few hundred images can cost noticeably more than expected if you don’t check the $106 per 1M image-output token rate before running it.
• Not handling the content filter response as a distinct error type. A blocked prompt returns a 400, identical in status code to a malformed request, so your error handling needs to actually inspect the response body, not just the status code.
• Hardcoding API keys into scripts that get committed to git. Always use environment variables or a secrets manager, never a literal string in your source file.
• Assuming the API is fully OpenAI SDK compatible out of the box. Some Foundry image endpoints require the raw REST calls shown in this guide rather than the standard openai Python client’s image methods, depending on your API version.
• Ignoring rate limits until a batch job fails halfway through. Always build in retry-with-backoff logic before running anything beyond a handful of test calls.

Troubleshooting

• Error: 401 Unauthorized. Your API key is wrong, expired, or you copied a key from a different deployment. Regenerate the key from the Foundry portal and update your environment variable.
• Error: 404 Not Found on the generations endpoint. Double-check your deployment name matches exactly what you set in Foundry, and confirm the model is actually deployed (not just visible in the catalog) in your target region.
• Error: 429 Too Many Requests. You’ve hit your tokens-per-minute quota. Implement the retry-with-backoff pattern from Step 7, or request a quota increase from the Azure Portal.
• Images come back blank or corrupted when saved locally. You likely forgot to base64-decode the b64_json field before writing bytes to disk. Check your base64.b64decode() call is wrapping the correct field.
• Edit requests ignore part of the instruction. Break complex multi-part edit instructions into separate sequential edit calls rather than one long compound prompt. The model handles single, clear edits more reliably than stacked instructions.
• Generated images don’t match the requested aspect ratio. Confirm the size parameter uses a supported value; unsupported dimensions silently fall back to a default rather than erroring.
• Billing shows charges higher than expected. Check whether you’re calling with "quality": "high" across an entire batch job. Switch to "standard" quality for draft iterations and reserve high quality for final outputs.
• Deployment stuck in “Updating” state for more than 15 minutes. This usually resolves on its own within 20-30 minutes during peak deployment windows. If it doesn’t, delete and recreate the deployment rather than waiting indefinitely.
• Content filter blocks a prompt that seems completely benign. Filters sometimes trigger on ambiguous phrasing (certain brand names, real public figures, or specific combinations of words). Rephrase the prompt more literally and specifically.

Advanced Tips

Once the basic pipeline works, a few adjustments make a meaningful difference in output quality and cost control. First, cache generated images by a hash of the prompt plus parameters, so re-running a batch script during development doesn’t burn tokens regenerating identical images. Second, for edit workflows, keep a version history of each edit step rather than overwriting the source file, since the model’s object-consistency strength is easiest to verify by diffing sequential edits against the original. Third, if you’re generating images for a specific brand or product line, build a short style-guide prefix (2-3 sentences describing lighting, color grading, and composition rules) and prepend it to every prompt programmatically, rather than trusting each individual prompt to carry that context. This produced noticeably more consistent output sets across our batch tests than varying the style language per prompt.

Finally, if your team is also evaluating Nano Banana 2 or GPT Image 2 for the same use case, run identical prompts through all three APIs and log the outputs side by side before committing to one provider. Image model quality differences are often use-case specific, a model that wins on portrait editing may lag on product photography, and the only reliable way to know is testing against your actual content, not published Arena scores alone.

Complete Working Project

Here’s the full project structure you should have after following this tutorial:

mai-image-tutorial/
├── venv/
├── .env                  # MAI_IMAGE_ENDPOINT, MAI_IMAGE_API_KEY, MAI_IMAGE_DEPLOYMENT
├── .gitignore            # includes .env and output/
├── generate.py           # single text-to-image call
├── edit.py               # single image-to-image edit call
├── batch_generate.py     # batch generation with skip-if-exists logic
├── main.py               # FastAPI wrapper for product integration
├── prompts.txt           # one prompt per line for batch jobs
└── output/                # generated images land here

This structure covers the three real usage patterns for MAI-Image-2.5 Pro: one-off generation for testing, batch generation for content pipelines, and an API wrapper for product integration. From here, you can layer in a database to track generated image metadata, a queue system like Celery for larger batch jobs, or a frontend that calls your FastAPI wrapper directly.

Prompt Engineering Tips for Editing Workflows

Editing prompts behave differently from generation prompts, and treating them the same is a common reason results disappoint. A generation prompt describes a scene from nothing, so vague language gets filled in by the model’s own defaults. An edit prompt is instructing a change against a fixed reference, so vague language creates ambiguity about what should and shouldn’t move. “Make it look better” is a bad edit prompt because the model has no way to know which attributes you consider better. “Increase the warmth of the lighting by roughly 15%, keep composition and subject position unchanged” gives the model a specific, bounded instruction it can act on reliably.

Anchor every edit prompt with two things: what should change, and what must stay exactly the same. Our testing found that explicitly naming the elements to preserve, like “keep the lighthouse and lighting exactly the same” in the earlier example, reduced unwanted drift in unrelated parts of the image far more consistently than simply describing the desired addition alone. This lines up with Microsoft’s stated design goal around object consistency: the model is built to hold a reference steady when told to, but it still needs to be told.

For multi-step edits, chain calls rather than compounding instructions into a single prompt. If you need to add a sailboat, change the sky color, and remove a dock post, running three sequential edit calls, each against the previous output, produced more predictable results in testing than asking for all three changes in one prompt. Yes, this costs more in image-output tokens since you’re generating three images instead of one, but the reliability gain is usually worth the extra spend for production content where a wrong result means a re-do anyway.

Sample Output

A successful generation call returns a JSON payload shaped like this:

{
  "created": 1787356800,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
      "revised_prompt": "A weathered lighthouse on a rocky Maine coastline
                          at golden hour, long shadows, photorealistic,
                          shallow depth of field, 4k detail"
    }
  ],
  "model": "mai-image-2.5-pro"
}

Note the revised_prompt field: like several other current-generation image models, MAI-Image-2.5 Pro internally expands your prompt before generation. If your output looks different from what you expected, check this field first, it often explains exactly what the model actually generated from.

When to Choose a Different Model

MAI-Image-2.5 Pro isn’t the right fit for every project. If you need the absolute highest text-to-image Arena score for pure creative generation, GPT Image 2’s Elo 1339 lead is hard to beat as of mid-2026. If your team already lives in the Google Workspace and Gemini ecosystem, Nano Banana 2’s 4K photorealism and tighter Gemini integration may save you an extra vendor relationship. If you need something completely free with no per-token billing complexity, Meta’s Muse Image is worth testing first. MAI-Image-2.5 Pro earns its place specifically when you’re already on Azure or Microsoft Foundry, and when image editing consistency matters more than raw generation throughput.

Frequently Asked Questions

Is MAI-Image-2.5 Pro free to use?

No. It bills per token through Microsoft Foundry: as of July 2026, while the model is still in public preview, Microsoft AI lists pricing at $5 per 1M text-input tokens, $8 per 1M image-input tokens, and $106 per 1M image-output tokens. If that output-token rate feels steep for lower-stakes work, Microsoft Foundry’s newer MAI-Image-2.6-Flash tier, in Public Preview since September 2026, starts image-output pricing at just $19 per 1M tokens, a cheaper option worth testing for draft or high-volume batches. There’s no separate paid consumer app for this specific model, and as of July 2026 Microsoft’s own documentation confirms the image-generator capability is available to Copilot Chat users with no metered usage, so casual use through Bing Image Creator and Copilot’s built-in image tools remains free.

Do I need an Azure subscription to use it?

Yes. MAI-Image-2.5 Pro is only accessible through Microsoft Foundry, which requires an active Azure subscription with billing enabled. There’s currently no standalone consumer web app for this model.

How does MAI-Image-2.5 Pro compare to Nano Banana 2?

On Arena’s Image Edit leaderboard, MAI-Image-2.5 Pro ranks No. 2, ahead of Nano Banana 2. Nano Banana 2 (Gemini 3 Pro Image) is generally considered stronger for pure 4K photorealistic generation, while MAI-Image-2.5 Pro is positioned specifically around controllable, consistent editing.

Can I use MAI-Image-2.5 Pro without writing code?

Microsoft Foundry includes a playground interface at ai.azure.com where you can test prompts against the model without writing a script. For anything beyond quick testing, you’ll need the API integration covered in this tutorial.

What image resolutions does it support?

Standard sizes like 1024×1024 and 1536×1024 are broadly supported. Always check the current Microsoft Learn documentation for the exact list of supported dimensions before hardcoding a size value, since supported resolutions can change between API versions.

Is there a rate limit I should plan around?

Yes, Foundry deployments have a default tokens-per-minute quota tied to your subscription tier. Image models consume this quota faster than text models because of high image-output token costs. Build retry-with-backoff logic (Step 7 above) into any script that makes more than a handful of calls.

Can MAI-Image-2.5 Pro edit images it didn’t generate?

Yes. The image edits API accepts any uploaded image file, not just images the model itself generated. This makes it usable for editing existing product photos, marketing assets, or user-uploaded content, subject to Foundry’s content filtering rules.

Is MAI-Image-2.5 Pro the same model behind Bing Image Creator?

As of July 2026, yes. Bing Image Creator and Copilot’s consumer image tools historically used a mix of Microsoft and partner models, but Microsoft AI has confirmed Bing Image Creator is now 100% in-house by default, with MAI-Image-2.5 powering it end-to-end. That said, the Foundry API version covered in this tutorial gives you direct, programmatic control that the consumer app doesn’t expose, so don’t assume identical feature parity between the two even though the underlying model is now shared.