=encoding utf8

=head1 NAME

OpenAPI::Client::OpenAI::Path::images-edits - Documentation for the /images/edits path.

=head1 OPERATIONS

=head2 POST /images/edits

=head3 createImageEdit

  $client->create_image_edit({
      body => { ... },
  });

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

You can call this endpoint with either:

- C<multipart/form-data> : use binary uploads via C<image> (and optional
C<mask> ). - C<application/json> : use C<images> (and optional C<mask> ) as
references with either C<image_url> or C<file_id> .

Note that JSON requests use C<images> (array) instead of the multipart
C<image> field.

=head4 Request body

Content-Type: application/json

Example:

    {
       "background" : "transparent",
       "images" : [
          null
       ],
       "input_fidelity" : "high",
       "mask" : null,
       "model" : "gpt-image-1.5",
       "moderation" : "auto",
       "n" : 1,
       "output_compression" : 100,
       "output_format" : "png",
       "partial_images" : 1,
       "prompt" : "Add a watercolor effect and keep the subject centered",
       "quality" : "high",
       "size" : "1024x1024",
       "stream" : false,
       "user" : "user-1234"
    }

Content-Type: multipart/form-data

Example:

    {
       "background" : "transparent",
       "image" : "string",
       "input_fidelity" : "high",
       "mask" : "string",
       "model" : "gpt-image-1.5",
       "n" : 1,
       "output_compression" : 100,
       "output_format" : "png",
       "partial_images" : 1,
       "prompt" : "A cute baby sea otter wearing a beret",
       "quality" : "high",
       "response_format" : "url",
       "size" : "1024x1024",
       "stream" : false,
       "user" : "user-1234"
    }

=head4 Responses

B<200 - OK>

Content-Type: application/json

Example:

    {
       "background" : "transparent",
       "created" : 1713833628,
       "data" : [
          {
             "b64_json" : "..."
          }
       ],
       "output_format" : "png",
       "quality" : "high",
       "size" : "1024x1024",
       "usage" : {
          "input_tokens" : 50,
          "input_tokens_details" : {
             "image_tokens" : 40,
             "text_tokens" : 10
          },
          "output_tokens" : 50,
          "total_tokens" : 100
       }
    }

Content-Type: text/event-stream

Example:

    {
       "b64_json" : "...",
       "background" : "transparent",
       "created_at" : 1620000000,
       "output_format" : "png",
       "partial_image_index" : 0,
       "quality" : "high",
       "size" : "1024x1024",
       "type" : "image_edit.partial_image"
    }

=head1 SCHEMAS

=head2 CreateImageEditRequest

Properties:

=over

=item * C<background> (string) - Allows to set transparency for the background of the generated image(s). This
parameter is only supported for the GPT image models. Must be one of
C<transparent> , C<opaque> or C<auto> (default value). When C<auto> is used,
the model will automatically determine the best background for the image.

If C<transparent> , the output format needs to support transparency, so it
should be set to either C<png> (default value) or C<webp> .

Allowed values: transparent, opaque, auto

Default: auto

=item * C<image> (anyOf, required) - The image(s) to edit. Must be a supported image file or an array of images.

For the GPT image models (C<gpt-image-1>, C<gpt-image-1-mini> , and
C<gpt-image-1.5> ), each image should be a C<png> , C<webp> , or C<jpg> file
less than 50MB. You can provide up to 16 images. C<chatgpt-image-latest>
follows the same input constraints as GPT image models.

For C<dall-e-2> , you can only provide one image, and it should be a square
C<png> file less than 4MB.

=item * C<input_fidelity> (anyOf)

=item * C<mask> (string) - An additional image whose fully transparent areas (e.g. where alpha is zero)
indicate where C<image> should be edited. If there are multiple images
provided, the mask will be applied on the first image. Must be a valid PNG
file, less than 4MB, and have the same dimensions as C<image> .

=item * C<model> (anyOf) - The model to use for image generation. Defaults to C<gpt-image-1.5> .

Default: gpt-image-1.5

=item * C<n> (integer) - The number of images to generate. Must be between 1 and 10.

Default: 1

=item * C<output_compression> (integer) - The compression level (0-100%) for the generated images. This parameter is
only supported for the GPT image models with the C<webp> or C<jpeg> output
formats, and defaults to 100.

Default: 100

=item * C<output_format> (string) - The format in which the generated images are returned. This parameter is only
supported for the GPT image models. Must be one of C<png> , C<jpeg> , or
C<webp> . The default value is C<png> .

Allowed values: png, jpeg, webp

Default: png

=item * C<partial_images> (PartialImages)

See L</PartialImages> below for shape.

=item * C<prompt> (string, required) - A text description of the desired image(s). The maximum length is 1000
characters for C<dall-e-2> , and 32000 characters for the GPT image models.

=item * C<quality> (string) - The quality of the image that will be generated for GPT image models. Defaults
to C<auto> .

Allowed values: standard, low, medium, high, auto

Default: auto

=item * C<response_format> (string) - The format in which the generated images are returned. Must be one of C<url>
or C<b64_json> . URLs are only valid for 60 minutes after the image has been
generated. This parameter is only supported for C<dall-e-2> (default is C<url>
for C<dall-e-2> ), as GPT image models always return base64-encoded images.

Allowed values: url, b64_json

=item * C<size> (anyOf) - The size of the generated images. For C<gpt-image-2> and
C<gpt-image-2-2026-04-21> , arbitrary resolutions are supported as
C<WIDTHxHEIGHT> strings, for example C<1536x864> . Width and height must both
be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1.
Resolutions above C<2560x1440> are experimental, and the maximum supported
resolution is C<3840x2160> . The requested size must also satisfy the model's
current pixel and edge limits. The standard sizes C<1024x1024> , C<1536x1024>
, and C<1024x1536> are supported by the GPT image models; C<auto> is supported
for models that allow automatic sizing. For C<dall-e-2> , use one of
C<256x256> , C<512x512> , or C<1024x1024> . For C<dall-e-3> , use one of
C<1024x1024> , C<1792x1024> , or C<1024x1792> .

Default: 1024x1024

=item * C<stream> (boolean) - Edit the image in streaming mode. Defaults to C<false> . See the
L<Image generation guide|https://platform.openai.com/docs/guides/image-generation>
for more information.

Default: 

=item * C<user> (string) - A unique identifier representing your end-user, which can help OpenAI to
monitor and detect abuse.
L<Learn more|https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids>
.

=back

=head2 EditImageBodyJsonParam

Properties:

=over

=item * C<background> (anyOf) - Background behavior for generated image output.

Default: auto

=item * C<images> (array of ImageRefParam, required) - Input image references to edit. For GPT image models, you can provide up to 16
images.

=item * C<input_fidelity> (anyOf) - Controls fidelity to the original input image(s).

=item * C<mask> (ImageRefParam)

See L</ImageRefParam> below for shape.

=item * C<model> (anyOf) - The model to use for image editing.

Default: gpt-image-1.5

=item * C<moderation> (anyOf) - Moderation level for GPT image models.

Default: auto

=item * C<n> (anyOf) - The number of edited images to generate.

Default: 1

=item * C<output_compression> (anyOf) - Compression level for C<jpeg> or C<webp> output.

=item * C<output_format> (anyOf) - Output image format. Supported for GPT image models.

Default: png

=item * C<partial_images> (PartialImages)

See L</PartialImages> below for shape.

=item * C<prompt> (string, required) - A text description of the desired image edit.

=item * C<quality> (anyOf) - Output quality for GPT image models.

Default: auto

=item * C<size> (anyOf) - Requested output image size.

Default: auto

=item * C<stream> (anyOf) - Stream partial image results as events.

Default: 

=item * C<user> (string) - A unique identifier representing your end-user, which can help OpenAI monitor
and detect abuse.

=back

=head2 Image

Properties:

=over

=item * C<b64_json> (string) - The base64-encoded JSON of the generated image. Returned by default for the
GPT image models, and only present if C<response_format> is set to C<b64_json>
for C<dall-e-2> and C<dall-e-3> .

=item * C<revised_prompt> (string) - For C<dall-e-3> only, the revised prompt that was used to generate the image.

=item * C<url> (string) - When using C<dall-e-2> or C<dall-e-3> , the URL of the generated image if
C<response_format> is set to C<url> (default value). Unsupported for the GPT
image models.

=back

=head2 ImageEditStreamEvent

See L<https://platform.openai.com/docs/api-reference> for details.

=head2 ImageGenInputUsageDetails

Properties:

=over

=item * C<image_tokens> (integer, required) - The number of image tokens in the input prompt.

=item * C<text_tokens> (integer, required) - The number of text tokens in the input prompt.

=back

=head2 ImageGenOutputTokensDetails

Properties:

=over

=item * C<image_tokens> (integer, required) - The number of image output tokens generated by the model.

=item * C<text_tokens> (integer, required) - The number of text output tokens generated by the model.

=back

=head2 ImageGenUsage

Properties:

=over

=item * C<input_tokens> (integer, required) - The number of tokens (images and text) in the input prompt.

=item * C<input_tokens_details> (ImageGenInputUsageDetails, required)

See L</ImageGenInputUsageDetails> below for shape.

=item * C<output_tokens> (integer, required) - The number of output tokens generated by the model.

=item * C<output_tokens_details> (ImageGenOutputTokensDetails)

See L</ImageGenOutputTokensDetails> below for shape.

=item * C<total_tokens> (integer, required) - The total number of tokens (images and text) used for the image generation.

=back

=head2 ImageRefParam

Properties:

=over

=item * C<file_id> (string) - The File API ID of an uploaded image to use as input.

=item * C<image_url> (string) - A fully qualified URL or base64-encoded data URL.

=back

=head2 ImagesResponse

Properties:

=over

=item * C<background> (string) - The background parameter used for the image generation. Either C<transparent>
or C<opaque> .

Allowed values: transparent, opaque

=item * C<created> (integer, required) - The Unix timestamp (in seconds) of when the image was created.

=item * C<data> (array of Image) - The list of generated images.

=item * C<output_format> (string) - The output format of the image generation. Either C<png> , C<webp> , or
C<jpeg> .

Allowed values: png, webp, jpeg

=item * C<quality> (string) - The quality of the image generated. Either C<low> , C<medium> , or C<high> .

Allowed values: low, medium, high

=item * C<size> (string) - The size of the image generated. Either C<1024x1024> , C<1024x1536> , or
C<1536x1024> .

Allowed values: 1024x1024, 1024x1536, 1536x1024

=item * C<usage> (ImageGenUsage)

See L</ImageGenUsage> below for shape.

=back

=head2 PartialImages

The number of partial images to generate. This parameter is used for streaming
responses that return partial images. Value must be between 0 and 3. When set
to 0, the response will be a single image sent in one streaming event.

Note that the final image may be sent before the full number of partial images
are generated if the full image is generated more quickly.

=head1 SEE ALSO

L<OpenAPI::Client::OpenAI::Path>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2023-2026 by Nelson Ferraz

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.14.0 or,
at your option, any later version of Perl 5 you may have available.

=cut
