APIMODELSAPIMODELS
APIドキュメント

apimodels.app

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.

Authentication

All requests carry the API key in the header:

Authorization: Bearer YOUR_API_KEY

Pricing

Itemmai-image-2.7mai-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-imageabout $0.05about $0.015
Reference: one 2K imageabout $0.20about $0.059
Reference: 1K edit with one input imageabout $0.06about $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

POST/v1/images/generations

Async 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"
  }'

Parameters

FieldRequiredTypeDescription
modelYesstringmai-image-2.7 or mai-image-2.7-flash
promptYesstringRequired, up to 32,000 characters; for edits, say what to change and what to keep
image / images / image_urlsNostring / string[]1–5 input images to edit (public URL or data URI); leave out for text-to-image
aspect_ratioNostring1:1 (text-to-image default), 4:3, 3:4, 3:2, 2:3, 16:9, 9:16
resolutionNostring1K (default, about 1 megapixel) or 2K (each side doubled); applies to aspect_ratio presets only
sizeNostringExact 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_sizeNostring / objectAlternative 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
backgroundNostringopaque (default) or transparent; transparent needs png or webp
output_formatNostringpng (default) / jpeg / webp; jpg is accepted as jpeg
qualityNostringAccepted but ignored (this model has no quality tiers)
response_formatNostringOne-call mode: url returns links only
callback_urlNostringWebhook 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.

FAQ

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.