Microsoft MAI models: lineup and how to use them
What you’ll learn
Section titled “What you’ll learn”- What the MAI family is and how it differs from the OpenAI and partner models that Microsoft also sells.
- Which MAI models exist in November 2026, what each does, and where you can actually call it.
- How to call MAI-Thinking-1 in Microsoft Foundry, including its encrypted reasoning state and token limits.
- What “preview” means in practice: no SLA, a default quota of zero, no provisioned throughput.
- How to choose between an MAI model and another model in the same Foundry resource.
Summary
Section titled “Summary”MAI (Microsoft AI) is the family of models that Microsoft trains itself, as opposed to the OpenAI, Anthropic, Meta, Mistral and other models it hosts. The family launched across several modalities around Microsoft Build in June 2026 and now covers reasoning text (MAI-Thinking), coding (MAI-Code), image generation and editing (MAI-Image), speech-to-text (MAI-Transcribe) and text-to-speech (MAI-Voice).
The models are not all offered in the same place. MAI-Thinking and MAI-Image are Foundry Models sold by Azure; MAI-Transcribe and MAI-Voice run through Azure Speech in Foundry Tools; MAI-Code is a model choice inside GitHub Copilot and Microsoft’s Copilot Code. Most are in preview in November 2026, which matters more for production planning than any capability claim.
Every figure below comes from Microsoft Learn or GitHub’s documentation on the date shown. Version numbers in this family move every few weeks, so treat the tables as a snapshot. Microsoft’s small language models (Phi) are covered separately on Microsoft small language models.
The MAI family at a glance
Section titled “The MAI family at a glance”Checked on Microsoft Learn and the GitHub Copilot docs, November 16, 2026.
| Capability | Current models | Where you call it | Status |
|---|---|---|---|
| Reasoning text | MAI-Thinking-1 (version 2026-06-01) |
Microsoft Foundry, Global Standard deployment | Preview |
| Coding | MAI-Code-1.1-Flash | GitHub Copilot model picker; Copilot Code | GA in GitHub Copilot |
| Image generation and editing | MAI-Image-2.6, MAI-Image-2.6-Flash (2026-07-31); MAI-Image-2.5-Pro (2026-06-19); MAI-Image-2.5, MAI-Image-2.5-Flash (2026-06-02) |
Microsoft Foundry, Global Standard deployment | Preview |
| Speech to text | MAI-Transcribe-2, MAI-Transcribe-1.5 |
Azure Speech (fast transcription enhancedMode, Voice Live) |
MAI-Transcribe-1 deprecated August 20, 2026 |
| Text to speech | MAI-Voice-2.1, MAI-Voice-2.1-Flash |
Azure Speech (SSML voice name suffix) | Public preview |
Microsoft also documents task-specific MAI variants inside other products, for example MAI-Cyber-1.1-Flash in a Defender code-security integration. Those are features of the product, not general-purpose endpoints.
Earlier MAI versions (November 2026)
- MAI-Code-1-Flash launched in GitHub Copilot in June 2026 and was retired from all Copilot experiences on September 10, 2026, with “latest MAI-Code model” as the replacement (GitHub’s model retirement history).
- MAI-Transcribe-1 was deprecated on August 20, 2026; MAI-Transcribe-1.5 and 2 remain.
- MAI-Voice-2 is the name used in launch coverage; the Azure Speech page now lists only MAI-Voice-2.1 and MAI-Voice-2.1-Flash.
GitHub notes that MAI models in Copilot “are continuously improving models”, so behavior can change between checkpoints without a new name.
MAI-Thinking-1: the reasoning model
Section titled “MAI-Thinking-1: the reasoning model”MAI-Thinking-1 is the family’s general-purpose text model. Microsoft positions it for work where quality depends on multi-step reasoning: enterprise assistants that follow complex instructions, coding workflows that read code, run tests and recover from mistakes, and quantitative reasoning such as financial modeling and forecasting.
| Property | Value (Microsoft Learn, November 2026) |
|---|---|
| Input / output | Text in, text out; function tools only |
| Context window | 256,000 tokens per request, input and output together |
| Output cap | 64,000 tokens, including reasoning tokens |
| API | Chat completions, compatible with the OpenAI SDK, at https://<resource>.services.ai.azure.com/mai/v1/chat/completions |
| Deployment | Global Standard only; provisioned throughput (PTU) not supported |
| Default quota | 0 tokens per minute on the Low tier; 100,000 TPM / 100 RPM on Medium; 250,000 TPM / 250 RPM on High |
| Authentication | Microsoft Entra ID (recommended) or an API key in the api-key header |
Three API details shape how you build on it:
modelis your deployment name, not the stringMAI-Thinking-1. A 404 usually means the two were confused.max_completion_tokens, notmax_tokens. The older parameter returns a 400 error, and the limit includes reasoning tokens, so a small value cuts the visible answer short.- Reasoning is returned encrypted, on request. Set
reasoning_displaytoencryptedand the assistant message carries an opaquereasoning.encrypted_contentvalue. Send the whole assistant message back unchanged on the next turn so the model keeps the reasoning it already did. Any change invalidates the blob, and it counts toward the context window. Microsoft’s guidance is not to inspect, decode, log or display it.
Content safety runs on input and output. A blocked prompt returns HTTP 400 before generation. On a streamed response, output safety can stop generation midway: the client receives the chunks so far, then an error event with SafetyBlockedError, then [DONE]. Treat a truncated stream that ends in an error event as an expected case, not a crash.
Coding, image and speech models
Section titled “Coding, image and speech models”MAI-Code is not an API product you deploy. It is a model you select in GitHub Copilot or Copilot Code, where it sits beside OpenAI, Anthropic and Google models. Copilot Business and Enterprise administrators enable it through a model policy. Its value is speed and cost inside the editor for completions, edits and test generation, so evaluate it the way you evaluate any model in the picker: on your own repository’s tasks.
MAI-Image models generate an image from text and edit images using up to five JPEG or PNG references, returning one PNG as base64. The prompt context is 32,000 tokens and English only. Each image must be at least 768 pixels on each side; the total pixel count is capped at 1,048,576 for 2.5 models and 2,359,296 for 2.6 models, which also add auto_aspect_ratio and web_grounding parameters. Photorealistic edits involving minors are blocked by default.
MAI-Transcribe-2 covers 60 languages (1.5 covers fewer) with speaker diarization, word-level timestamps, keyword biasing through a phrase list, automatic language detection, code switching, and a choice of verbatim or clean transcripts. You call it through the Azure Speech fast transcription API by setting enhancedMode.enabled to true and enhancedMode.model to MAI-Transcribe-2.
MAI-Voice-2.1 and MAI-Voice-2.1-Flash are text-to-speech models with prebuilt voices in 23 languages and emotion control through SSML. Flash targets low-latency voice agents and IVR flows; 2.1 targets long-form narration where quality matters more than latency. You choose the model with a suffix on the voice name, for example en-US-Harper:MAI-Voice-2.1. Instant voice cloning from a 5 to 60 second clip exists but is gated behind a limited-access review, and only consented, licensed voices can be synthesized.
Running the sample
Section titled “Running the sample”The sample below uses the openai Python package (3.51.0, Python 3.11) pointed at a Foundry endpoint, as Microsoft’s own examples do. It requires a Foundry deployment and an API key and was not executed against Azure. It was run against a mocked HTTP transport that returned two chat completion responses, which confirmed the URL, the api-key header, the reasoning_display field and that the second request carries the first turn’s reasoning blob back. Set AZURE_ENDPOINT, AZURE_API_KEY and DEPLOYMENT_NAME, then run python mai_dispute.py.
Worked example: an OrdersPortal dispute reviewer
Section titled “Worked example: an OrdersPortal dispute reviewer”An invented shop, OrdersPortal, wants a model to triage refund disputes. The decision is multi-step (delivery evidence, customer history, carrier updates), and new evidence often arrives as a follow-up, so the conversation is multi-turn and benefits from keeping the model’s earlier reasoning.
# mai_dispute.py - ask MAI-Thinking-1 (preview) to assess an OrdersPortal refund dispute# Requires a Foundry deployment and key; not executed against Azure.import osfrom openai import OpenAI
client = OpenAI( base_url=f"{os.environ['AZURE_ENDPOINT']}/mai/v1", # https://<resource>.services.ai.azure.com api_key="unused", # key goes in the api-key header instead default_headers={"api-key": os.environ["AZURE_API_KEY"]},)
def assess(history: list[dict]) -> dict: response = client.chat.completions.create( model=os.environ["DEPLOYMENT_NAME"], # your deployment name, not "MAI-Thinking-1" messages=history, max_completion_tokens=8000, # includes reasoning tokens; 64K cap extra_body={"reasoning_display": "encrypted"}, # MAI extension: return reasoning state ) choice = response.choices[0] if choice.finish_reason == "length": raise RuntimeError("truncated: raise max_completion_tokens") if choice.finish_reason != "stop": raise RuntimeError(f"no usable answer: {choice.finish_reason}") print(choice.message.content) print("tokens:", response.usage.prompt_tokens, response.usage.completion_tokens) # Keep the whole assistant message, including the opaque reasoning blob, for the next turn return choice.message.model_dump(exclude_none=True)
history = [ {"role": "system", "content": "You review OrdersPortal refund disputes. Answer APPROVE, REJECT or ESCALATE, then one sentence of reasons."}, {"role": "user", "content": "Order A1001: customer says the parcel never arrived. Carrier shows delivered, no photo. Customer has 2 prior disputes in 12 months, both approved."},]history.append(assess(history))history.append({"role": "user", "content": "The carrier has now confirmed the parcel was left at the wrong address."})history.append(assess(history))Output from the mocked run (the answers are scripted, the request handling is real):
ESCALATE. Delivered status without proof, but the history of approved disputes needs a person to review it.tokens: 96 412APPROVE. The carrier confirmed a misdelivery, so the customer is not at fault.tokens: 96 412What the example teaches:
- Persisting history means persisting the blob. If OrdersPortal stores conversations in a database between turns, the stored assistant message must include
reasoning.encrypted_contentbyte for byte. Rebuilding the message fromcontentalone silently drops the reasoning. - The blob is not an audit trail. It is opaque by design. If reviewers need to know why a dispute was approved, ask the model for a short stated rationale in the answer, as the system prompt does here, and store that.
- Completion tokens dwarf the prompt. Reasoning is billed as output. Measure
completion_tokenson real disputes before sizing quota, because the default Low tier has no quota at all.
Choosing MAI or another model in Foundry
Section titled “Choosing MAI or another model in Foundry”A Foundry resource can deploy MAI models, Azure OpenAI models and partner models side by side, so the question is rarely “MAI or not” but “which deployment for this workload”.
| Choose | When |
|---|---|
| MAI-Thinking-1 | Your evaluation shows it passes on the task, the workload tolerates preview terms, and you want a Microsoft-trained model billed and supported through Azure |
| A generally available Azure OpenAI or partner model | You need an SLA, provisioned throughput, a longer context than 256K, image input, or a feature MAI-Thinking-1 lacks today (only function tools are supported) |
model-router |
You want Foundry to pick among underlying models per request and accept less control over which one answers |
| A Phi model | The task is narrow and you want a small model, possibly on your own hardware; see Microsoft small language models |
The cross-provider method (category, then tier, then effort, then a graded test set) is on LLM model selection. It applies unchanged to MAI.
Trade-offs
Section titled “Trade-offs”| Factor | MAI models | Hosted third-party models in the same resource |
|---|---|---|
| Vendor relationship | One vendor for model, hosting, billing and support | Same Azure billing, but the model’s behavior and roadmap belong to its maker |
| Maturity | Mostly preview in November 2026; versions change every few weeks | Many generally available, with SLAs and longer lifecycle records |
| Capacity options | Global Standard only for MAI-Thinking-1 | Often Data Zone, regional and provisioned options as well |
| API shape | OpenAI-compatible chat completions plus MAI extensions (/mai/v1) |
Azure OpenAI APIs or the model’s own schema |
| Ecosystem fit | Built into GitHub Copilot, Copilot Code and Azure Speech | Broader community knowledge, prompts and tooling |
Failure modes and operations
Section titled “Failure modes and operations”- Deploying into zero quota. The default Low tier for MAI-Thinking-1 is 0 TPM. A deployment that succeeds can still return 429 on every call until you request a higher tier.
- Treating preview as production. Preview models come without an SLA and can change behavior or be withdrawn. Microsoft’s own guidance is not to use them for production workloads.
- Mid-stream safety stops. Streamed answers can end with a
SafetyBlockedErrorevent. UI code that only expects[DONE]shows a half-finished answer as complete. - Losing reasoning between turns. Serializing only
content, or a framework that rebuilds messages, dropsreasoning.encrypted_content. Quality degrades without any error. - Version drift. MAI-Code-1-Flash lasted about three months in Copilot, and MAI-Transcribe-1 was deprecated within months. Pin the version you evaluated, keep it in configuration, and watch the deprecation notes.
- Wrong parameter names.
max_tokensand non-function tools return 400 errors on MAI-Thinking-1. - Voice cloning without consent records. Gated access requires recorded consent from the speaker. Build the consent store before the feature, not after legal asks.
When not to use MAI models
Section titled “When not to use MAI models”- You need an SLA today. Most of the family is in preview; pick a generally available model and revisit later.
- The workload needs provisioned throughput or a data-zone deployment that MAI-Thinking-1 does not offer.
- You need image input to a reasoning model. MAI-Thinking-1 is text only.
- You want the newest MAI-Code for a non-GitHub tool. It is not offered as a general API in November 2026.
- A smaller model already passes. If a Phi model or a fast tier from another provider meets your graded test set, a reasoning model adds latency and cost for nothing.
Interview questions
Section titled “Interview questions”1. What is the MAI family, and how is it different from Azure OpenAI?
MAI models are trained by Microsoft AI. Azure OpenAI models are OpenAI’s models hosted and sold by Microsoft. Both can live in one Foundry resource and are billed through Azure, but they differ in maker, API surface (MAI-Thinking-1 uses an OpenAI-compatible endpoint under /mai/v1), release status and lifecycle.
2. Why does MAI-Thinking-1 return its reasoning encrypted, and what do you do with it?
The model’s chain of thought stays opaque while still letting later turns benefit from it. You request it with reasoning_display: "encrypted", store the full assistant message unchanged, and send it back on the next turn. You never decode, log or edit it, and you budget for it in the 256K context.
3. A streamed MAI-Thinking-1 answer stops halfway with no finish_reason. What happened and how should the client react?
Most likely output safety stopped generation: the stream ends with an error event of type SafetyBlockedError and then [DONE]. The client should mark the answer as incomplete, not show it as final, log the event, and offer a retry or a fallback path.
4. Senior scenario: OrdersPortal’s architecture board wants to move its dispute assistant from a generally available model to MAI-Thinking-1 because the evaluation scores are slightly better and it simplifies vendor management. What do you recommend? Separate the quality result from the operational readiness. MAI-Thinking-1 is in preview: no SLA, a Global Standard deployment only, no provisioned throughput and a default quota of zero. Run it in shadow mode first: send a copy of live disputes to it, compare decisions with the current model and with human outcomes, and measure completion tokens, latency and 429s at real volume. If it holds up, route a small share of low-risk disputes to it behind a flag, with the current model as automatic fallback on errors, safety stops or quota exhaustion. Fix the conversation store so the encrypted reasoning survives between turns, and keep the human escalation path. Make the full switch only when the model reaches general availability or the business explicitly accepts preview terms in writing, and record the decision with a review date because MAI versions change quickly.
Key takeaways
Section titled “Key takeaways”- MAI is Microsoft’s own model family: Thinking, Code, Image, Transcribe and Voice, each offered through a different surface.
- In November 2026 most MAI models are in preview; plan quotas, fallbacks and SLAs around that.
- MAI-Thinking-1 is OpenAI SDK-compatible at
/mai/v1, with a 256K context, a 64K output cap and encrypted reasoning that must be passed back unchanged. - MAI-Code is chosen inside GitHub Copilot and Copilot Code, not deployed as an API.
- Versions turn over in weeks; keep model names and versions in configuration and re-evaluate on each change.
Related pages
Section titled “Related pages”- LLM model selection
- Microsoft small language models
- OpenAI models and Anthropic models
- Microsoft Copilot (chat app)
- GitHub Copilot
- AI models in 2026
Official references
Section titled “Official references”Checked on November 16, 2026. MAI models change often; verify before production decisions.
- Foundry Models sold by Azure: Microsoft models
- Deploy and use MAI-Thinking-1 in Microsoft Foundry (preview)
- Deploy and use MAI image models in Microsoft Foundry (preview)
- MAI-Transcribe in Azure Speech
- MAI-Voice in Azure Speech
- Region availability for Foundry Models sold by Azure
- GitHub Copilot: supported AI models and model retirement history
- Copilot Code: get started (model choice)