通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

如何使用 Azure OpenAI 映像生成模型

OpenAI 的图像生成模型基于用户提供的文本提示和可选图像创建图像。 本文介绍如何使用这些模型、配置选项以及从 Azure 中的高级图像生成功能中获益。

Prerequisites

概述

方面 GPT-Image-1 DALL·E 3
输入/输出形式和格式 接受 文本 + 图像 输入;仅输出 base64 中的图像（无 URL 选项）。 接受 文本（主）输入; 有限的图像编辑输入（带有掩码）。 输出为 URL 或 base64。
图像大小/分辨率 1024×1024、1024×1536、1536×1024 1024×1024、1024×1792、1792×1024
质量选项 low medium 、high（默认值 = 高） standard、样式hd选项：natural、vivid
每个请求的图像数 每个请求 1-10 个图像（n 参数） 每个请求只有 1 个图像 （n 必须为 1）
编辑（修复/变体） 是 - 支持使用掩码 + 提示进行修复和变体 是 - 支持修复和变体
优势 具备更高的提示保真度、更强的现实感、能够利用多模态上下文，并在编辑与指令遵循方面表现突出 强于快速遵从，自然文本呈现，风格多样，图像生成连贯。

调用图像生成 API

以下命令显示了将图像模型用于代码的最基本方法。 如果这是你第一次以编程方式使用这些模型，请从快速入门开始。

将 POST 请求发送到：

https://<your_resource_name>.openai.azure.com/openai/deployments/<your_deployment_name>/images/generations?api-version=<api_version>

URL:

请替换以下值：

  • <your_resource_name> 是 Azure OpenAI 资源的名称。
  • <your_deployment_name> 是 DALL-E 3 或 GPT-image-1 模型部署的名称。
  • <api_version> 是要使用的 API 版本。 例如，2025-04-01-preview。

所需的标头：

  • Content-Type: application/json
  • api-key: <your_API_key>

Body:

下列为请求正文示例。 指定了许多选项，这些选项将在后面的部分中定义。

{
    "prompt": "A multi-colored umbrella on the beach, disposable camera",
    "model": "gpt-image-1",
    "size": "1024x1024", 
    "n": 1,
    "quality": "high"
}

Tip

有关映像生成令牌成本，请参阅 映像令牌。

Output

成功的图像生成 API 调用的响应如以下示例所示。 该 b64_json 字段包含输出图像数据。

{ 
    "created": 1698116662, 
    "data": [ 
        { 
            "b64_json": "<base64 image data>"
        }
    ]
}

Note

GPT-image-1 不支持 response_format 参数，该参数始终返回 base64 编码的图像。

Streaming

可以通过将gpt-image-1参数设置为stream，将true参数设置为介于0和3之间的值，来向partial_images流式传输图像生成请求。

import base64
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

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

client = OpenAI(  
  base_url = "https://RESOURCE-NAME-HERE/openai/v1/",  
  api_key=token_provider,
  default_headers={"api_version":"preview"}
)

stream = client.images.generate(
    model="gpt-image-1",
    prompt="A cute baby sea otter",
    n=1,
    size="1024x1024",
    stream=True,
    partial_images = 2
)

for event in stream:
    if event.type == "image_generation.partial_image":
        idx = event.partial_image_index
        image_base64 = event.b64_json
        image_bytes = base64.b64decode(image_base64)
        with open(f"river{idx}.png", "wb") as f:
            f.write(image_bytes)

API 调用拒绝

根据我们的内容策略筛选提示和图像。 标记提示或图像时，API 返回错误。

如果提示已标记，则消息中的 error.code 值设置为 contentFilter。 下面是一个示例：

{
    "created": 1698435368,
    "error":
    {
        "code": "contentFilter",
        "message": "Your task failed as a result of our safety system."
    }
}

生成的图像本身也可能会被筛除。 在这种情况下，错误消息设置为“Generated image was filtered as a result of our safety system”。 下面是一个示例：

{
    "created": 1698435368,
    "error":
    {
        "code": "contentFilter",
        "message": "Generated image was filtered as a result of our safety system."
    }
}

编写有效的文本到图像提示

提示应描述要在图像中看到的内容，以及图像的视觉样式。

编写提示时，请考虑图像 API 附带内容审查筛选功能。 如果服务将你的提示识别为有害内容，则不会生成图像。 有关详细信息，请参阅 内容筛选。

Tip

若要全面了解如何调整文本提示以生成不同类型的图像，请参阅 图像提示工程指南。

指定 API 选项

以下 API 正文参数可用于图像生成模型。

Size

指定生成的图像的大小。 对于 GPT-image-1 模型，必须是 1024x1024、1024x1536 或 1536x1024。 方形图像的生成速度更快。

Quality

图像质量有三个选项：low、medium 和 high。 可以更快地生成质量较低的图像。

默认值是 high。

Number

可以在单个 API 调用中生成一到 10 个图像。 默认值是 1。

用户 ID

使用 用户 参数为发出请求的用户指定唯一标识符。 此标识符可用于跟踪和监视使用模式。 该值可以是任何字符串，例如用户 ID 或电子邮件地址。

输出格式

使用 output_format 参数指定生成的图像的格式。 支持的格式是 PNG 和 JPEG。 默认值为 PNG。

Note

Azure AI Foundry 模型中的 Azure OpenAI 不支持 WEBP 图像。

Compression

使用 output_compression 参数指定生成的映像的压缩级别。 在两者之间输入一个整数0100，其中0没有压缩，并且100是最大压缩。 默认值为 100。

Streaming

使用 流 参数启用流式处理响应。 设置为 true 时，API 会在生成部分图像时返回这些图像。 此功能可为用户提供更快的视觉反馈，并降低感知到的延迟。 设置 partial_images 参数来控制生成的部分图像数（1-3）。

调用图像编辑 API

使用图像编辑 API，可以根据提供的文本提示修改现有图像。 API 调用类似于图像生成 API 调用，但还需要提供输入图像。

Important

输入图像的大小必须小于 50 MB，并且必须是 PNG 或 JPG 文件。

Important

gpt-image-1-mini 当前不支持图像编辑。

将 POST 请求发送到：

https://<your_resource_name>.openai.azure.com/openai/deployments/<your_deployment_name>/images/edits?api-version=<api_version>

URL:

请替换以下值：

  • <your_resource_name> 是 Azure OpenAI 资源的名称。
  • <your_deployment_name> 是 DALL-E 3 或 GPT-image-1 模型部署的名称。
  • <api_version> 是要使用的 API 版本。 例如，2025-04-01-preview。

所需的标头：

  • Content-Type: multipart/form-data
  • api-key: <your_API_key>

Body:

下列为请求正文示例。 指定了许多选项，这些选项将在后面的部分中定义。

Important

图像编辑 API 采用多部分/表单数据，而不是 JSON 数据。 下面的示例显示了将附加到 cURL 请求的示例表单数据。

-F "image[]=@beach.png" \
-F 'prompt=Add a beach ball in the center' \
-F "model=gpt-image-1" \
-F "size=1024x1024" \
-F "n=1" \
-F "quality=high"

API 响应输出

成功图像编辑 API 调用的响应如以下示例所示。 该 b64_json 字段包含输出图像数据。

{ 
    "created": 1698116662, 
    "data": [ 
        { 
            "b64_json": "<base64 image data>"
        }
    ]
}

指定图像编辑 API 选项

除了可用于图像生成模型之外，以下 API 正文参数还可用于图像编辑模型。

图像

图像值指示要编辑的图像文件。

输入保真度

input_fidelity 参数控制模型在匹配输入图像的样式和特征（尤其是面部特征）时所投入的工作量。

使用此参数可以对图像进行细微编辑，而无需更改不相关的区域。 使用高输入保真度时，人脸的保留比标准模式更为准确。

Important

模型不支持 gpt-image-1-mini 输入保真度。

Mask

mask 参数使用与主 image 输入参数相同的类型。 它通过在这些区域使用完全透明的像素（alpha 值为零）来定义图像中你希望模型编辑的区域。 掩码必须是 PNG 文件，并且具有与输入图像相同的尺寸。

Streaming

使用 流 参数启用流式处理响应。 设置为 true 时，API 会在生成部分图像时返回这些图像。 此功能可为用户提供更快的视觉反馈，并降低感知到的延迟。 设置 partial_images 参数来控制生成的部分图像数（1-3）。

相关内容