models

Microsoft AI: MAI-Image-2.5

Markdown · JSON

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.5

Microsoft AI /microsoft/mai-image-2.5

Overview

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
FieldTypeRequirementValues & limitsDefault
FieldmodelTypestringRequirementRequiredValues & limits
microsoft/mai-image-2.5
Default—
FieldpromptTypestringRequirementRequiredValues & limits
Minimum length: 1
Default—
Fieldaspect_ratioTypestringRequirementOptionalValues & limits
1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, auto
Default—
FieldnTypeintegerRequirementOptionalValues & limits
Minimum: 1
Maximum: 1
Default—
Fieldinput_referencesTypearrayRequirementOptionalValues & limits
Minimum items: 0
Maximum items: 1
Default—
FieldproviderTypeobjectRequirementOptionalValues & limitsDefault—
Method parameters and lifecycle
ParameterContract
Parametercontent_typeContractapplication/json
ParameterrequiredContractmodel, prompt
Parametermaterial_typesContracttext, 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.

ConfigurationRate scheduleForecast quantityCharge
ConfigurationBase token ratesRate scheduleBase rateForecast 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 costRate schedule—Forecast quantityone generation estimateCharge
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

curl
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}/content
  • GET /v1/media/assets
  • GET /v1/media/assets/{asset_id}
Other content reads
Read existing owned assets
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
FieldType
FieldcreatedType
Fielddata[].urlType
Fielddata[].b64_jsonType
FieldusageType

Aliases

Model aliases

Ailoot Ultra microsoft/mai-image-2.5

Method path aliases

/v1/images

Related caller IDs

microsoft/mai-image-2.5

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

More details

Connect Ailoot to Claude Code, OpenCode, Hermes or your own app.

The company and its project portfolio

The company and its project portfolio: millions of customers; monthly sales in the billions.

Buy tokens at a discount.

Subscription discounts for regular use. Promo codes offer up to 50% off token purchases.

Subscription
Choose a discounted plan for your regular requests.
Promo code: up to 50% off
Enter your code at checkout. The price updates to reflect the current promotion.
Spending in your history
The model, tokens and amount are recorded for each request.

Choose a subscription · View model prices

Connect the API to a product you sell.

Use Ailoot in SaaS, apps and bots under its official service offer and licence agreement. Request a reseller licence for resale.

Commercial application
Add text, image, video and audio generation to paid features in your service.
Reseller licence
Send a description of your project and how you provide access. Request written terms for use and resale.
Documents on the website
The service offer, licence agreement and data processing policy are available before you connect.

Request a reseller licence · Service offer and licence agreement