Use the image generation tool (preview)

Create an agent with the image generation tool

This sample creates an agent with the image generation tool, generates an image, and saves it to a file. Select Prompt Agents to use the Azure AI Projects SDK to create a server-side prompt agent, or Hosted Agents to use the Agent Framework FoundryChatClient to build an ephemeral, in-process agent.

Use Python 3.9 or later for the prompt-agent sample. Install its dependencies:

python -m pip install azure-ai-projects azure-identity

Prompt agents

import base64
import os

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, ImageGenTool

# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
IMAGE_MODEL = "gpt-image-1"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Create an agent with the image generation tool
agent = project.agents.create_version(
    agent_name="agent-image-generation",
    definition=PromptAgentDefinition(
        model="gpt-5",
        instructions="Generate images based on user prompts.",
        tools=[ImageGenTool(model=IMAGE_MODEL, quality="low", size="1024x1024")],
    ),
    description="Agent for image generation.",
)
print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

# Generate an image using the agent
response = openai.responses.create(
    input="Generate an image of the Microsoft logo.",
    extra_headers={
        "x-ms-oai-image-generation-deployment": IMAGE_MODEL,
    },
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)

# Clean up the agent
project.agents.delete_version(agent_name=agent.name, agent_version=agent.version)

# Extract and save the generated image
image_data = [output.result for output in response.output if output.type == "image_generation_call"]
if image_data and image_data[0]:
    file_path = os.path.abspath("microsoft.png")
    with open(file_path, "wb") as f:
        f.write(base64.b64decode(image_data[0]))
    print(f"Image saved to: {file_path}")

Hosted agents

This sample uses FoundryChatClient from the Microsoft Agent Framework and calls get_image_generation_tool() to attach the image generation tool. Install the package with pip install agent-framework-foundry aiohttp, set the FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_MODEL environment variables, and sign in with az login.

import asyncio
import base64
import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

IMAGE_MODEL = "gpt-image-1"


async def main() -> None:
    agent = Agent(
        client=FoundryChatClient(credential=AzureCliCredential()),
        instructions="Generate images based on user prompts.",
        tools=[
            FoundryChatClient.get_image_generation_tool(
                model=IMAGE_MODEL,
                quality="low",
                size="1024x1024",
            )
        ],
    )

    result = await agent.run("Generate an image of the Microsoft logo.")

    # Extract and save the generated image from the raw response.
    for output in result.raw_representation.output:
        if output.type == "image_generation_call":
            file_path = os.path.abspath("microsoft.png")
            with open(file_path, "wb") as f:
                f.write(base64.b64decode(output.result))
            print(f"Image saved to: {file_path}")

    print(f"Agent: {result.text}")


if __name__ == "__main__":
    asyncio.run(main())

Expected output

The tool returns base64-encoded image bytes, which the sample saves to disk; the model's text reply is also printed:

Image saved to: /path/to/microsoft.png
Agent: Here is the generated Microsoft logo image.

For more about Agent Framework Foundry tool factories, see the Foundry provider samples.

Sample for image generation in Azure.AI.Extensions.OpenAI

In this example, you generate an image based on a simple prompt. The code in this example is synchronous. For an asynchronous example, see the sample code example in the Azure SDK for .NET repository on GitHub.

Use the .NET 8 SDK or later. Add the required packages to your project:

dotnet add package Azure.AI.Projects
dotnet add package Azure.AI.Extensions.OpenAI
dotnet add package Azure.Identity

using System;
using System.Collections.Generic;
using System.IO;
using System.Threading.Tasks;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Core;
using Azure.Core.Pipeline;
using Azure.Identity;

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
var projectEndpoint = "your_project_endpoint";
var imageModel = "gpt-image-1";

// Create the AI Project client with custom header policy
AIProjectClientOptions projectOptions = new();
projectOptions.AddPolicy(new HeaderPolicy(imageModel), PipelinePosition.PerCall);

// Create the AI Project client
AIProjectClient projectClient = new(
    endpoint: new Uri(projectEndpoint),
    tokenProvider: new DefaultAzureCredential(),
    options: projectOptions
);

// Use the client to create the versioned agent object.
// To generate images, we need to provide agent with the ImageGenerationTool
// when creating this tool. The ImageGenerationTool parameters include
// the image generation model, image quality and resolution.
// Supported image generation models include gpt-image-1.
DeclarativeAgentDefinition agentDefinition = new(model: "gpt-5")
{
Instructions = "Generate images based on user prompts.",
Tools = {
        ResponseTool.CreateImageGenerationTool(
            model: imageModel,
            quality: ImageGenerationToolQuality.Low,
            size:ImageGenerationToolSize.W1024xH1024
        )
    }
};
AgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
    agentName: "myAgent",
    options: new(agentDefinition));

ProjectOpenAIClient openAIClient = projectClient.GetProjectOpenAIClient();
ProjectResponsesClient responseClient = openAIClient.GetProjectResponsesClientForAgent(new AgentReference(name: agentVersion.Name));

ResponseResult response = responseClient.CreateResponse("Generate parody of Newton with apple.");

// Parse the ResponseResult object and save the generated image.
foreach (ResponseItem item in response.OutputItems)
{
    if (item is ImageGenerationCallResponseItem imageItem)
    {
        File.WriteAllBytes("newton.png", imageItem.ImageResultBytes.ToArray());
        Console.WriteLine($"Image downloaded and saved to: {Path.GetFullPath("newton.png")}");
    }
}

// Clean up resources by deleting the Agent.
projectClient.AgentAdministrationClient.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);

// To use image generation, provide the custom header to web requests,
// which contain the model deployment name, for example:
// `x-ms-oai-image-generation-deployment: gpt-image-1`.
// To implement it, create a custom header policy.
internal class HeaderPolicy(string image_deployment) : PipelinePolicy
{
    private const string image_deployment_header = "x-ms-oai-image-generation-deployment";

    public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
    {
        message.Request.Headers.Add(image_deployment_header, image_deployment);
        ProcessNext(message, pipeline, currentIndex);
    }

    public override async ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
    {
        // Add your desired header name and value
        message.Request.Headers.Add(image_deployment_header, image_deployment);
        await ProcessNextAsync(message, pipeline, currentIndex);
    }
}

Expected output

When you run the sample, you see the following output:

Agent created (id: <agent-id>, name: myAgent, version: 1)
Image downloaded and saved to: /path/to/newton.png
Agent deleted

Create an agent with the image generation tool

Use a Bash-compatible shell with Azure CLI, curl, jq, and a base64 command that supports --decode. Set FOUNDRY_PROJECT_ENDPOINT before you run the requests.

Get an access token:

export AGENT_TOKEN=$(az account get-access-token --scope "https://ai.azure.com/.default" --query accessToken -o tsv)

The following example creates an agent that uses the image generation tool.

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/agents?api-version=v1" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "name": "image-gen-agent",
    "description": "Test agent for image generation capabilities",
    "definition": {
      "kind": "prompt",
      "model": "gpt-5",
      "tools": [
        {
          "type": "image_generation"
        }
      ],
      "instructions": "You are a creative assistant that generates images when requested. Please respond to image generation requests clearly and concisely."
    }
  }'

Create a response

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "x-ms-oai-image-generation-deployment: gpt-image-1" \
  -d '{
    "agent": {
      "type": "agent_reference",
      "name": "image-gen-agent"
    },
    "input": [{
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Please generate small image of a sunset over a mountain lake."
        }
      ]
    }],
    "stream": false
  }'

Expected output

The response JSON includes an image_generation_call output item with a result field containing base64-encoded image data:

{
  "id": "resp_<id>",
  "status": "completed",
  "output": [
    {
      "type": "image_generation_call",
      "result": "<base64-encoded-image-data>",
      "status": "completed"
    },
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Here is the image of a sunset over a mountain lake."
        }
      ]
    }
  ]
}

To extract and save the image, pipe the response through jq and base64:

RESPONSE=$(curl -s -X POST "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "x-ms-oai-image-generation-deployment: gpt-image-1" \
  -d '{ ... }')

echo "$RESPONSE" | jq -r '.output[] | select(.type=="image_generation_call") | .result' \
  | base64 --decode > generated_image.png

Clean up the REST agent

Delete the agent after you save the generated image:

curl --request DELETE \
  --url "$FOUNDRY_PROJECT_ENDPOINT/agents/image-gen-agent?api-version=v1" \
  -H "Authorization: Bearer $AGENT_TOKEN"

Create an agent with image generation tool

This sample demonstrates how to create an AI agent with image generation capabilities by using the Azure AI Projects client. The agent generates images based on text prompts and saves them to files. For a JavaScript example, see the sample code in the Azure SDK for JavaScript repository on GitHub.

Use Node.js 22 or later. Install the required packages:

npm install @azure/ai-projects @azure/identity

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import * as fs from "fs";
import * as path from "path";
import { fileURLToPath } from "url";

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";
const IMAGE_MODEL = "gpt-image-1";

export async function main(): Promise<void> {
  // Create clients to call Foundry API
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  // Create Agent with image generation tool
  const agent = await project.agents.createVersion("agent-image-generation", {
    kind: "prompt",
    model: "gpt-5",
    instructions: "Generate images based on user prompts",
    tools: [
      {
        type: "image_generation",
        quality: "low",
        size: "1024x1024",
      },
    ],
  });
  console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

  // Generate image using the agent
  const response = await openai.responses.create(
    {
      input: "Generate an image of Microsoft logo.",
    },
    {
      body: { agent_reference: { name: agent.name, type: "agent_reference" } },
      headers: { "x-ms-oai-image-generation-deployment": IMAGE_MODEL },
    },
  );

  // Extract and save the generated image
  const imageData = response.output?.filter((output) => output.type === "image_generation_call");

  if (imageData && imageData.length > 0 && imageData[0].result) {
    const __filename = fileURLToPath(import.meta.url);
    const __dirname = path.dirname(__filename);
    const filename = "microsoft.png";
    const filePath = path.join(__dirname, filename);

    // Decode base64 and save to file
    const imageBuffer = Buffer.from(imageData[0].result, "base64");
    fs.writeFileSync(filePath, imageBuffer);

    console.log(`Image downloaded and saved to: ${path.resolve(filePath)}`);
  } else {
    console.log("No image data found in the response.");
  }

  // Clean up resources
  await project.agents.deleteVersion(agent.name, agent.version);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

Expected output

When you run the sample, you see the following output:

Agent created (id: <agent-id>, name: agent-image-generation, version: 1)
Image downloaded and saved to: /path/to/microsoft.png

Use image generation in a Java agent

Use JDK 17 or later and Maven 3.8 or later. Add the dependencies to your pom.xml:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-agents</artifactId>
    <version>2.2.0</version>
</dependency>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.18.4</version>
  </dependency>

Create an agent with image generation

import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.ResponsesClient;
import com.azure.ai.agents.models.*;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Base64;
import java.util.Collections;

public class ImageGenerationExample {
  public static void main(String[] args) throws Exception {
        // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
        String projectEndpoint = "your_project_endpoint";
        String imageModel = "gpt-image-1";

        AgentsClientBuilder builder = new AgentsClientBuilder()
            .credential(new DefaultAzureCredentialBuilder().build())
            .endpoint(projectEndpoint);

        AgentsClient agentsClient = builder.buildAgentsClient();
        ResponsesClient responsesClient = builder.buildResponsesClient();

        // Create image generation tool with model, quality, and size
        ImageGenTool imageGenTool = new ImageGenTool()
            .setModel(ImageGenToolModel.fromString(imageModel))
            .setQuality(ImageGenToolQuality.LOW)
            .setSize(ImageGenToolSize.fromString("1024x1024"));

        // Create agent with image generation tool
        PromptAgentDefinition agentDefinition = new PromptAgentDefinition("gpt-5")
            .setInstructions("You are a creative assistant that can generate images based on descriptions.")
            .setTools(Collections.singletonList(imageGenTool));

        AgentVersionDetails agent = agentsClient.createAgentVersion("image-gen-agent", agentDefinition);
        System.out.printf("Agent created: %s (version %s)%n", agent.getName(), agent.getVersion());

        // Create a response
        AgentReference agentReference = new AgentReference(agent.getName())
            .setVersion(agent.getVersion());

        Response response = responsesClient.createAzureResponse(
            new AzureCreateResponseOptions().setAgentReference(agentReference),
            ResponseCreateParams.builder()
                .input("Generate an image of a sunset over a mountain range"));

        System.out.println("Response status: " + response.status().map(Object::toString).orElse("unknown"));

        Path imagePath = Path.of("generated-image.png");
        boolean imageSaved = false;
        for (var outputItem : response.output()) {
          if (outputItem.isImageGenerationCall()) {
            String result = outputItem.asImageGenerationCall().result()
              .orElseThrow(() -> new IllegalStateException("Image result is missing."));
            Files.write(imagePath, Base64.getDecoder().decode(result));
            long imageSize = Files.size(imagePath);
            if (imageSize == 0) {
              throw new IllegalStateException("The generated image is empty.");
            }
            System.out.printf("Image saved to: %s (%d bytes)%n", imagePath.toAbsolutePath(), imageSize);
            imageSaved = true;
            break;
          }
        }
        if (!imageSaved) {
          throw new IllegalStateException("No image_generation_call output found.");
        }

        // Clean up
        agentsClient.deleteAgentVersion(agent.getName(), agent.getVersion());
    }
}

Expected output

Agent created: image-gen-agent (version 1)
Response status: completed
Image saved to: <path>/generated-image.png (<bytes> bytes)