Class: OpenAI::Resources::Images

Inherits:
Object
  • Object
show all
Defined in:
lib/openai/resources/images.rb,
sig/openai/resources/images.rbs

Overview

Given a prompt and/or an input image, the model will generate a new image.

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Images

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Images.

Parameters:



304
305
306
 
# File 'lib/openai/resources/images.rb', line 304

def initialize(client:)
  @client = client
end

Instance Method Details

#create_variation(image:, model: nil, n: nil, response_format: nil, size: nil, user: nil, request_options: {}) ⇒ OpenAI::Models::ImagesResponse

Some parameter documentations has been truncated, see Models::ImageCreateVariationParams for more details.

Creates a variation of a given image. This endpoint only supports dall-e-2.

String, StringIO, and pathless IO inputs are sent with generic upload metadata. Use OpenAI::FilePart when you need to override the filename or content type.

Parameters:

  • image (Pathname, StringIO, IO, String, OpenAI::FilePart) —

    The image to use as the basis for the variation(s). Must be a valid PNG file, le

  • model (String, Symbol, OpenAI::Models::ImageModel, nil) —

    The model to use for image generation. Only dall-e-2 is supported at this time

  • n (Integer, nil) —

    The number of images to generate. Must be between 1 and 10.

  • response_format (Symbol, OpenAI::Models::ImageCreateVariationParams::ResponseFormat, nil) —

    The format in which the generated images are returned. Must be one of url or `

  • size (Symbol, OpenAI::Models::ImageCreateVariationParams::Size, nil) —

    The size of the generated images. Must be one of 256x256, 512x512, or `1024x

  • user (String) —

    A unique identifier representing your end-user, which can help OpenAI to monitor

  • request_options (OpenAI::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/openai/resources/images.rb', line 35

def create_variation(params)
  parsed, options = OpenAI::ImageCreateVariationParams.dump_request(params)
  @client.request(
    method: :post,
    path: "images/variations",
    headers: {"content-type" => "multipart/form-data"},
    body: parsed,
    model: OpenAI::ImagesResponse,
    security: {bearer_auth: true},
    options: options
  )
end

#edit(image:, prompt:, background: nil, input_fidelity: nil, mask: nil, model: nil, n: nil, output_compression: nil, output_format: nil, partial_images: nil, quality: nil, response_format: nil, size: nil, user: nil, request_options: {}) ⇒ OpenAI::Models::ImagesResponse

See OpenAI::Resources::Images#edit_stream_raw for streaming counterpart.

Some parameter documentations has been truncated, see Models::ImageEditParams for more details.

Creates an edited or extended image given one or more source images and a prompt. This endpoint supports GPT Image models (gpt-image-1.5, gpt-image-1, gpt-image-1-mini, and chatgpt-image-latest) and dall-e-2.

String, StringIO, and pathless IO inputs are sent with generic upload metadata. Use OpenAI::FilePart when you need to override the filename or content type.

Parameters:

  • image (Pathname, StringIO, IO, String, OpenAI::FilePart, Array<Pathname, StringIO, IO, String, OpenAI::FilePart>) —

    The image(s) to edit. Must be a supported image file or an array of images.

  • prompt (String) —

    A text description of the desired image(s). The maximum length is 1000 character

  • background (Symbol, OpenAI::Models::ImageEditParams::Background, nil) —

    Allows to set transparency for the background of the generated image(s).

  • input_fidelity (Symbol, OpenAI::Models::ImageEditParams::InputFidelity, nil) —

    Control how much effort the model will exert to match the style and features, es

  • mask (Pathname, StringIO, IO, String, OpenAI::FilePart) —

    An additional image whose fully transparent areas (e.g. where alpha is zero) ind

  • model (String, Symbol, OpenAI::Models::ImageModel, nil) —

    The model to use for image generation. One of dall-e-2 or a GPT image model (`

  • n (Integer, nil) —

    The number of images to generate. Must be between 1 and 10.

  • output_compression (Integer, nil) —

    The compression level (0-100%) for the generated images. This parameter

  • output_format (Symbol, OpenAI::Models::ImageEditParams::OutputFormat, nil) —

    The format in which the generated images are returned. This parameter is

  • partial_images (Integer, nil) —

    The number of partial images to generate. This parameter is used for

  • quality (Symbol, OpenAI::Models::ImageEditParams::Quality, nil) —

    The quality of the image that will be generated for GPT image models. Defaults t

  • response_format (Symbol, OpenAI::Models::ImageEditParams::ResponseFormat, nil) —

    The format in which the generated images are returned. Must be one of url or `

  • size (String, Symbol, OpenAI::Models::ImageEditParams::Size, nil) —

    The size of the generated images. For gpt-image-2 and gpt-image-2-2026-04-21

  • user (String) —

    A unique identifier representing your end-user, which can help OpenAI to monitor

  • request_options (OpenAI::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/openai/resources/images.rb', line 96

def edit(params)
  parsed, options = OpenAI::ImageEditParams.dump_request(params)
  if parsed[:stream]
    message = "Please use `#edit_stream_raw` for the streaming use case."
    raise ArgumentError.new(message)
  end
  @client.request(
    method: :post,
    path: "images/edits",
    headers: {"content-type" => "multipart/form-data"},
    body: parsed,
    model: OpenAI::ImagesResponse,
    security: {bearer_auth: true},
    options: options
  )
end

#edit_stream_raw(image:, prompt:, background: nil, input_fidelity: nil, mask: nil, model: nil, n: nil, output_compression: nil, output_format: nil, partial_images: nil, quality: nil, response_format: nil, size: nil, user: nil, request_options: {}) ⇒ OpenAI::Internal::Stream<OpenAI::Models::ImageEditPartialImageEvent, OpenAI::Models::ImageEditCompletedEvent>

See OpenAI::Resources::Images#edit for non-streaming counterpart.

Some parameter documentations has been truncated, see Models::ImageEditParams for more details.

Creates an edited or extended image given one or more source images and a prompt. This endpoint supports GPT Image models (gpt-image-1.5, gpt-image-1, gpt-image-1-mini, and chatgpt-image-latest) and dall-e-2.

String, StringIO, and pathless IO inputs are sent with generic upload metadata. Use OpenAI::FilePart when you need to override the filename or content type.

Parameters:

  • image (Pathname, StringIO, IO, String, OpenAI::FilePart, Array<Pathname, StringIO, IO, String, OpenAI::FilePart>) —

    The image(s) to edit. Must be a supported image file or an array of images.

  • prompt (String) —

    A text description of the desired image(s). The maximum length is 1000 character

  • background (Symbol, OpenAI::Models::ImageEditParams::Background, nil) —

    Allows to set transparency for the background of the generated image(s).

  • input_fidelity (Symbol, OpenAI::Models::ImageEditParams::InputFidelity, nil) —

    Control how much effort the model will exert to match the style and features, es

  • mask (Pathname, StringIO, IO, String, OpenAI::FilePart) —

    An additional image whose fully transparent areas (e.g. where alpha is zero) ind

  • model (String, Symbol, OpenAI::Models::ImageModel, nil) —

    The model to use for image generation. One of dall-e-2 or a GPT image model (`

  • n (Integer, nil) —

    The number of images to generate. Must be between 1 and 10.

  • output_compression (Integer, nil) —

    The compression level (0-100%) for the generated images. This parameter

  • output_format (Symbol, OpenAI::Models::ImageEditParams::OutputFormat, nil) —

    The format in which the generated images are returned. This parameter is

  • partial_images (Integer, nil) —

    The number of partial images to generate. This parameter is used for

  • quality (Symbol, OpenAI::Models::ImageEditParams::Quality, nil) —

    The quality of the image that will be generated for GPT image models. Defaults t

  • response_format (Symbol, OpenAI::Models::ImageEditParams::ResponseFormat, nil) —

    The format in which the generated images are returned. Must be one of url or `

  • size (String, Symbol, OpenAI::Models::ImageEditParams::Size, nil) —

    The size of the generated images. For gpt-image-2 and gpt-image-2-2026-04-21

  • user (String) —

    A unique identifier representing your end-user, which can help OpenAI to monitor

  • request_options (OpenAI::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/openai/resources/images.rb', line 161

def edit_stream_raw(params)
  parsed, options = OpenAI::ImageEditParams.dump_request(params)
  unless parsed.fetch(:stream, true)
    message = "Please use `#edit` for the non-streaming use case."
    raise ArgumentError.new(message)
  end
  parsed.store(:stream, true)
  @client.request(
    method: :post,
    path: "images/edits",
    headers: {
      "content-type" => "multipart/form-data",
      "accept" => "text/event-stream",
      "accept-encoding" => "identity"
    },
    body: parsed,
    stream: OpenAI::Internal::Stream,
    model: OpenAI::ImageEditStreamEvent,
    security: {bearer_auth: true},
    options: options
  )
end

#generate(prompt:, background: nil, model: nil, moderation: nil, n: nil, output_compression: nil, output_format: nil, partial_images: nil, quality: nil, response_format: nil, size: nil, style: nil, user: nil, request_options: {}) ⇒ OpenAI::Models::ImagesResponse

See OpenAI::Resources::Images#generate_stream_raw for streaming counterpart.

Some parameter documentations has been truncated, see Models::ImageGenerateParams for more details.

Creates an image given a prompt. Learn more.

Parameters:

Returns:

See Also:



225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
 
# File 'lib/openai/resources/images.rb', line 225

def generate(params)
  parsed, options = OpenAI::ImageGenerateParams.dump_request(params)
  if parsed[:stream]
    message = "Please use `#generate_stream_raw` for the streaming use case."
    raise ArgumentError.new(message)
  end
  @client.request(
    method: :post,
    path: "images/generations",
    body: parsed,
    model: OpenAI::ImagesResponse,
    security: {bearer_auth: true},
    options: options
  )
end

#generate_stream_raw(prompt:, background: nil, model: nil, moderation: nil, n: nil, output_compression: nil, output_format: nil, partial_images: nil, quality: nil, response_format: nil, size: nil, style: nil, user: nil, request_options: {}) ⇒ OpenAI::Internal::Stream<OpenAI::Models::ImageGenPartialImageEvent, OpenAI::Models::ImageGenCompletedEvent>

See OpenAI::Resources::Images#generate for non-streaming counterpart.

Some parameter documentations has been truncated, see Models::ImageGenerateParams for more details.

Creates an image given a prompt. Learn more.

Parameters:

Returns:

See Also:



282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
 
# File 'lib/openai/resources/images.rb', line 282

def generate_stream_raw(params)
  parsed, options = OpenAI::ImageGenerateParams.dump_request(params)
  unless parsed.fetch(:stream, true)
    message = "Please use `#generate` for the non-streaming use case."
    raise ArgumentError.new(message)
  end
  parsed.store(:stream, true)
  @client.request(
    method: :post,
    path: "images/generations",
    headers: {"accept" => "text/event-stream", "accept-encoding" => "identity"},
    body: parsed,
    stream: OpenAI::Internal::Stream,
    model: OpenAI::ImageGenStreamEvent,
    security: {bearer_auth: true},
    options: options
  )
end