Image Generation

​

Supported Providers & APIs

​

OpenAI Images API

​

Setting Up in the Playground

1. Open the Playground or Prompt Registry
2. In the model settings panel, select OpenAI (or OpenAI Azure) as the provider
3. Change the API dropdown to Images API
4. Select an image model (e.g. gpt-image-1, dall-e-3)
5. Write your image prompt in the text area
6. Click Run

​

Parameters

​

Using with pl.run()

from promptlayer import PromptLayer

pl = PromptLayer(api_key="pl_*****")

response = pl.run(
    prompt_name="my-image-prompt",
    input_variables={"subject": "a cat wearing a top hat"}
)

# The generated image is in the prompt blueprint
content = response["prompt_blueprint"]["prompt_template"]["content"]
for item in content:
    if item["type"] == "output_media":
        print(f"Image URL: {item['url']}")
        print(f"MIME type: {item['mime_type']}")

​

Pricing

​

OpenAI Responses API — Image Generation Tool

​

Setting Up in the Prompt Registry

1. Open your prompt in the Prompt Registry
2. Set the provider to OpenAI and the API to Responses API
3. Click the Functions & Output button
4. Click Built-in tools and add Image Generation
5. Save and run your prompt

​

How It Works

1. The model receives your messages and decides if an image should be generated
2. The model invokes the image_generation tool with an optimized prompt
3. The generated image appears in the response as an output_media content block
4. The model may also return text alongside the image (e.g., describing what was generated)

• Revised prompt — The optimized prompt the model used for image generation (collapsible in the UI)
• Parameters — Size, quality, background, and output format used
• Image ID — Unique identifier for the image_generation_call

​

Multiple Images

​

Using with pl.run()

from promptlayer import PromptLayer

pl = PromptLayer(api_key="pl_*****")

response = pl.run(
    prompt_name="image-chat-prompt",
    input_variables={"request": "Draw a sunset over mountains"}
)

messages = response["prompt_blueprint"]["prompt_template"]["messages"]
assistant_msg = messages[-1]

for content in assistant_msg["content"]:
    if content["type"] == "output_media":
        print(f"Generated image: {content['url'][:50]}...")
        if content.get("provider_metadata", {}).get("revised_prompt"):
            print(f"Revised prompt: {content['provider_metadata']['revised_prompt']}")
    elif content["type"] == "text":
        print(f"Text: {content['text']}")

​

Google Gemini — Native Image Generation

​

Setting Up in the Playground

1. Open the Playground or Prompt Registry
2. Select Google (or Vertex AI) as the provider
3. Choose a Gemini image model (e.g., gemini-2.5-flash-image)
4. PromptLayer automatically configures response_modalities: ["TEXT", "IMAGE"] when an image model is selected
5. Write your prompt and click Run

​

Image Configuration

​

How It Works

1. The image data is returned as inline_data in the Gemini response
2. PromptLayer converts this into an output_media content block for consistent display
3. The image is displayed in the same card format as OpenAI-generated images
4. Image metadata (aspect ratio, image size) is shown in the parameters block

​

Using with pl.run()

from promptlayer import PromptLayer

pl = PromptLayer(api_key="pl_*****")

response = pl.run(
    prompt_name="gemini-image-prompt",
    input_variables={"description": "A watercolor painting of a garden"}
)

messages = response["prompt_blueprint"]["prompt_template"]["messages"]
assistant_msg = messages[-1]

for content in assistant_msg["content"]:
    if content["type"] == "output_media":
        print(f"Generated image (MIME: {content['mime_type']})")
        if content.get("provider_metadata", {}).get("aspect_ratio"):
            print(f"Aspect ratio: {content['provider_metadata']['aspect_ratio']}")

​

Output Media Format

{
  "type": "output_media",
  "id": "img_abc123",
  "url": "<base64>",
  "mime_type": "image/png",
  "media_type": "image",
  "provider_metadata": {
    "revised_prompt": "A detailed, photorealistic sunset...",
    "size": "1024x1024",
    "quality": "high",
    "background": "auto",
    "output_format": "png",
    "aspect_ratio": "16:9",
    "image_size": "1024"
  }
}

​

Provider Metadata by Provider

• revised_prompt — The model’s optimized version of your prompt
• size — Image dimensions
• quality — Quality level
• background — Background setting (GPT Image models)
• output_format — Image format

• aspect_ratio — Configured aspect ratio
• image_size — Configured image size

​

Viewing Generated Images

• Header — Shows “Image Generation” label (with the tool call ID for Responses API)
• Parameters block — Displays generation parameters (size, quality, format, etc.)
• Revised prompt — Collapsible accordion showing the optimized prompt (when available)
• Image preview — The generated image with download/copy support

​

Image Storage

• Base64 images are uploaded to cloud storage and replaced with a URL reference
• URL images are stored as-is
• This keeps request logs compact and ensures images remain accessible
• Images are available in the dashboard, evaluations, and API responses

​

Logging Image Generation Requests

• openai.images.generate
• openai.OpenAI.images.generate
• openai.AzureOpenAI.images.generate
• openai.responses.create (when using the image_generation tool)

​

Evaluations

​

Related Docs

• Supported Providers
• Tool Calling (Built-in Tools)
• Run
• Custom Logging