MAI Image 2.7 API reference (2.7 / Flash)
The API for Microsoft's MAI Image 2.7 (a Microsoft public preview), in two tiers: mai-image-2.7 and mai-image-2.7-flash. One endpoint covers text-to-image and editing: a prompt alone, or a prompt plus 1–5 input images; one image per request, seven aspect ratios at 1K / 2K or an exact size up to 2048×2048; transparent backgrounds in PNG / WebP. Both tiers take the same request and differ only in their per-token rates.
Autenticação
All requests carry the API key in the header:
Authorization: Bearer YOUR_API_KEYPreços
| Item | mai-image-2.7 | mai-image-2.7-flash |
|---|---|---|
| Text input, per 1M tokens | $7.15 | $2.50 |
| Image input, per 1M tokens | $11.44 | $3.58 |
| Image output, per 1M tokens | $48.62 | $14.30 |
| Reference: one 1K text-to-image | about $0.05 | about $0.015 |
| Reference: one 2K image | about $0.20 | about $0.059 |
| Reference: 1K edit with one input image | about $0.06 | about $0.018 |
You are charged for the tokens each request actually uses, so there is no fixed unit price: a 1K image (about 1 megapixel) is about 1,024 output tokens and a 2K image about 4,096; each input image counts as image input and the prompt as text input. The reference rows are typical costs; the credits field on the finished task shows what was charged. Failed requests are not charged.
Text-to-image
/v1/images/generationsAsync by default: create returns a taskId; poll GET ?task_id= until completed and read resultUrls, or receive a webhook via callback_url. With no size settings you get a 1:1 image at 1K. We have run one test so far (18 November 2026): Flash, 1K 16:9 text-to-image, a 1360×768 PNG in about 16 seconds end to end, charged $0.0148. That is a single example, not a typical timing; we have no measurements yet for 2.7, 2K or edits.
# Text-to-image — create returns a taskId, then poll for the result.
curl -X POST https://api.apimodels.app/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "mai-image-2.7",
"prompt": "A minimalist product photo of a matte white ceramic teapot on a light oak table beside a sunlit window, soft shadows, realistic photography",
"aspect_ratio": "16:9",
"resolution": "1K"
}'
# → { "code": 200, "data": { "taskId": "...", "state": "pending", "model": "mai-image-2.7" } }
curl "https://api.apimodels.app/v1/images/generations?task_id=TASK_ID" \
-H "Authorization: Bearer YOUR_API_KEY"
# → { "code": 200, "data": { "state": "completed", "resultUrls": ["https://r2.apimodels.app/..."] } }Editing · combining pictures
Add image (one picture) or images (up to 5) to edit; the model id stays the same. Say what to change and what to keep; with several pictures, refer to them by what they show ("the teapot from the second image"). Input images can be public URLs or data URIs. Without a size, an edit comes back close to the input's size; aspect_ratio or size overrides that. Microsoft's headline is fine-grained editing: change an object's colour, material or position while the rest stays put, and keep the picture consistent across successive edits.
# Edit one picture — say what to change and what to keep.
curl -X POST https://api.apimodels.app/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "mai-image-2.7",
"prompt": "Make the teapot glossy cobalt blue. Keep the table, the window light, the shadows and the framing exactly the same.",
"image": "https://example.com/teapot.jpg"
}'
# Combine up to 5 pictures — refer to them by what they show.
curl -X POST https://api.apimodels.app/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "mai-image-2.7",
"prompt": "Place the teapot from the second image on the kitchen counter in the first image. Keep the kitchen and its lighting unchanged.",
"images": ["https://example.com/kitchen.jpg", "https://example.com/teapot.png"],
"aspect_ratio": "4:3"
}'2K and exact sizes
resolution 2K doubles each side (2048×2048 at 1:1, about 4× the tokens, about $0.20 per image on 2.7). You can also pass size as WIDTHxHEIGHT: each side at least 768 px, at most 4,194,304 pixels (2048×2048), rounded down to a multiple of 16; there is no 4K. With an exact size and no callback_url, the request stays open until the image is ready and returns { created, data: [{ url }] } in the same response — what the OpenAI SDK's images.generate expects.
# 2K preset: each side doubled (16:9 → about 2720x1536).
curl -X POST https://api.apimodels.app/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "mai-image-2.7",
"prompt": "A wide hero banner of a quiet mountain lake at dawn, mist over the water, a small wooden dock",
"aspect_ratio": "16:9",
"resolution": "2K"
}'
# Exact size + no callback_url: the image comes back in this same response (OpenAI shape).
# Each side >= 768 px, at most 4,194,304 pixels (2048x2048), rounded down to a multiple of 16.
curl -X POST https://api.apimodels.app/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "mai-image-2.7-flash",
"prompt": "A square app icon of a paper plane on a soft gradient, flat illustration",
"size": "2048x2048",
"response_format": "url"
}'
# → { "created": ..., "data": [{ "url": "https://r2.apimodels.app/..." }] }Transparent background
Set background to transparent with output_format png or webp, for text-to-image and edits alike: product shots, logos, icons and stickers without a cut-out step. JPEG has no alpha channel, so it cannot be combined with a transparent background.
# Transparent background: background "transparent" + png or webp (JPEG has no alpha channel).
curl -X POST https://api.apimodels.app/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "mai-image-2.7",
"prompt": "A die-cut sticker of a smiling cartoon avocado with a thick white outline, no background",
"background": "transparent",
"output_format": "png",
"aspect_ratio": "1:1",
"resolution": "1K"
}'
# The same on an existing photo: cut the product out.
curl -X POST https://api.apimodels.app/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "mai-image-2.7-flash",
"prompt": "Cut out the ceramic mug on a transparent background. Keep the mug, its handle and its glaze exactly as they are.",
"image": "https://example.com/mug.jpg",
"background": "transparent",
"output_format": "webp"
}'Parâmetros
| Field | Required | Type | Description |
|---|---|---|---|
| model | Yes | string | mai-image-2.7 or mai-image-2.7-flash |
| prompt | Yes | string | Required, up to 32,000 characters; for edits, say what to change and what to keep |
| image / images / image_urls | No | string / string[] | 1–5 input images to edit (public URL or data URI); leave out for text-to-image |
| aspect_ratio | No | string | 1:1 (text-to-image default), 4:3, 3:4, 3:2, 2:3, 16:9, 9:16 |
| resolution | No | string | 1K (default, about 1 megapixel) or 2K (each side doubled); applies to aspect_ratio presets only |
| size | No | string | Exact size such as 1536x1024; each side ≥ 768, at most 4,194,304 pixels, rounded down to a multiple of 16. Overrides aspect_ratio, and resolution is ignored; without callback_url the image comes back in the same response |
| image_size | No | string / object | Alternative form: a preset name — square_hd, landscape_4_3, portrait_4_3, landscape_3_2, portrait_3_2, landscape_16_9, portrait_16_9 (with resolution) — or {"width": W, "height": H} (same size rules as above). Priority: image_size > size > aspect_ratio |
| background | No | string | opaque (default) or transparent; transparent needs png or webp |
| output_format | No | string | png (default) / jpeg / webp; jpg is accepted as jpeg |
| quality | No | string | Accepted but ignored (this model has no quality tiers) |
| response_format | No | string | One-call mode: url returns links only |
| callback_url | No | string | Webhook URL called when the task completes |
Limits
- One image per request; n (num_images) other than 1 returns 400, so send separate requests for more.
- Up to 5 input images (more returns 400); mask, seed and negative_prompt are not supported and return 400 instead of being silently dropped.
- Up to 2048×2048, no 4K; only the seven aspect ratios above (others return 400); no side below 768 px. resolution is ignored for exact sizes; quality has no effect.
- Output is PNG, JPEG or WebP only (no GIF or SVG); a transparent background needs PNG or WebP.
- Microsoft offers both models as a public preview, so behaviour may change.
- Text renders legibly, but specifications, dates and part names can be invented; check them before you publish.
Not every request succeeds
Content review can refuse a prompt or an image, and the upstream occasionally returns a temporary error. Failed requests are not charged, and the response carries the reason: for review refusals, change the prompt or the image; for temporary errors, retry. Result files are deleted after 30 days, so download or re-host them promptly.
Try it in the playground: MAI Image 2.7 / MAI Image 2.7 Flash (the playground offers 1K / 2K and aspect ratios and returns PNG; use the API for transparent backgrounds, JPEG / WebP and exact sizes). For 4K, GIF or SVG, see GPT Image 2.6.
Perguntas frequentes
How do I edit an image with MAI Image 2.7?
POST to /v1/images/generations with model mai-image-2.7 (or mai-image-2.7-flash), a prompt that says what to change and what to keep, and the picture as image (or up to 5 pictures as images). Input images are billed as image-input tokens.
How much does MAI Image 2.7 cost?
Per token, on actual usage. mai-image-2.7: text input $7.15, image input $11.44, image output $48.62 per 1M tokens, about $0.05 per 1K image. mai-image-2.7-flash: $2.50 / $3.58 / $14.30, about $0.015 per 1K image. Failed requests are not charged.
How do I get a transparent background?
Pass background: "transparent" with output_format png or webp. JPEG has no alpha channel, so it cannot be combined with a transparent background.