Implantar e usar modelos de imagem MAI no Microsoft Foundry (versão prévia)

Os modelos de imagem MAI são uma família de modelos de imagem desenvolvidos pela Microsoft AI que oferecem geração de imagens a partir de texto de última geração e, em alguns modelos, edições de imagem para imagem. Esses modelos são oferecidos como parte do Microsoft Foundry Models, comercializado pelo Azure, proporcionando acesso seguro de nível empresarial por meio do Microsoft Foundry.

Neste artigo, você aprenderá a:

  • Implantar modelos de imagem MAI no Microsoft Foundry
  • Autenticar usando Microsoft Entra ID ou chaves de API
  • Gerar imagens usando a API de gerações de imagem MAI
  • Faça uma edição de imagem usando a API de edição de imagens do MAI

Os modelos de imagem MAI no Microsoft Foundry incluem:

Nome do modelo Versão do modelo Tipo
MAI-Image-2.5-Flash (Versão prévia) 2026-06-02 Geração de texto para imagem
Edições de imagem a imagem
MAI-Image-2.5 (Versão prévia) 2026-06-02 Geração de texto para imagem
Edições de imagem a imagem
MAI-Image-2e (Versão prévia) 2026-04-09 Geração de texto para imagem
MAI-Image-2 (Versão prévia) 2026-02-20 Geração de texto para imagem

Para saber mais sobre os modelos individuais, consulte Modelos de imagem MAI disponíveis.

Pré-requisitos

  • Uma assinatura Azure com uma forma de pagamento válida. Se você não tiver uma assinatura de Azure, crie uma conta de Azure paga .
  • Acesso ao Microsoft Foundry com permissões apropriadas para criar e gerenciar recursos.
  • Um projeto Microsoft Foundry. Os modelos de imagem MAI estão disponíveis para implantação global padrão (Centro-Oeste dos EUA, Leste dos EUA, Oeste dos EUA, Europa Ocidental, Suécia Central, Sul da Índia e Norte dos Emirados Árabes Unidos).
  • A função de Colaborador dos Serviços Cognitivos no recurso Fábrica de IA do Azure para implantar modelos. Para obter mais informações, consulte funções do Azure RBAC.

Implantar modelos de imagem MAI

Para implantar um modelo de imagem MAI, siga as instruções em Deploy Microsoft Foundry Models no portal do Foundry.

Como alternativa, você pode implantar o modelo usando o CLI do Azure. O código a seguir mostra a implantação de MAI-Image-2.5 Para implantar um modelo diferente, substitua o nome do modelo e a versão nas linhas --model-name MAI-Image-2.5 e --model-version 2026-06-02 pelos valores do modelo desejado.

Substitua <ACCOUNT_NAME>, <RESOURCE_GROUP> e <DEPLOYMENT_NAME> pelos seus valores.

az cognitiveservices account deployment create \
  --name <ACCOUNT_NAME> \
  --resource-group <RESOURCE_GROUP> \
  --deployment-name <DEPLOYMENT_NAME> \
  --model-name "MAI-Image-2.5" \
  --model-format Microsoft \
  --model-version 2026-06-02 \
  --sku-name GlobalStandard \
  --sku-capacity 1

Referência:az cognitiveservices account deployment create

Para listar todas as implantações disponíveis em seu recurso:

az cognitiveservices account deployment list \ 
  --resource-group <RESOURCE_GROUP> \ 
  --name <ACCOUNT_NAME> \ 
  -o table

Referência:az cognitiveservices account deployment list

Após a implantação, use o playground do Foundry para testar interativamente o modelo.

Executar geração de texto em imagem

O exemplo a seguir mostra como gerar uma imagem de um prompt de texto usando um modelo de imagem MAI com a API de gerações de imagem MAI.

Usar autenticação de chave de API

  1. Instale a requests biblioteca:

    pip install requests

  2. Definir variáveis de ambiente:

    export AZURE_ENDPOINT="https://<resource-name>.services.ai.azure.com"
export AZURE_API_KEY="<your-api-key>"
export DEPLOYMENT_NAME="<your-deployment-name>"

  3. Execute o seguinte código:

    import os
import base64
import requests

endpoint = os.environ["AZURE_ENDPOINT"]
api_key = os.environ["AZURE_API_KEY"]
deployment_name = os.environ["DEPLOYMENT_NAME"]

width = 1024
height = 1024

url = f"{endpoint}/mai/v1/images/generations"

payload = {
    "model": deployment_name,
    "prompt": "A photorealistic concept art poster of a university at sunset, cinematic lighting",
    "width": width,
    "height": height
}

response = requests.post(
    url,
    headers={
        "Content-Type": "application/json",
        "api-key": api_key,
    },
    json=payload,
)
response.raise_for_status()

result = response.json()
print(result)

image_data = [
    output
    for output in result.get("data", [])
    if "b64_json" in output
]

if image_data:
    image_base64 = image_data[0]["b64_json"]
    output_path = "output.png"
    with open(output_path, "wb") as f:
        f.write(base64.b64decode(image_base64))
    print(f"Image saved to {output_path}")
else:
    print("Unexpected response format:", result)

    Saída esperada: Uma resposta JSON que contém os dados de imagem gerados no formato base64. A imagem é decodificada e salva como output.png no diretório atual.

Usar a autenticação do Microsoft Entra ID

Para usar Microsoft Entra ID em vez de uma chave de API, substitua o cabeçalho api-key por um token de portador obtido usando o DefaultAzureCredential:

  1. Instale a biblioteca de identidade do Azure:

    pip install azure-identity

  2. Atualize os cabeçalhos de solicitação no código de autenticação de chave de API:

    from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
)
token = token_provider()

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}",
}

    Reference:DefaultAzureCredential

Executar uma edição de imagem para imagem

O exemplo a seguir mostra como executar uma edição de imagem para imagem usando um modelo de imagem MAI com a API de edições de imagem MAI.

MAI-Image-2.5-Flash (Versão prévia) e MAI-Image-2.5 (versão prévia) dão suporte a edições de imagem para imagem usando a API de edições de imagem.

Nota

As solicitações de edições de imagem para imagem usam dados de formulário de várias partes.

Usar autenticação de chave de API

  1. Instale a requests biblioteca:

    pip install requests

  2. Definir variáveis de ambiente:

    export AZURE_ENDPOINT="https://<resource-name>.services.ai.azure.com"
export AZURE_API_KEY="<your-api-key>"
export DEPLOYMENT_NAME="<your-deployment-name>"

  3. Execute o seguinte código:

    import os
import base64
import requests

endpoint = os.environ["AZURE_ENDPOINT"]
api_key = os.environ["AZURE_API_KEY"]
deployment_name = os.environ["DEPLOYMENT_NAME"]

width = 1024
height = 1024

url = f"{endpoint}/mai/v1/images/edits"

# Replace the file name and type.
reference_image = <path_to_your_image.png>
image_type = "image/png" # or "image/jpeg" based on format of your image. 

files = [
    ("image", (reference_image, open(reference_image, "rb"), image_type))
]

payload={
    "model": deployment_name,
    "prompt": "Turn this image into a clean futuristic product shot with studio lighting",
}

response = requests.post(
    url,
    headers={
        "api-key": api_key,
    },
    data=payload,
    files=files
)

response.raise_for_status()

result = response.json()
print(result)


image_data = [
    output
    for output in result.get("data", [])
    if "b64_json" in output
]

if image_data:
    image_base64 = image_data[0]["b64_json"]
    output_path = "output.png"
    with open(output_path, "wb") as f:
        f.write(base64.b64decode(image_base64))
    print(f"Image saved to {output_path}")
else:
    print("Unexpected response format:", result)

    Saída esperada: Uma resposta JSON que contém os dados de imagem editados no formato base64. A imagem é decodificada e salva como output.png no diretório atual.

Para usar o Microsoft Entra ID em vez de uma chave de API, modifique esse código conforme descrito na seção anterior: Usar a autenticação do Microsoft Entra ID.

Modelos de imagem MAI disponíveis

A Foundry dá suporte ao uso de MAI-Image-2.5-Flash (versão prévia), MAI-Image-2.5 (versão prévia), MAI-Image-2 (versão prévia) e MAI-Image-2e (versão prévia). Cada um desses modelos é adequado para os seguintes casos de uso principais:

  • Geração de texto para imagem: Gere imagens de alta qualidade a partir de prompts de linguagem natural, permitindo que os usuários traduzam descrições textuais em saídas visualmente coerentes adequadas para uma ampla gama de casos de uso criativos e de design.
  • Síntese de imagem fotorealista: Capaz de gerar imagens realistas com estrutura visual consistente, tornando-a adequada para cenários de visualização de conceito e criação de conteúdo.
  • Produto, identidade visual e design comercial: Adequado para imagens de produtos, visuais de marketing, ativos de marca e fluxos de trabalho criativos comerciais.

MAI-Image-2.5-Flash (versão prévia) e MAI-Image-2.5 (versão prévia) se destacam ainda mais nestes principais casos de uso:

  • Edição de imagem para imagem: Dê suporte a edições precisas e controláveis em imagens existentes, incluindo remoção de objeto, substituição, alterações de atributo, pintura, atualizações de texto e limpeza de artefatos, preservando a composição e o layout.
  • Retratos de alta fidelidade: Gere retratos expressivos de aparência natural com estrutura facial precisa, iluminação e textura.
  • Renderização de texto precisa: Renderização aprimorada de texto em imagens geradas, incluindo rótulos, cartazes, empacotamento e sinalização.
  • Raciocínio visual: Raciocine sobre objetos, a estrutura da cena, a iluminação, a escala e o posicionamento espacial para produzir resultados consistentes, mesmo a partir de prompts ambíguos.

Para obter mais detalhes sobre as capacidades do modelo, consulte as capacidades dos modelos da Microsoft nos Modelos do Foundry vendidos pelo Azure.

MAI-Image-2.5-Flash (versão prévia)

MAI-Image-2.5-Flash (Versão prévia) é um modelo de edição de geração de texto para imagem e imagem para imagem projetado para criar imagens de alta qualidade e visualmente ricas a partir de prompts de linguagem natural e para executar edições precisas e controláveis em imagens existentes. Ele usa uma abordagem generativa baseada em difusão para refinar progressivamente as imagens, permitindo um forte alinhamento entre o texto de entrada e a saída gerada. O modelo é otimizado para produzir imagens diversas e coerentes em uma ampla gama de cenários criativos e de design, tornando-o adequado para tarefas como visualização de conceito, geração de conteúdo criativo, fluxos de trabalho de edição de imagem e design de produção.

MAI-Image-2.5 (versão prévia)

MAI-Image-2.5 (Versão prévia) é um modelo de edição de geração de texto para imagem e imagem para imagem projetado para criar imagens de alta qualidade e visualmente avançadas de prompts de linguagem natural e para executar edições precisas e controláveis em imagens existentes. Ele usa uma abordagem generativa baseada em difusão para refinar progressivamente as imagens, permitindo um forte alinhamento entre o texto de entrada e a saída gerada. O modelo se destaca em edições precisas e cirúrgicas com consistência, permitindo que usuários e desenvolvedores façam edições direcionadas em objetos, adaptem layouts, atualizem texto, removam artefatos como desfoque de movimento e preservem a consistência visual ao longo das iterações.

MAI-Image-2e (versão prévia)

MAI-Image-2e (versão prévia) oferece geração de imagem de alta qualidade, assim como MAI-Image-2, mas até 22% mais rápido e quatro vezes mais eficiente do que MAI-Image-2, tornando-se uma opção inteligente para desenvolvedores que criam em escala. MAI-Image-2e é mais adequado para cenários de alta volume e rápida reviravolta, por exemplo, imagens de produto em escala, variações de marketing, ativos de marca ou qualquer fluxo de trabalho em que a eficiência e o custo por imagem sejam fundamentais.

MAI-Image-2 (versão prévia)

MAI-Image-2 (Versão prévia) é um modelo de geração de texto para imagem projetado para criar imagens de alta qualidade e visualmente avançadas a partir de prompts de linguagem natural. Ele usa uma abordagem generativa baseada em difusão para refinar progressivamente as imagens, permitindo um forte alinhamento entre o texto de entrada e a saída gerada. O modelo é otimizado para produzir imagens diversas e coerentes em uma ampla gama de cenários criativos e de design, tornando-o adequado para tarefas como visualização de conceito, geração de conteúdo criativo e fluxos de trabalho de design de imagem.

Endpoints de API

Depois de implantar um modelo de imagem MAI, use a API de geração de imagens MAI para gerar imagens e a API de edição de imagens MAI para edições de imagem para imagem.

  • Endpoint da API de geração de imagens: um endpoint gerenciado pela Microsoft que aceita um prompt de texto e retorna uma imagem PNG. O ponto de extremidade da API tem o seguinte formato:

    https://<resource-name>.services.ai.azure.com/mai/v1/images/generations

  • Image edita o ponto de extremidade da API: um ponto de extremidade gerenciado por Microsoft que aceita uma imagem JPEG ou PNG e retorna uma imagem PNG. O ponto de extremidade da API tem o seguinte formato:

    https://<resource-name>.services.ai.azure.com/mai/v1/images/edits

Para autenticar, você precisa do seu endpoint de recurso e de um token Microsoft Entra ID ou de uma chave API. Você pode encontrar esses valores na seção Keys e Endpoint do recurso no portal do Azure ou na página de detalhes da implantação no portal Foundry.

Parâmetros de solicitação

A tabela a seguir lista os parâmetros de solicitação para as APIs de imagem:

Parâmetro API Tipo Descrição
model Ambas cadeia O nome da implantação que você atribuiu ao implantar o modelo.
prompt Ambas cadeia O prompt de texto que descreve a imagem a ser gerada ou as edições a serem feitas.
Comprimento máximo do contexto: 32.000 símbolos.
image Edições de imagem cadeia O caminho para a imagem que você deseja editar. A imagem é enviada como multipart/form-data. Deve estar no formato JPEG ou PNG.
width Gerações de imagens inteiro Largura da imagem de saída em pixels.
Mínimo: 768. O produto de width × height não deve exceder 1.048.576.
height Gerações de imagens inteiro Altura da imagem de saída em pixels.
Mínimo: 768. O produto de width × height não deve exceder 1.048.576.

Nota

O formato de saída é sempre PNG. A contagem total máxima de pixels é de 1.048.576 (equivalente a 1024×1024). Ambos width e height devem ter pelo menos 768 pixels cada. Qualquer dimensão pode exceder 1024, desde que a contagem total de pixels permaneça dentro do limite.

Cotas e limites de API

Os modelos de imagem MAI têm os seguintes limites de taxa medidos em RPM (Solicitações por Minuto). A camada disponível para você depende da sua assinatura e da configuração de implantação.

Tipo de implantação Camada MAI-Image-2.5-Flash
(RPM)		 MAI-Image-2.5
(RPM)		 MAI-Image-2e
(RPM)		 MAI-Image-2
(RPM)
Padrão Global 0
(Gratuito)		 0 0 0 0
Padrão Global 1 2 2 18 9
Padrão Global 2 4 4 30 15
Padrão Global 3 6 6 60 30
Padrão Global 4 8 8 90 45
Padrão Global 5 10 10 120 60
Padrão Global 6 12 12 180 90

Para solicitar um aumento de cota, envie o formulário de solicitação de aumento de cota. As solicitações são processadas na ordem em que são recebidas e a prioridade vai para os clientes que usam ativamente sua alocação de cota existente.

Solucionar problemas

Use a tabela a seguir para resolver erros comuns ao trabalhar com modelos de imagem MAI:

Erro Causa Corrigir
401 Unauthorized Chave de API inválida ou token expirado Regenerar a chave no portal Azure. Para a autenticação do Entra ID, verifique se o escopo do token é https://cognitiveservices.azure.com/.default.
404 Not Found Nome de implantação ou URL de ponto de extremidade incorretos Verifique o nome da implantação e o ponto de extremidade no portal do Foundry em Implantações.
400 Bad Request width ou height abaixo do mínimo, ou a contagem total de pixels excede o máximo Verifique width e height cada um tenha pelo menos 768, e que width × height ≤ 1.048.576.
429 Too Many Requests Limite de taxa excedido Aguarde e tente novamente ou solicite um aumento de cota.

Considerações sobre IA responsável

Ao usar modelos de imagem MAI no Foundry, considere estas práticas de IA responsáveis:

  • Esteja ciente das limitações conhecidas: Apesar das mitigações técnicas, como filtragem de dados e classificadores de conteúdo aplicados no nível do sistema, os modelos de geração de imagem podem produzir conteúdo prejudicial ou inesperado com base em solicitações do usuário. As áreas de risco comuns incluem conteúdo violento ou peludo, conteúdo sexual ou nudez, representações de figuras públicas e replicação de material registrado ou outro material protegido.
  • Configurar a segurança de conteúdo: aplique mitigações adicionais apropriadas ao seu caso de uso, pois nenhum modelo generativo é imune a prompts adversários.
  • Cumpra os termos aplicáveis: Certifique-se de que o uso de imagens geradas está em conformidade com os termos de serviço da Microsoft e as leis de direitos autorais e de propriedade intelectual aplicáveis.
  • Seja transparente: divulgue que o conteúdo é gerado por IA ao compartilhar ou publicar imagens.
  • Evite conteúdo prejudicial: não gere conteúdo que possa ser prejudicial, enganoso ou que viole a privacidade.

Conteúdo relacionado

  • Last updated on