Use the image generation tool (preview) in Foundry Agent Service

Generate images from text prompts with the image generation tool in Microsoft Foundry Agent Service. Configure agents, deploy models, and save output.

• The image generation tool requires the gpt-image-1 model. See the Azure OpenAI transparency note for limitations and responsible AI considerations.
• You also need a compatible orchestrator model (gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, o3, or gpt-5 series) deployed in the same Foundry project.

The image generation tool in Microsoft Foundry Agent Service generates images from text prompts in conversations and multistep workflows. The agent’s Foundry model orchestrates the image generation request and returns base64-encoded output that you can save to a file.

Usage support

The following table shows SDK and setup support.

Microsoft Foundry support	Python SDK	C# SDK	JavaScript SDK	Java SDK	REST API	Basic agent setup	Standard agent setup
✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️

Prerequisites

• An Azure account with an active subscription.
• A Foundry project.
• A basic or standard agent environment. See agent environment setup.
• Permissions to create and manage agent versions in the project.
• Two model deployments in the same Foundry project:
  • A compatible Azure OpenAI model deployment for the agent (for example, gpt-4o).
  • An image generation model deployment (gpt-image-1).

Configure the image generation tool

1. Deploy your orchestrator model (for example, gpt-4o) to your Foundry project.
2. Deploy gpt-image-1 to the same Foundry project.
3. Confirm your region and model support for image generation. See Best practices for using tools in Microsoft Foundry Agent Service.

Code examples

Before you start, install the latest SDK package. The .NET SDK is currently in preview. For package installation instructions, see the quickstart.

When to use the image generation tool

The image generation tool in Agent Service offers advantages over the Azure OpenAI Image API:

Advantage	Description
Streaming	Display partial image outputs during generation to improve perceived latency.
Flexible inputs	Accept image file IDs as inputs, in addition to raw image bytes.

Optional parameters

Customize image generation by specifying these optional parameters when you create the tool:

Parameter	Description
size	Image size. One of 1024x1024, 1024x1536, 1536x1024, or auto.
quality	Image quality. One of low, medium, high, or auto.
background	Background type. One of transparent, opaque, or auto.
output_format	Output format. One of png, webp, or jpeg.
output_compression	Compression level for webp and jpeg output (0-100).
moderation	Moderation level for the generated image. One of auto or low.
partial_images	Number of partial images to generate in streaming mode (0-3).
input_image_mask	Optional mask for inpainting. Provide image_url (base64) or file_id.

Image generation time varies based on the quality setting and prompt complexity. For time-sensitive applications, consider using quality: "low" or enabling partial_images for streaming.

Use the Responses API if you want to:

• Build conversational image experiences with GPT Image.
• Stream partial image results during generation for a smoother user experience.

Write effective text-to-image prompts

Effective prompts produce better images. Describe the subject, visual style, and composition you want. Use action words like “draw,” “create,” or “edit” to guide the model’s output.

Content filtering can block image generation if the service detects unsafe content in your prompt. For more information, see Guardrails and controls overview.

For a thorough look at how you can tweak your text prompts to generate different kinds of images, see Image prompt engineering techniques.

Verify tool execution

Use either of these approaches to confirm that image generation ran successfully:

• In the response payload, look for an output item with type set to image_generation_call.
• In the Foundry portal, open tracing/debug for your run to confirm the tool call and inspect inputs and outputs.

When image generation succeeds, the response includes an image_generation_call output item with a result field containing base64-encoded image data.

If you see only text output and no image_generation_call item, the request might not be routed to image generation. Review the troubleshooting section.

Troubleshooting

Issue	Cause	Resolution
Image generation fails	Missing deployment	Verify both the orchestrator model (for example, gpt-4o) and gpt-image-1 deployments exist in the same Foundry project.
Image generation fails	Missing or incorrect header	Verify the header x-ms-oai-image-generation-deployment is present on the Responses request and matches your image generation deployment name.
Agent uses wrong deployment	Model name misconfiguration	Confirm the orchestrator model name in your agent definition differs from the image generation deployment name.
Prompt doesn’t produce an image	Content filtering blocked the request	Check content filtering logs. See Guardrails and controls overview for guidelines on acceptable prompts.
Tool not available	Regional or model limitation	Confirm the image generation tool is available in your region and with your orchestrator model. See Best practices for using tools.
Generated image has low quality	Prompt lacks detail	Provide more specific and detailed prompts describing the desired image style, composition, and elements.
Image generation times out	Large or complex image request	Simplify the prompt or increase timeout settings. Consider breaking complex requests into multiple simpler ones.
Unexpected image content	Ambiguous prompt	Refine your prompt to be more specific. Include negative prompts to exclude unwanted elements.

Related content

• Best practices for using tools in Microsoft Foundry Agent Service
• Image generation in Azure OpenAI
• Responses API in Azure OpenAI
• Guardrails and controls overview