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.
", "aboutText": "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.\n\nFor 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.\n\nVisual 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.\n\nDirected 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.\n\nMicrosoft 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.\n\nThe 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.\n\nGeneration 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.\n\nThe 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.\n\nWithin 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.", "editorialOverlay": { "copy_fields": null, "copy_sha256": null, "copy_source": null, "html_sha256": "7d415d96ddadf6c8806ca748d1ba97e7926173813c6b78a98def15fdb9e65739", "module_sha256": "ee9dc1c50b1e6a8fb7fa062030fcb4646b9aaaeb08be513b723a5a92a7290f06", "raw_model_unchanged": true, "schema": "ailoot-native-model-editorial-v1" }, "locale": "en", "methods": [ { "html": "microsoft/mai-image-2.5Microsoft 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.
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.
POST /v1/images/generationstext, imageimage| 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— |
| 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}
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.
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 →
set -eu\n: "${AILOOT_API_KEY:?Set your Ailoot API key}"\nexport AILOOT_API_KEY\npython3 - <<'PY_REQUEST'\nimport json,os\nfrom pathlib import Path\np={'model': 'microsoft/mai-image-2.5', 'prompt': 'a red panda astronaut floating in space, studio lighting'}\n\nPath("request.json").write_text(json.dumps(p,ensure_ascii=False))\nPY_REQUEST\ncurl --fail-with-body --silent --show-error https://api.ailoot.ai/v1/images/generations \\\n -H "Authorization: Bearer $AILOOT_API_KEY" -H 'Content-Type: application/json' \\\n --data-binary @request.json -D response-headers.txt -o result.json\npython3 - <<'PY_RESULT'\nimport base64, json, os, subprocess\nfrom pathlib import Path\nfrom urllib.parse import urlsplit, urljoin\n\ndef save_images(items):\n if not items: raise SystemExit("No completed images; retain the full response")\n for index, item in enumerate(items):\n encoded=item.get("b64_json")\n uri=item.get("url", "")\n if not encoded and uri.startswith("data:image/"):\n header, separator, encoded=uri.partition(",")\n if not separator or ";base64" not in header: raise SystemExit("Unsupported image data URI")\n if encoded:\n raw=base64.b64decode(encoded,validate=True)\n elif uri:\n uri=urljoin("https://api.ailoot.ai",uri)\n parsed=urlsplit(uri)\n if parsed.scheme!="https" or not parsed.netloc or parsed.username or parsed.password:\n raise SystemExit("Invalid returned image URL")\n owned=parsed.netloc=="api.ailoot.ai" and parsed.path.startswith("/v1/media/assets/") and parsed.path.endswith("/content")\n args=["curl","--fail-with-body","--silent","--show-error",uri]\n if owned: args += ["-H","Authorization: Bearer "+os.environ["AILOOT_API_KEY"]]\n temporary=Path(f"image-{index}.bin")\n subprocess.run(args+["-o",str(temporary)],check=True)\n raw=temporary.read_bytes()\n temporary.unlink()\n else: raise SystemExit("Image has neither bytes nor URL")\n if not raw: raise SystemExit("Empty image result")\n 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"\n Path(f"image-{index}.{ext}").write_bytes(raw)\n print("Every returned image saved; complete response metadata retained")\nsave_images(json.loads(Path("result.json").read_text())["data"])\nPY_RESULT\nDownload 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}set -eu\n: "${AILOOT_API_KEY:?Set your Ailoot API key}"\ncurl --fail-with-body --silent --show-error https://api.ailoot.ai/v1/media/assets \\\n -H "Authorization: Bearer $AILOOT_API_KEY" -o owned-assets.json\n# Preserve every returned asset and follow its exact signed content URL. Do not construct a signed token.\nSave 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.
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.
| Field | Type |
|---|---|
Fieldcreated | Type |
Fielddata[].url | Type |
Fielddata[].b64_json | Type |
Fieldusage | Type |
Ailoot Ultra microsoft/mai-image-2.5
/v1/images