Microsoft AI: MAI-Image-2.5
Microsoft AI MAI-Image-2.5 creates images from text and makes targeted edits to supplied photos or designs. It supports object and text changes, artifact cleanup and face-preserving revisions, with PNG output and up to five visual references. Its model card specifies a 32K context and 1,048,576 output pixels.
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 is the general generation and controlled-editing edition of the 2.5 image family. Its model card describes a diffusion model using flow matching, with 20 billion non-embedding parameters, text and image input, and a 32K-token context. It produces image output for concepts, portraits, product imagery, illustrations and revisions of existing designs. The useful starting choice is whether the task needs a new composition or a specific change to an asset that already contains the intended subject.
For generation, describe the main subject, visual style, light, viewpoint and arrangement. The maker highlights detailed, coherent images, text rendering, product imagery and prompt adherence. A practical brief for a presentation illustration can specify the subject’s role, the intended visual emphasis and the amount of surrounding space. A product concept can include the material, scale and surface finish. Keep the description coherent so objects share one scene and one lighting plan instead of combining several incompatible visual treatments.
Visual reasoning in this edition concerns scene structure, lighting, scale and spatial relationships. The manufacturer gives adding an object with suitable perspective and shadows as an editing use. For a workshop edit, place a small stool beside a workbench while retaining the existing viewpoint and light. The review should compare the stool’s size, where it touches the floor and whether its shadow follows the other objects. A locally convincing object still needs to fit the geometry of the whole source image.
Directed edits include object removal or replacement, attribute changes, inpainting, layout adaptation, text updates and cleanup such as reducing motion-blur artifacts. Provide the source image and name both the correction and the details to retain. A focused photo edit might remove a distracting object from the background while keeping the person, crop and foreground arrangement. A design revision might update a short line of text while retaining the composition. Compare the complete result with the source rather than assessing only the edited region.
Microsoft also emphasizes facial identity consistency across edits, including changes of pose, expression or viewpoint. Use a clear reference for the likeness and specify the intended change in a way that preserves the identifying features. The manufacturer’s current editing guide accepts up to five JPEG or PNG images, allowing different references to identify the person, object, scene or style. Name those roles in the prompt. In a portrait revision, inspect the face as well as the changed clothing or background before treating the image as finished.
The exact model card limits output to 1,048,576 total pixels, equivalent to a 1024×1024 square, and allows one side to exceed 1024 if the total remains within that area. The serving guide additionally requires both dimensions to be at least 768 pixels. A rectangular target such as 1344×768 has 1,032,192 pixels and satisfies those documented area and minimum-dimension rules. The useful limit is the product of width and height, so prepare the destination shape before asking for a landscape or portrait composition.
Generation and editing return PNG image data in the manufacturer’s serving interface. The native model card reports a 32K-token context, while that interface specifies a 32,000-token maximum prompt context. The catalogue’s separate 4,096 output-token figure is a token allowance rather than an output dimension. Retain those stated scopes when organizing a detailed prompt and the finished image. Source assets, retained features, requested edits and target size make a useful revision record alongside the PNG.
The model’s creative range spans photorealistic and cinematic imagery, portraits, product or branding concepts, text-bearing designs and other visual styles. For a label or sign, supply the exact wording and inspect its spelling at the final display size. A recognisable photographic surface can still contain invented detail, an inconsistent reflection or inaccurate lettering. A practical check follows the design’s requirements: object identity, legibility, spatial relationships and the retained scene all matter. Keep a specific correction separate from changes that have already worked.
Within the 2.5 family, Pro emphasizes higher fidelity and stable relationships in dense scenes, while Flash serves more responsive production. The 2.6 family introduces a larger documented pixel-area allowance, optional web grounding and model-directed aspect selection. Standard 2.5 retains its own generation and editing workflow without those later controls. Select the edition from the difficult part of the actual image task and review the completed result against that brief.
Ailoot Ultra · Images POST /v1/images/generations microsoft/mai-image-2.5
microsoft/mai-image-2.5Overview
Microsoft AI MAI-Image-2.5 creates images from text and makes targeted edits to supplied photos or designs. It supports object and text changes, artifact cleanup and face-preserving revisions, with PNG output and up to five visual references. Its model card specifies a 32K context and 1,048,576 output pixels.
- 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 | 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.385024 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', '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
Method path aliases
/v1/images
Related caller IDs
FAQ · Microsoft AI: MAI-Image-2.5
- What inputs and results are available?
POST /v1/images/generations·microsoft/mai-image-2.5:text,image→image- Which fields does the request use?
POST /v1/images/generations·microsoft/mai-image-2.5:model,prompt,aspect_ratio,n,input_references,provider- What limits apply?
POST /v1/images/generations·microsoft/mai-image-2.5:n.minimum:1;n.maximum:1