# MAI Image API

> Provider: **Microsoft**
> Source: https://www.pixazo.ai/models/mai-image

MAI Image 2.5 API is Microsoft's proprietary, internally developed text-to-image foundation model interface that allows developers to programmatically generate and edit high-fidelity visuals directly through Microsoft Azure AI Foundry. This diffusion-based cloud programmatic gateway enables enterprise workflows to transition natural language prompts into photorealistic assets, featuring visual reasoning capabilities across scale, complex studio lighting, and spatial relationships. Built specifically to support production-level graphic pipelines, the application interface provides fine-grained, localized edit controls, precise text rendering within layouts, and strict facial identity consistency across consecutive iterations.

## MAI Image 2.5

### Text to Image

## Base URL

```
https://gateway.pixazo.ai/microsoft-mai-image-2-5/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Microsoft MAI Image 2.5 generate request

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/microsoft-mai-image-2-5/v1/microsoft-mai-image-2-5-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY

{
  "prompt": "A photorealistic still life of vintage cameras on a wooden desk, warm window light",
  "num_images": 1,
  "aspect_ratio": "auto",
  "output_format": "png",
  "sync_mode": false
}
```

```
import requests

url = "https://gateway.pixazo.ai/microsoft-mai-image-2-5/v1/microsoft-mai-image-2-5-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "A photorealistic still life of vintage cameras on a wooden desk, warm window light",
    "num_images": 1,
    "aspect_ratio": "auto",
    "output_format": "png",
    "sync_mode": false
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const url = "https://gateway.pixazo.ai/microsoft-mai-image-2-5/v1/microsoft-mai-image-2-5-request";
const headers = {
  "Content-Type": "application/json",
  "Cache-Control": "no-cache",
  "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
};
const data = {
  prompt: "A photorealistic still life of vintage cameras on a wooden desk, warm window light",
  num_images: 1,
  aspect_ratio: "auto",
  output_format: "png",
  sync_mode: false
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));
```

```
curl -X POST "https://gateway.pixazo.ai/microsoft-mai-image-2-5/v1/microsoft-mai-image-2-5-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "prompt": "A photorealistic still life of vintage cameras on a wooden desk, warm window light",
    "num_images": 1,
    "aspect_ratio": "auto",
    "output_format": "png",
    "sync_mode": false
  }'
```

## Output

```
{
  "request_id": "microsoft-mai-image-2-5_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/microsoft-mai-image-2-5_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=microsoft-mai-image-2-5&operation=microsoft-mai-image-2-5-request)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Microsoft MAI Image 2.5 generate request

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

non-empty; ≤ 5000 chars

Text prompt for image generation (3–5000 characters)

num\_images

No

integer

1

1–4

Number of images to generate (valid values: 1–4)

aspect\_ratio

No

string

"auto"

"auto", "21:9", "16:9", "3:2", "4:3", "5:4", "1:1", "4:5", "3:4", "2:3", "9:16"

Image aspect ratio. Allowed: \`auto\`, \`21:9\`, \`16:9\`, \`3:2\`, \`4:3\`, \`5:4\`, \`1:1\`, \`4:5\`, \`3:4\`, \`2:3\`, \`9:16\`

output\_format

No

string

"png"

"jpeg", "png", "webp"

Output format of generated images. Allowed: \`jpeg\`, \`png\`, \`webp\`

sync\_mode

No

boolean

false

—

If true, returns media as a data URI inline in the response; otherwise returns a polling ID

## Example Request

```
{
  "prompt": "A photorealistic still life of vintage cameras on a wooden desk, warm window light",
  "num_images": 1,
  "aspect_ratio": "auto",
  "output_format": "png",
  "sync_mode": false
}
```

## Response

```
{
  "request_id": "microsoft-mai-image-2-5_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/microsoft-mai-image-2-5_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_API\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'microsoft-mai-image-2-5' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "microsoft-mai-image-2-5_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "microsoft-mai-image-2-5",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/microsoft-mai-image-2-5_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "microsoft-mai-image-2-5_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "microsoft-mai-image-2-5",
  "error": null,
  "output": {
    "media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/microsoft-mai-image-2-5_019dxxxx/output.png"],
    "media_type": "image/png"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

### Image to Image (Image Editing)

## Base URL

```
https://gateway.pixazo.ai/microsoft-mai-image-2-5-edit/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Microsoft MAI Image 2.5 Edit generate request

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/microsoft-mai-image-2-5-edit/v1/microsoft-mai-image-2-5-edit-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY

{
  "prompt": "Make the lighting warm golden hour and add a soft bokeh background",
  "image_urls": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg"
  ],
  "num_images": 1,
  "aspect_ratio": "auto",
  "output_format": "png",
  "sync_mode": false
}
```

```
import requests

url = "https://gateway.pixazo.ai/microsoft-mai-image-2-5-edit/v1/microsoft-mai-image-2-5-edit-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "Make the lighting warm golden hour and add a soft bokeh background",
    "image_urls": [
        "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg"
    ],
    "num_images": 1,
    "aspect_ratio": "auto",
    "output_format": "png",
    "sync_mode": false
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const url = "https://gateway.pixazo.ai/microsoft-mai-image-2-5-edit/v1/microsoft-mai-image-2-5-edit-request";

const data = {
  prompt: "Make the lighting warm golden hour and add a soft bokeh background",
  image_urls: [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg"
  ],
  num_images: 1,
  aspect_ratio: "auto",
  output_format: "png",
  sync_mode: false
};

fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));
```

```
curl -X POST "https://gateway.pixazo.ai/microsoft-mai-image-2-5-edit/v1/microsoft-mai-image-2-5-edit-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "prompt": "Make the lighting warm golden hour and add a soft bokeh background",
    "image_urls": [
        "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg"
    ],
    "num_images": 1,
    "aspect_ratio": "auto",
    "output_format": "png",
    "sync_mode": false
  }'
```

## Output

```
{
  "request_id": "microsoft-mai-image-2-5-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/microsoft-mai-image-2-5-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=microsoft-mai-image-2-5-edit&operation=microsoft-mai-image-2-5-edit-request)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Microsoft MAI Image 2.5 Edit generate request

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

3–5000 chars

Instruction describing how to edit the input image. Must be 3–5000 characters long.

image\_urls

Yes

string\[\]

—

—

Array containing exactly one URL to the source image. Supports HTTP(S) or data: URLs.

num\_images

No

integer

1

1, 2, 3, 4

Number of output images to generate. Allowed values: 1, 2, 3, 4.

aspect\_ratio

No

string

"auto"

auto, 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3

Desired output aspect ratio. Use auto to match the input image dimensions or let the model decide.

output\_format

No

string

"png"

jpeg, png, webp

Output image format. Allowed values: jpeg, png, webp.

sync\_mode

No

boolean

false

—

If true, returns the generated image(s) as base64-encoded data URIs inline in the response. If false, returns a polling URL for asynchronous retrieval.

## Example Request

```
{
  "prompt": "Make the lighting warm golden hour and add a soft bokeh background",
  "image_urls": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg"
  ],
  "num_images": 1,
  "aspect_ratio": "auto",
  "output_format": "png",
  "sync_mode": false
}
```

## Response

```
{
  "request_id": "microsoft-mai-image-2-5-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/microsoft-mai-image-2-5-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_API\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'microsoft-mai-image-2-5-edit' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "microsoft-mai-image-2-5-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "microsoft-mai-image-2-5-edit",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/microsoft-mai-image-2-5-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "microsoft-mai-image-2-5-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "microsoft-mai-image-2-5-edit",
  "error": null,
  "output": {
    "media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/microsoft-mai-image-2-5-edit_019dxxxx/output.png"],
    "media_type": "image/png"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.