Skip to main content
The Images API provides three methods for interacting with images: generating new images from text prompts, editing existing images, and creating variations of images.

​
Generate images

Creates an image given a text prompt. 
client.images.generate(params)
​
prompt
String
required
A text description of the desired image(s). Maximum length is 32000 characters for GPT image models, 1000 for DALL-E.
​
model
String
default:"gpt-image-1.5"
The model to use for image generation. Options: dall-e-2, dall-e-3, gpt-image-1.5, gpt-image-1, gpt-image-1-mini, chatgpt-image-latest.
​
n
Integer
default:"1"
The number of images to generate. Must be between 1 and 10. For dall-e-3, only n=1 is supported.
​
size
String
default:"1024x1024"
The size of the generated images. Options include 1024x1024, 1536x1024 (landscape), 1024x1536 (portrait), 256x256, 512x512.
​
quality
String
default:"standard"
The quality of the image. Options: standard or hd. HD quality is available for dall-e-3 and GPT image models.
​
style
String
The style of the generated images. Options: vivid or natural. Only supported for dall-e-3.
​
response_format
String
default:"url"
The format in which images are returned. Options: url or b64_json.
​
background
String
Set transparency for the background. Options: opaque or transparent.
​
output_format
String
The format for generated images. Supported for GPT image models. Options include png, jpeg, webp.
​
output_compression
Integer
The compression level (0-100%) for the generated images. Only for GPT image models.
​
moderation
String
Control the content-moderation level. Options: off, low, medium, high. Only for GPT image models.
​
user
String
A unique identifier representing your end-user.

​
Response

Returns an ImagesResponse object.
​
created
Integer
Unix timestamp of when the image was created.
​
data
Array
List of generated image objects.

​
Examples

​
Basic image generation

require "openai"

client = OpenAI::Client.new

response = client.images.generate(
  prompt: "An astronaut lounging in a tropical resort in space, pixel art"
)

puts response.data.first.url

​
HD quality with specific size

response = client.images.generate(
  prompt: "A serene mountain landscape at sunset",
  model: "dall-e-3",
  size: "1536x1024",
  quality: "hd",
  style: "natural"
)

image_url = response.data.first.url
puts "Generated image: #{image_url}"
puts "Revised prompt: #{response.data.first.revised_prompt}"

​
Multiple images

response = client.images.generate(
  prompt: "A cute cat playing with yarn",
  model: "dall-e-2",
  n: 3,
  size: "512x512"
)

response.data.each_with_index do |image, i|
  puts "Image #{i + 1}: #{image.url}"
end

​
Streaming image generation

stream = client.images.generate_stream_raw(
  prompt: "A futuristic cityscape",
  model: "gpt-image-1.5",
  partial_images: 3
)

stream.each do |event|
  case event
  when OpenAI::Models::ImageGenPartialImageEvent
    puts "Partial image #{event.index} received"
  when OpenAI::Models::ImageGenCompletedEvent
    puts "Final image: #{event.data.first.url}"
  end
end

​
Edit images

Creates an edited or extended image given one or more source images and a prompt. 
client.images.edit(params)
​
image
File | Array<File>
required
The image(s) to edit. Must be a valid PNG file, less than 4MB, and square.
​
prompt
String
required
A text description of the desired image(s). Maximum length is 1000 characters.
​
mask
File
An additional image whose fully transparent areas indicate where to edit. Must be a valid PNG file.
​
model
String
default:"gpt-image-1.5"
The model to use. Supports GPT image models and dall-e-2.
​
n
Integer
default:"1"
The number of images to generate. Must be between 1 and 10.
​
size
String
The size of the generated images. Same options as generate.
​
response_format
String
default:"url"
The format in which images are returned: url or b64_json.
​
quality
String
The quality of the image. Options: standard or hd.
​
input_fidelity
String
Control how much effort the model exerts to match the style and features. Options: auto, low, medium, high.

​
Examples

​
Edit an image

require "openai"

client = OpenAI::Client.new

response = client.images.edit(
  image: File.open("original.png"),
  prompt: "Add a red hat to the person in the image"
)

puts response.data.first.url

​
Edit with mask

response = client.images.edit(
  image: File.open("photo.png"),
  mask: File.open("mask.png"),
  prompt: "Replace the masked area with a sunny sky",
  model: "dall-e-2"
)

puts response.data.first.url

​
Streaming edit

stream = client.images.edit_stream_raw(
  image: File.open("input.png"),
  prompt: "Make it look futuristic",
  model: "gpt-image-1.5",
  partial_images: 2
)

stream.each do |event|
  case event
  when OpenAI::Models::ImageEditPartialImageEvent
    puts "Partial result available"
  when OpenAI::Models::ImageEditCompletedEvent
    puts "Edit complete: #{event.data.first.url}"
  end
end

​
Create image variations

Creates a variation of a given image. Only supports dall-e-2. 
client.images.create_variation(params)
​
image
File
required
The image to use as the basis for the variation(s). Must be a valid PNG file, less than 4MB, and square.
​
model
String
The model to use. Only dall-e-2 is supported at this time.
​
n
Integer
default:"1"
The number of images to generate. Must be between 1 and 10.
​
size
String
The size of the generated images. Options: 256x256, 512x512, or 1024x1024.
​
response_format
String
default:"url"
The format in which images are returned: url or b64_json.

​
Examples

​
Create variations

require "openai"

client = OpenAI::Client.new

response = client.images.create_variation(
  image: File.open("original.png"),
  n: 3,
  size: "512x512"
)

response.data.each_with_index do |image, i|
  puts "Variation #{i + 1}: #{image.url}"
end

​
Download and save images

require "openai"
require "open-uri"

client = OpenAI::Client.new

response = client.images.generate(
  prompt: "A beautiful sunset over the ocean"
)

image_url = response.data.first.url

# Download and save
URI.open(image_url) do |image|
  File.open("sunset.png", "wb") do |file|
    file.write(image.read)
  end
end

puts "Image saved to sunset.png"

​
Best practices

  • Be specific: More detailed prompts generally produce better results
  • Choose the right model: Use dall-e-3 or GPT image models for highest quality
  • Image format: For edits and variations, ensure images are PNG format and square
  • File size: Keep images under 4MB for best performance
  • Experiment with parameters: Try different quality, style, and size settings
  • Use streaming: For real-time feedback with GPT image models

Build docs developers (and LLMs) love

Get started for freeTalk to us