Microsoft AI: MAI-Image-2.5 Pro
Microsoft AI MAI-Image-2.5 Pro generates and edits detailed images for hero visuals, product compositions and precise in-image text. The Pro edition emphasizes consistent objects, characters, materials and spatial relationships in dense scenes, using text and visual references to produce a PNG image.
About the model
This description covers the model’s capabilities. Available in Ailoot inputs, outputs and options are listed for the selected method below.
Microsoft AI MAI-Image-2.5 Pro is the fidelity-focused edition within the 2.5 image series. It generates images from natural-language briefs and performs directed edits on existing assets. Microsoft identifies hero imagery, detailed editing and precise in-image text as central uses, and its model comparison highlights consistency of objects, characters, materials and spatial relationships in complex compositions. The final artifact is a picture for a design or production workflow, such as a key product image or a carefully arranged editorial scene.
For generation, describe the composition through relationships rather than a list of unrelated objects. Identify the main subject, its scale relative to nearby items, the materials involved and the direction of light. The Pro edition’s documented visual reasoning is useful where these relationships define whether a dense scene is believable. For a product composition, place a ceramic pitcher, clear glasses and a folded cloth on a wooden table, with consistent reflections and a single window light. Review the contacts, shadows and visible material properties in the resulting image.
For product and character work, supply the visual identity that must survive the edit. Microsoft describes object consistency across complex scenes and character consistency across views and moments as Pro strengths. State which features identify the item or person and which aspect of the scene should change. For example, retain a jacket’s silhouette and fastening details while placing the character in a different background. The useful review compares those retained details with the source reference; a visually attractive result is not by itself evidence of an exact match.
The manufacturer’s image-editing interface accepts up to five JPEG or PNG references. Separate their roles in the brief: the product, the person, the setting or the visual treatment. Editing tasks include removal and replacement of objects, attribute changes, inpainting, layout adaptation, text updates and artifact cleanup. For a local edit, describe the target and the surrounding elements to preserve. For a more substantial rearrangement, explain how the composition should work after the change so the model has a coherent spatial objective.
Text rendering is particularly relevant to a hero composition or packaging concept. Supply the exact phrase, its position and its relationship to the object or image. Keep recurring names and label text consistent between the brief and references. Inspect each rendered character at the intended display size and compare it with the supplied wording. A later edit can focus on the wording or placement while retaining the successful product composition. The PNG output can then be incorporated into the layout whose final typographic and crop requirements are known.
The current Microsoft image guide applies a maximum output area of 1,048,576 pixels to the 2.5 models, equivalent to 1024×1024. Both dimensions must be at least 768 pixels in that interface, and a longer side is allowed when the total area remains within the limit. This permits rectangular compositions such as 1344×768, which totals 1,032,192 pixels. That area constraint is different from a maximum of 1024 on each side. Prepare the target shape for the composition instead of expecting a generic aspect-ratio label to determine the crop correctly.
The serving guide specifies a maximum prompt context of 32,000 tokens and returns PNG image data for both generation and editing. The exact Pro catalogue page separately lists a context window of 131.072K and 4,096 output tokens. These are published token quantities with their own catalogue or serving scope; the practical image-request preparation follows the serving prompt and pixel limits. Retain the image, source references and brief as one revision record. Check the visual result itself for the detailed identity, material and geometry constraints that motivated choosing Pro.
Version choice should follow the composition. Standard MAI-Image-2.5 covers general generation and localized edits; Pro adds the series’ emphasis on fidelity and consistent relationships in visually dense scenes. The 2.6 family raises the documented output-area limit and adds optional web grounding and automatic aspect selection. Those later controls are specific to 2.6 and do not define this Pro edition’s workflow. Choose Pro when the difficult part of the brief concerns stable object identity, material appearance or spatial structure within a detailed image.
Review both the requested change and the retained content. Hands holding objects, intersections, fine print, facial likeness and reflections are useful places to inspect in a complex composition. A plausible image can still contain a misleading marking or an incorrect physical relationship. Make the next correction concrete and preserve the parts of the brief that produced the intended layout. This supports a controlled sequence of design revisions rather than repeatedly redefining the entire scene.
Ailoot Ultra · Images POST /v1/images/generations microsoft/mai-image-2.5-pro
microsoft/mai-image-2.5-proOverview
Microsoft AI MAI-Image-2.5 Pro generates and edits detailed images for hero visuals, product compositions and precise in-image text. The Pro edition emphasizes consistent objects, characters, materials and spatial relationships in dense scenes, using text and visual references to produce a PNG image.
- Accepted inputs
- Text · Images
- Results
- Images
Available in Ailoot · inputs & methods
Ailoot Ultra · Images POST /v1/images/generations
- Input types
text,image- Output types
image
| Field | Type | Requirement | Values & limits | Default |
|---|---|---|---|---|
Fieldmodel | Typestring | RequirementRequired | Values & limits microsoft/mai-image-2.5-pro | Default— |
Fieldprompt | Typestring | RequirementRequired | Values & limits Minimum length: 1 | Default— |
Fieldaspect_ratio | Typestring | RequirementOptional | Values & limits 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, auto | Default— |
Fieldn | Typeinteger | RequirementOptional | Values & limits Minimum: 1 Maximum: 1 | Default— |
Fieldinput_references | Typearray | RequirementOptional | Values & limits Minimum items: 0 Maximum items: 1 | Default— |
Fieldprovider | Typeobject | RequirementOptional | Values & limits | Default— |
Method parameters and lifecycle
| Parameter | Contract |
|---|---|
Parametercontent_type | Contractapplication/json |
Parameterrequired | Contractmodel, prompt |
Parametermaterial_types | Contracttext, image |
Lifecycle: synchronous_result_then_owned_library
GET /v1/media/tasks/{task_id} · actual returned task_id or media library record
GET /v1/media/assets/{asset_id}/content
GET /v1/media/assets
GET /v1/media/assets/{asset_id}
Pricing
How the final charge is calculated
The displayed rates estimate the cost before generation. The final charge is calculated from the cost recorded for the original generation. Measured output duration and forecast quantities are not the final billable quantity.
Tariff references do not add request options. Supported parameters are listed for the selected method.
- Fast mode
- Not specified When fast mode is selected
- Flex mode
- Not specified When flex mode is selected
- Maximum reasoning effort
- Not specified When maximum reasoning effort uses the default adjustment
Estimated rates for comparison
Prices by configuration
Match each charge to the conditions shown. Use one rate for each set of alternative configurations.
| Configuration | Rate schedule | Forecast quantity | Charge |
|---|---|---|---|
| ConfigurationBase token rates | Rate scheduleBase rate | Forecast quantity— | Charge Input · Input tokens · Estimate for comparison only — / 1K tokens Output · Output tokens · Estimate for comparison only — / 1K tokens Input · Cache read · Estimate for comparison only — / 1K tokens Input · Cache write · Estimate for comparison only — / 1K tokens Input · Cache write, 1 hour · Estimate for comparison only — / 1K tokens |
| ConfigurationEstimated generation cost | Rate schedule— | Forecast quantityone generation estimate | Charge Output · Estimated generation cost · Estimate for comparison only $0.884736 estimate before generation This estimate is not an additional charge or a fixed rate for the completed generation. |
Ailoot reserves an estimated amount before a request. After the result, it settles the final charge from measured usage. Streaming settlement uses the final usage record. How reservation and settlement work →
Example requests
Ailoot Ultra · Images
set -eu
: "${AILOOT_API_KEY:?Set your Ailoot API key}"
export AILOOT_API_KEY
python3 - <<'PY_REQUEST'
import json,os
from pathlib import Path
p={'model': 'microsoft/mai-image-2.5-pro', 'prompt': 'a red panda astronaut floating in space, studio lighting'}
Path("request.json").write_text(json.dumps(p,ensure_ascii=False))
PY_REQUEST
curl --fail-with-body --silent --show-error https://api.ailoot.ai/v1/images/generations \
-H "Authorization: Bearer $AILOOT_API_KEY" -H 'Content-Type: application/json' \
--data-binary @request.json -D response-headers.txt -o result.json
python3 - <<'PY_RESULT'
import base64, json, os, subprocess
from pathlib import Path
from urllib.parse import urlsplit, urljoin
def save_images(items):
if not items: raise SystemExit("No completed images; retain the full response")
for index, item in enumerate(items):
encoded=item.get("b64_json")
uri=item.get("url", "")
if not encoded and uri.startswith("data:image/"):
header, separator, encoded=uri.partition(",")
if not separator or ";base64" not in header: raise SystemExit("Unsupported image data URI")
if encoded:
raw=base64.b64decode(encoded,validate=True)
elif uri:
uri=urljoin("https://api.ailoot.ai",uri)
parsed=urlsplit(uri)
if parsed.scheme!="https" or not parsed.netloc or parsed.username or parsed.password:
raise SystemExit("Invalid returned image URL")
owned=parsed.netloc=="api.ailoot.ai" and parsed.path.startswith("/v1/media/assets/") and parsed.path.endswith("/content")
args=["curl","--fail-with-body","--silent","--show-error",uri]
if owned: args += ["-H","Authorization: Bearer "+os.environ["AILOOT_API_KEY"]]
temporary=Path(f"image-{index}.bin")
subprocess.run(args+["-o",str(temporary)],check=True)
raw=temporary.read_bytes()
temporary.unlink()
else: raise SystemExit("Image has neither bytes nor URL")
if not raw: raise SystemExit("Empty image result")
ext="png" if raw.startswith(b"\x89PNG") else "jpg" if raw.startswith(b"\xff\xd8") else "webp" if raw[:4]==b"RIFF" and raw[8:12]==b"WEBP" else "svg" if raw.lstrip().startswith((b"<svg",b"<?xml")) else "bin"
Path(f"image-{index}.{ext}").write_bytes(raw)
print("Every returned image saved; complete response metadata retained")
save_images(json.loads(Path("result.json").read_text())["data"])
PY_RESULT
Receive and save results
Ailoot Ultra · Images
Download each returned image or save its Base64 contents
GET /v1/media/tasks/{task_id}GET /v1/media/assets/{asset_id}/contentGET /v1/media/assetsGET /v1/media/assets/{asset_id}
Other content reads
set -eu
: "${AILOOT_API_KEY:?Set your Ailoot API key}"
curl --fail-with-body --silent --show-error https://api.ailoot.ai/v1/media/assets \
-H "Authorization: Bearer $AILOOT_API_KEY" -o owned-assets.json
# Preserve every returned asset and follow its exact signed content URL. Do not construct a signed token.
Keep all completed results
Save every completed image; retrieve each returned URL or decode its Base64 contents.
Retain the complete response and headers, every actual output, original returned identifiers and all usage fields. Recover the original operation without submitting creation again.
If the original response needs checking
Keep the returned X-Client-Request-ID for reconciliation. Read only actual returned task_id/asset_id values or the owned media library; never build a task URL from the operation ID and never resubmit creation.
Response fields
| Field | Type |
|---|---|
Fieldcreated | Type |
Fielddata[].url | Type |
Fielddata[].b64_json | Type |
Fieldusage | Type |
Aliases
Model aliases
Ailoot Ultra microsoft/mai-image-2.5-pro
Method path aliases
/v1/images
Related caller IDs
FAQ · Microsoft AI: MAI-Image-2.5 Pro
- What inputs and results are available?
POST /v1/images/generations·microsoft/mai-image-2.5-pro:text,image→image- Which fields does the request use?
POST /v1/images/generations·microsoft/mai-image-2.5-pro:model,prompt,aspect_ratio,n,input_references,provider- What limits apply?
POST /v1/images/generations·microsoft/mai-image-2.5-pro:n.minimum:1;n.maximum:1