=encoding utf8

=head1 NAME

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

=head1 OPERATIONS

=head2 POST /images/generations

=head3 createImage

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

Creates an image given a prompt.
L<Learn more|https://platform.openai.com/docs/guides/images> .

=head4 Request body

Content-Type: application/json

Example:

    {
       "created" : 1713833628,
       "data" : [
          {
             "b64_json" : "..."
          }
       ],
       "usage" : {
          "input_tokens" : 50,
          "input_tokens_details" : {
             "image_tokens" : 40,
             "text_tokens" : 10
          },
          "output_tokens" : 50,
          "total_tokens" : 100
       }
    }

=head4 Responses

B<200 - OK>

Content-Type: application/json

Example:

    {
       "created" : 1713833628,
       "data" : [
          {
             "b64_json" : "..."
          }
       ],
       "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:

    {
       "created" : 1713833628,
       "data" : [
          {
             "b64_json" : "..."
          }
       ],
       "usage" : {
          "input_tokens" : 50,
          "input_tokens_details" : {
             "image_tokens" : 40,
             "text_tokens" : 10
          },
          "output_tokens" : 50,
          "total_tokens" : 100
       }
    }

=head1 SCHEMAS

=head2 CreateImageRequest

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<model> (anyOf) - The model to use for image generation. One of C<dall-e-2> , C<dall-e-3> , or a
GPT image model (C<gpt-image-1>, C<gpt-image-1-mini> , C<gpt-image-1.5> ).
Defaults to C<dall-e-2> unless a parameter specific to the GPT image models is
used.

Default: dall-e-2

=item * C<moderation> (string) - Control the content-moderation level for images generated by the GPT image
models. Must be either C<low> for less restrictive filtering or C<auto>
(default value).

Allowed values: low, auto

Default: auto

=item * C<n> (integer) - The number of images to generate. Must be between 1 and 10. For C<dall-e-3> ,
only C<n=1> is supported.

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> .

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 32000
characters for the GPT image models, 1000 characters for C<dall-e-2> and 4000
characters for C<dall-e-3> .

=item * C<quality> (string) - The quality of the image that will be generated.

- C<auto> (default value) will automatically select the best quality for the
given model. - C<high> , C<medium> and C<low> are supported for the GPT image
models. - C<hd> and C<standard> are supported for C<dall-e-3> . - C<standard>
is the only option for C<dall-e-2> .

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

Default: auto

=item * C<response_format> (string) - The format in which generated images with C<dall-e-2> and C<dall-e-3> 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 isn't supported for
the GPT image models, which always return base64-encoded images.

Allowed values: url, b64_json

Default: url

=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: auto

=item * C<stream> (boolean) - Generate 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. This parameter is only supported for the GPT image
models.

Default: 

=item * C<style> (string) - The style of the generated images. This parameter is only supported for
C<dall-e-3> . Must be one of C<vivid> or C<natural> . Vivid causes the model
to lean towards generating hyper-real and dramatic images. Natural causes the
model to produce more natural, less hyper-real looking images.

Allowed values: vivid, natural

Default: vivid

=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 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 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 ImageGenStreamEvent

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

=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 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
