openai 0.92.0 → 0.94.0

data/sig/openai/models/chat/completion_create_params.rbs

@@ -46,110 +46,632 @@ module OpenAI
         extend OpenAI::Internal::Type::RequestParameters::Converter
         include OpenAI::Internal::Type::RequestParameters
 
+        # A list of messages comprising the conversation so far. Depending on the
+        # [model](https://developers.openai.com/api/docs/models) you use, different
+        # message types (modalities) are supported, like
+        # [text](https://developers.openai.com/api/docs/guides/text),
+        # [images](https://developers.openai.com/api/docs/guides/images-vision), and
+        # [audio](https://developers.openai.com/api/docs/guides/audio).
         attr_accessor messages: ::Array[OpenAI::Models::Chat::chat_completion_message_param]
 
+        # Model ID used to generate the response, like `gpt-6-astra` or `o3`. OpenAI
+        # offers a wide range of models with different capabilities, performance
+        # characteristics, and price points. Refer to the
+        # [model guide](https://developers.openai.com/api/docs/models) to browse and
+        # compare available models.
         attr_accessor model: OpenAI::Models::Chat::CompletionCreateParams::model
 
+        # Parameters for audio output. Required when audio output is requested with
+        # `modalities: ["audio"]`.
+        # [Learn more](https://developers.openai.com/api/docs/guides/audio).
         attr_accessor audio: OpenAI::Chat::ChatCompletionAudioParam?
 
+        # Number between -2.0 and 2.0. Positive values penalize new tokens based on their
+        # existing frequency in the text so far, decreasing the model's likelihood to
+        # repeat the same line verbatim.
         attr_accessor frequency_penalty: Float?
 
+        # Deprecated in favor of `tool_choice`.
+        #
+        # Controls which (if any) function is called by the model.
+        #
+        # `none` means the model will not call a function and instead generates a message.
+        #
+        # `auto` means the model can pick between generating a message or calling a
+        # function.
+        #
+        # Specifying a particular function via `{"name": "my_function"}` forces the model
+        # to call that function.
+        #
+        # `none` is the default when no functions are present. `auto` is the default if
+        # functions are present.
         attr_reader function_call: OpenAI::Models::Chat::CompletionCreateParams::function_call?
 
+        # Deprecated in favor of `tool_choice`.
+        #
+        # Controls which (if any) function is called by the model.
+        #
+        # `none` means the model will not call a function and instead generates a message.
+        #
+        # `auto` means the model can pick between generating a message or calling a
+        # function.
+        #
+        # Specifying a particular function via `{"name": "my_function"}` forces the model
+        # to call that function.
+        #
+        # `none` is the default when no functions are present. `auto` is the default if
+        # functions are present.
         def function_call=: (
           OpenAI::Models::Chat::CompletionCreateParams::function_call
         ) -> OpenAI::Models::Chat::CompletionCreateParams::function_call
 
+        # Deprecated in favor of `tools`.
+        #
+        # A list of functions the model may generate JSON inputs for.
         attr_reader functions: ::Array[OpenAI::Chat::CompletionCreateParams::Function]?
 
+        # Deprecated in favor of `tools`.
+        #
+        # A list of functions the model may generate JSON inputs for.
         def functions=: (
           ::Array[OpenAI::Chat::CompletionCreateParams::Function]
         ) -> ::Array[OpenAI::Chat::CompletionCreateParams::Function]
 
+        # Modify the likelihood of specified tokens appearing in the completion.
+        #
+        # Accepts a JSON object that maps tokens (specified by their token ID in the
+        # tokenizer) to an associated bias value from -100 to 100. Mathematically, the
+        # bias is added to the logits generated by the model prior to sampling. The exact
+        # effect will vary per model, but values between -1 and 1 should decrease or
+        # increase likelihood of selection; values like -100 or 100 should result in a ban
+        # or exclusive selection of the relevant token.
         attr_accessor logit_bias: ::Hash[Symbol, Integer]?
 
+        # Whether to return log probabilities of the output tokens or not. If true,
+        # returns the log probabilities of each output token returned in the `content` of
+        # `message`.
         attr_accessor logprobs: bool?
 
+        # An upper bound for the number of tokens that can be generated for a completion,
+        # including visible output tokens and
+        # [reasoning tokens](https://developers.openai.com/api/docs/guides/reasoning).
         attr_accessor max_completion_tokens: Integer?
 
+        # The maximum number of [tokens](https://platform.openai.com/tokenizer) that can
+        # be generated in the chat completion. This value can be used to control
+        # [costs](https://openai.com/api/pricing/) for text generated via API.
+        #
+        # This value is now deprecated in favor of `max_completion_tokens`, and is not
+        # compatible with
+        # [o-series models](https://developers.openai.com/api/docs/guides/reasoning).
         attr_accessor max_tokens: Integer?
 
+        # Set of 16 key-value pairs that can be attached to an object. This can be useful
+        # for storing additional information about the object in a structured format, and
+        # querying for objects via API or the dashboard.
+        #
+        # Keys are strings with a maximum length of 64 characters. Values are strings with
+        # a maximum length of 512 characters.
         attr_accessor metadata: OpenAI::Models::metadata?
 
+        # Output types that you would like the model to generate. Most models are capable
+        # of generating text, which is the default:
+        #
+        # `["text"]`
+        #
+        # The `gpt-4o-audio-preview` model can also be used to
+        # [generate audio](https://developers.openai.com/api/docs/guides/audio). To
+        # request that this model generate both text and audio responses, you can use:
+        #
+        # `["text", "audio"]`
         attr_accessor modalities: ::Array[OpenAI::Models::Chat::CompletionCreateParams::modality]?
 
+        # Configuration for running moderation on the request input and generated output.
         attr_accessor moderation: OpenAI::Chat::CompletionCreateParams::Moderation?
 
+        # How many chat completion choices to generate for each input message. Note that
+        # you will be charged based on the number of generated tokens across all of the
+        # choices. Keep `n` as `1` to minimize costs.
         attr_accessor n: Integer?
 
+        # Whether to enable
+        # [parallel function calling](https://developers.openai.com/api/docs/guides/function-calling#parallel-function-calling)
+        # during tool use.
         attr_reader parallel_tool_calls: bool?
 
+        # Whether to enable
+        # [parallel function calling](https://developers.openai.com/api/docs/guides/function-calling#parallel-function-calling)
+        # during tool use.
         def parallel_tool_calls=: (bool) -> bool
 
+        # Configuration for a
+        # [Predicted Output](https://developers.openai.com/api/docs/guides/predicted-outputs),
+        # which can greatly improve response times when large parts of the model response
+        # are known ahead of time. This is most common when you are regenerating a file
+        # with only minor changes to most of the content.
         attr_accessor prediction: OpenAI::Chat::ChatCompletionPredictionContent?
 
+        # Number between -2.0 and 2.0. Positive values penalize new tokens based on
+        # whether they appear in the text so far, increasing the model's likelihood to
+        # talk about new topics.
         attr_accessor presence_penalty: Float?
 
+        # Used by OpenAI to cache responses for similar requests to optimize your cache
+        # hit rates. Replaces the `user` field.
+        # [Learn more](https://developers.openai.com/api/docs/guides/prompt-caching).
         attr_accessor prompt_cache_key: String?
 
+        # Options for prompt caching. Supported for `gpt-5.6` and later models. By
+        # default, OpenAI automatically chooses one implicit cache breakpoint. You can add
+        # explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each
+        # request can write up to four breakpoints. For cache matching, OpenAI considers
+        # up to the latest 80 breakpoints in the conversation, without a content-block
+        # lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The
+        # `ttl` defaults to `30m`, which is currently the only supported value. See the
+        # [prompt caching guide](https://developers.openai.com/api/docs/guides/prompt-caching)
+        # for current details.
         attr_reader prompt_cache_options: OpenAI::Chat::CompletionCreateParams::PromptCacheOptions?
 
+        # Options for prompt caching. Supported for `gpt-5.6` and later models. By
+        # default, OpenAI automatically chooses one implicit cache breakpoint. You can add
+        # explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each
+        # request can write up to four breakpoints. For cache matching, OpenAI considers
+        # up to the latest 80 breakpoints in the conversation, without a content-block
+        # lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The
+        # `ttl` defaults to `30m`, which is currently the only supported value. See the
+        # [prompt caching guide](https://developers.openai.com/api/docs/guides/prompt-caching)
+        # for current details.
         def prompt_cache_options=: (
           OpenAI::Chat::CompletionCreateParams::PromptCacheOptions
         ) -> OpenAI::Chat::CompletionCreateParams::PromptCacheOptions
 
+        # Deprecated. Use `prompt_cache_options.ttl` instead.
+        #
+        # The retention policy for the prompt cache. Set to `24h` to enable extended
+        # prompt caching, which keeps cached prefixes active for longer, up to a maximum
+        # of 24 hours.
+        # [Learn more](https://developers.openai.com/api/docs/guides/prompt-caching#prompt-cache-retention).
+        # This field expresses a maximum retention policy, while
+        # `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two fields
+        # are independent and do not interact. For `gpt-5.5`, `gpt-5.5-pro`, and future
+        # models, only `24h` is supported.
+        #
+        # For older models that support both `in_memory` and `24h`, the default depends on
+        # your organization's data retention policy:
+        #
+        # - Organizations without ZDR enabled default to `24h`.
+        # - Organizations with ZDR enabled default to `in_memory` when
+        #   `prompt_cache_retention` is not specified.
         attr_accessor prompt_cache_retention: OpenAI::Models::Chat::CompletionCreateParams::prompt_cache_retention?
 
+        # Constrains effort on reasoning for reasoning models. Currently supported values
+        # are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. Reducing
+        # reasoning effort can result in faster responses and fewer tokens used on
+        # reasoning in a response. Not all reasoning models support every value. See the
+        # [reasoning guide](https://developers.openai.com/api/docs/guides/reasoning) for
+        # model-specific support.
         attr_accessor reasoning_effort: OpenAI::Models::reasoning_effort?
 
+        # An object specifying the format that the model must output.
+        #
+        # Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured
+        # Outputs which ensures the model will match your supplied JSON schema. Learn more
+        # in the
+        # [Structured Outputs guide](https://developers.openai.com/api/docs/guides/structured-outputs).
+        #
+        # Setting to `{ "type": "json_object" }` enables the older JSON mode, which
+        # ensures the message the model generates is valid JSON. Using `json_schema` is
+        # preferred for models that support it.
         attr_reader response_format: OpenAI::Models::Chat::CompletionCreateParams::response_format?
 
+        # An object specifying the format that the model must output.
+        #
+        # Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured
+        # Outputs which ensures the model will match your supplied JSON schema. Learn more
+        # in the
+        # [Structured Outputs guide](https://developers.openai.com/api/docs/guides/structured-outputs).
+        #
+        # Setting to `{ "type": "json_object" }` enables the older JSON mode, which
+        # ensures the message the model generates is valid JSON. Using `json_schema` is
+        # preferred for models that support it.
         def response_format=: (
           OpenAI::Models::Chat::CompletionCreateParams::response_format
         ) -> OpenAI::Models::Chat::CompletionCreateParams::response_format
 
+        # A stable identifier used to help detect users of your application that may be
+        # violating OpenAI's usage policies. The IDs should be a string that uniquely
+        # identifies each user, with a maximum length of 64 characters. We recommend
+        # hashing their username or email address, in order to avoid sending us any
+        # identifying information.
+        # [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).
         attr_accessor safety_identifier: String?
 
+        # This feature is in Beta. If specified, our system will make a best effort to
+        # sample deterministically, such that repeated requests with the same `seed` and
+        # parameters should return the same result. Determinism is not guaranteed, and you
+        # should refer to the `system_fingerprint` response parameter to monitor changes
+        # in the backend.
         attr_accessor seed: Integer?
 
+        # Specifies the processing type used for serving the request.
+        #
+        # - If set to 'auto', then the request will be processed with the service tier
+        #   configured in the Project settings. Unless otherwise configured, the Project
+        #   will use 'default'.
+        # - If set to 'default', then the request will be processed with the standard
+        #   pricing and performance for the selected model.
+        # - If set to
+        #   '[flex](https://developers.openai.com/api/docs/guides/flex-processing)', then
+        #   the request will be processed with the Flex Processing service tier.
+        # - To opt-in to
+        #   [Fast mode](https://developers.openai.com/api/docs/guides/fast-mode) at the
+        #   request level, include the `service_tier=fast` or `service_tier=priority`
+        #   parameter for Responses or Chat Completions. The response will show
+        #   `service_tier=priority` regardless of if you specify `service_tier=fast` or
+        #   `priority` in your request.
+        # - When not set, the default behavior is 'auto'.
+        #
+        # When the `service_tier` parameter is set, the response body will include the
+        # `service_tier` value based on the processing mode actually used to serve the
+        # request. This response value may be different from the value set in the
+        # parameter.
         attr_accessor service_tier: OpenAI::Models::Chat::CompletionCreateParams::service_tier?
 
+        # Not supported with latest reasoning models `o3` and `o4-mini`.
+        #
+        # Up to 4 sequences where the API will stop generating further tokens. The
+        # returned text will not contain the stop sequence.
         attr_accessor stop: OpenAI::Models::Chat::CompletionCreateParams::stop?
 
+        # Whether or not to store the output of this chat completion request for use in
+        # our
+        # [model distillation](https://developers.openai.com/api/docs/guides/supervised-fine-tuning#distilling-from-a-larger-model)
+        # or [evals](https://developers.openai.com/api/docs/guides/evals) products.
+        #
+        # Supports text and image inputs. Note: image inputs over 8MB will be dropped.
         attr_accessor store: bool?
 
+        # Options for streaming response. Only set this when you set `stream: true`.
         attr_accessor stream_options: OpenAI::Chat::ChatCompletionStreamOptions?
 
+        # What sampling temperature to use, between 0 and 2. Higher values like 0.8 will
+        # make the output more random, while lower values like 0.2 will make it more
+        # focused and deterministic. We generally recommend altering this or `top_p` but
+        # not both.
         attr_accessor temperature: Float?
 
+        # Controls which (if any) tool is called by the model. `none` means the model will
+        # not call any tool and instead generates a message. `auto` means the model can
+        # pick between generating a message or calling one or more tools. `required` means
+        # the model must call one or more tools. Specifying a particular tool via
+        # `{"type": "function", "function": {"name": "my_function"}}` forces the model to
+        # call that tool.
+        #
+        # `none` is the default when no tools are present. `auto` is the default if tools
+        # are present.
         attr_reader tool_choice: OpenAI::Models::Chat::chat_completion_tool_choice_option?
 
+        # Controls which (if any) tool is called by the model. `none` means the model will
+        # not call any tool and instead generates a message. `auto` means the model can
+        # pick between generating a message or calling one or more tools. `required` means
+        # the model must call one or more tools. Specifying a particular tool via
+        # `{"type": "function", "function": {"name": "my_function"}}` forces the model to
+        # call that tool.
+        #
+        # `none` is the default when no tools are present. `auto` is the default if tools
+        # are present.
         def tool_choice=: (
           OpenAI::Models::Chat::chat_completion_tool_choice_option
         ) -> OpenAI::Models::Chat::chat_completion_tool_choice_option
 
+        # A list of tools the model may call. You can provide either
+        # [custom tools](https://developers.openai.com/api/docs/guides/function-calling#custom-tools)
+        # or
+        # [function tools](https://developers.openai.com/api/docs/guides/function-calling).
         attr_reader tools: ::Array[OpenAI::Models::Chat::chat_completion_tool]?
 
+        # A list of tools the model may call. You can provide either
+        # [custom tools](https://developers.openai.com/api/docs/guides/function-calling#custom-tools)
+        # or
+        # [function tools](https://developers.openai.com/api/docs/guides/function-calling).
         def tools=: (
           ::Array[OpenAI::Models::Chat::chat_completion_tool]
         ) -> ::Array[OpenAI::Models::Chat::chat_completion_tool]
 
+        # An integer between 0 and 20 specifying the maximum number of most likely tokens
+        # to return at each token position, each with an associated log probability. In
+        # some cases, the number of returned tokens may be fewer than requested.
+        # `logprobs` must be set to `true` if this parameter is used.
         attr_accessor top_logprobs: Integer?
 
+        # An alternative to sampling with temperature, called nucleus sampling, where the
+        # model considers the results of the tokens with top_p probability mass. So 0.1
+        # means only the tokens comprising the top 10% probability mass are considered.
+        #
+        # We generally recommend altering this or `temperature` but not both.
         attr_accessor top_p: Float?
 
+        # This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use
+        # `prompt_cache_key` instead to maintain caching optimizations. A stable
+        # identifier for your end-users. Used to boost cache hit rates by better bucketing
+        # similar requests and to help OpenAI detect and prevent abuse.
+        # [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).
         attr_reader user: String?
 
+        # This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use
+        # `prompt_cache_key` instead to maintain caching optimizations. A stable
+        # identifier for your end-users. Used to boost cache hit rates by better bucketing
+        # similar requests and to help OpenAI detect and prevent abuse.
+        # [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).
         def user=: (String) -> String
 
+        # Constrains the verbosity of the model's response. Lower values will result in
+        # more concise responses, while higher values will result in more verbose
+        # responses. Currently supported values are `low`, `medium`, and `high`. The
+        # default is `medium`.
         attr_accessor verbosity: OpenAI::Models::Chat::CompletionCreateParams::verbosity?
 
+        # This tool searches the web for relevant results to use in a response. Learn more
+        # about the
+        # [web search tool](https://developers.openai.com/api/docs/guides/tools-web-search).
         attr_reader web_search_options: OpenAI::Chat::CompletionCreateParams::WebSearchOptions?
 
+        # This tool searches the web for relevant results to use in a response. Learn more
+        # about the
+        # [web search tool](https://developers.openai.com/api/docs/guides/tools-web-search).
         def web_search_options=: (
           OpenAI::Chat::CompletionCreateParams::WebSearchOptions
         ) -> OpenAI::Chat::CompletionCreateParams::WebSearchOptions
 
+        # @param messages
+        #   A list of messages comprising the conversation so far. Depending on the
+        #   [model](https://developers.openai.com/api/docs/models) you use, different
+        #   message types (modalities) are supported, like
+        #   [text](https://developers.openai.com/api/docs/guides/text),
+        #   [images](https://developers.openai.com/api/docs/guides/images-vision), and
+        #   [audio](https://developers.openai.com/api/docs/guides/audio).
+        # @param model
+        #   Model ID used to generate the response, like `gpt-6-astra` or `o3`. OpenAI
+        #   offers a wide range of models with different capabilities, performance
+        #   characteristics, and price points. Refer to the
+        #   [model guide](https://developers.openai.com/api/docs/models) to browse and
+        #   compare available models.
+        # @param audio
+        #   Parameters for audio output. Required when audio output is requested with
+        #   `modalities: ["audio"]`.
+        #   [Learn more](https://developers.openai.com/api/docs/guides/audio).
+        # @param frequency_penalty
+        #   Number between -2.0 and 2.0. Positive values penalize new tokens based on their
+        #   existing frequency in the text so far, decreasing the model's likelihood to
+        #   repeat the same line verbatim.
+        # @param function_call
+        #   Deprecated in favor of `tool_choice`.
+        #
+        #   Controls which (if any) function is called by the model.
+        #
+        #   `none` means the model will not call a function and instead generates a message.
+        #
+        #   `auto` means the model can pick between generating a message or calling a
+        #   function.
+        #
+        #   Specifying a particular function via `{"name": "my_function"}` forces the model
+        #   to call that function.
+        #
+        #   `none` is the default when no functions are present. `auto` is the default if
+        #   functions are present.
+        # @param functions
+        #   Deprecated in favor of `tools`.
+        #
+        #   A list of functions the model may generate JSON inputs for.
+        # @param logit_bias
+        #   Modify the likelihood of specified tokens appearing in the completion.
+        #
+        #   Accepts a JSON object that maps tokens (specified by their token ID in the
+        #   tokenizer) to an associated bias value from -100 to 100. Mathematically, the
+        #   bias is added to the logits generated by the model prior to sampling. The exact
+        #   effect will vary per model, but values between -1 and 1 should decrease or
+        #   increase likelihood of selection; values like -100 or 100 should result in a ban
+        #   or exclusive selection of the relevant token.
+        # @param logprobs
+        #   Whether to return log probabilities of the output tokens or not. If true,
+        #   returns the log probabilities of each output token returned in the `content` of
+        #   `message`.
+        # @param max_completion_tokens
+        #   An upper bound for the number of tokens that can be generated for a completion,
+        #   including visible output tokens and
+        #   [reasoning tokens](https://developers.openai.com/api/docs/guides/reasoning).
+        # @param max_tokens
+        #   The maximum number of [tokens](https://platform.openai.com/tokenizer) that can
+        #   be generated in the chat completion. This value can be used to control
+        #   [costs](https://openai.com/api/pricing/) for text generated via API.
+        #
+        #   This value is now deprecated in favor of `max_completion_tokens`, and is not
+        #   compatible with
+        #   [o-series models](https://developers.openai.com/api/docs/guides/reasoning).
+        # @param metadata
+        #   Set of 16 key-value pairs that can be attached to an object. This can be useful
+        #   for storing additional information about the object in a structured format, and
+        #   querying for objects via API or the dashboard.
+        #
+        #   Keys are strings with a maximum length of 64 characters. Values are strings with
+        #   a maximum length of 512 characters.
+        # @param modalities
+        #   Output types that you would like the model to generate. Most models are capable
+        #   of generating text, which is the default:
+        #
+        #   `["text"]`
+        #
+        #   The `gpt-4o-audio-preview` model can also be used to
+        #   [generate audio](https://developers.openai.com/api/docs/guides/audio). To
+        #   request that this model generate both text and audio responses, you can use:
+        #
+        #   `["text", "audio"]`
+        # @param moderation
+        #   Configuration for running moderation on the request input and generated output.
+        # @param n
+        #   How many chat completion choices to generate for each input message. Note that
+        #   you will be charged based on the number of generated tokens across all of the
+        #   choices. Keep `n` as `1` to minimize costs.
+        # @param parallel_tool_calls
+        #   Whether to enable
+        #   [parallel function calling](https://developers.openai.com/api/docs/guides/function-calling#parallel-function-calling)
+        #   during tool use.
+        # @param prediction
+        #   Configuration for a
+        #   [Predicted Output](https://developers.openai.com/api/docs/guides/predicted-outputs),
+        #   which can greatly improve response times when large parts of the model response
+        #   are known ahead of time. This is most common when you are regenerating a file
+        #   with only minor changes to most of the content.
+        # @param presence_penalty
+        #   Number between -2.0 and 2.0. Positive values penalize new tokens based on
+        #   whether they appear in the text so far, increasing the model's likelihood to
+        #   talk about new topics.
+        # @param prompt_cache_key
+        #   Used by OpenAI to cache responses for similar requests to optimize your cache
+        #   hit rates. Replaces the `user` field.
+        #   [Learn more](https://developers.openai.com/api/docs/guides/prompt-caching).
+        # @param prompt_cache_options
+        #   Options for prompt caching. Supported for `gpt-5.6` and later models. By
+        #   default, OpenAI automatically chooses one implicit cache breakpoint. You can add
+        #   explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each
+        #   request can write up to four breakpoints. For cache matching, OpenAI considers
+        #   up to the latest 80 breakpoints in the conversation, without a content-block
+        #   lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The
+        #   `ttl` defaults to `30m`, which is currently the only supported value. See the
+        #   [prompt caching guide](https://developers.openai.com/api/docs/guides/prompt-caching)
+        #   for current details.
+        # @param prompt_cache_retention
+        #   Deprecated. Use `prompt_cache_options.ttl` instead.
+        #
+        #   The retention policy for the prompt cache. Set to `24h` to enable extended
+        #   prompt caching, which keeps cached prefixes active for longer, up to a maximum
+        #   of 24 hours.
+        #   [Learn more](https://developers.openai.com/api/docs/guides/prompt-caching#prompt-cache-retention).
+        #   This field expresses a maximum retention policy, while
+        #   `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two fields
+        #   are independent and do not interact. For `gpt-5.5`, `gpt-5.5-pro`, and future
+        #   models, only `24h` is supported.
+        #
+        #   For older models that support both `in_memory` and `24h`, the default depends on
+        #   your organization's data retention policy:
+        #
+        #   - Organizations without ZDR enabled default to `24h`.
+        #   - Organizations with ZDR enabled default to `in_memory` when
+        #     `prompt_cache_retention` is not specified.
+        # @param reasoning_effort
+        #   Constrains effort on reasoning for reasoning models. Currently supported values
+        #   are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. Reducing
+        #   reasoning effort can result in faster responses and fewer tokens used on
+        #   reasoning in a response. Not all reasoning models support every value. See the
+        #   [reasoning guide](https://developers.openai.com/api/docs/guides/reasoning) for
+        #   model-specific support.
+        # @param response_format
+        #   An object specifying the format that the model must output.
+        #
+        #   Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured
+        #   Outputs which ensures the model will match your supplied JSON schema. Learn more
+        #   in the
+        #   [Structured Outputs guide](https://developers.openai.com/api/docs/guides/structured-outputs).
+        #
+        #   Setting to `{ "type": "json_object" }` enables the older JSON mode, which
+        #   ensures the message the model generates is valid JSON. Using `json_schema` is
+        #   preferred for models that support it.
+        # @param safety_identifier
+        #   A stable identifier used to help detect users of your application that may be
+        #   violating OpenAI's usage policies. The IDs should be a string that uniquely
+        #   identifies each user, with a maximum length of 64 characters. We recommend
+        #   hashing their username or email address, in order to avoid sending us any
+        #   identifying information.
+        #   [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).
+        # @param seed
+        #   This feature is in Beta. If specified, our system will make a best effort to
+        #   sample deterministically, such that repeated requests with the same `seed` and
+        #   parameters should return the same result. Determinism is not guaranteed, and you
+        #   should refer to the `system_fingerprint` response parameter to monitor changes
+        #   in the backend.
+        # @param service_tier
+        #   Specifies the processing type used for serving the request.
+        #
+        #   - If set to 'auto', then the request will be processed with the service tier
+        #     configured in the Project settings. Unless otherwise configured, the Project
+        #     will use 'default'.
+        #   - If set to 'default', then the request will be processed with the standard
+        #     pricing and performance for the selected model.
+        #   - If set to
+        #     '[flex](https://developers.openai.com/api/docs/guides/flex-processing)', then
+        #     the request will be processed with the Flex Processing service tier.
+        #   - To opt-in to
+        #     [Fast mode](https://developers.openai.com/api/docs/guides/fast-mode) at the
+        #     request level, include the `service_tier=fast` or `service_tier=priority`
+        #     parameter for Responses or Chat Completions. The response will show
+        #     `service_tier=priority` regardless of if you specify `service_tier=fast` or
+        #     `priority` in your request.
+        #   - When not set, the default behavior is 'auto'.
+        #
+        #   When the `service_tier` parameter is set, the response body will include the
+        #   `service_tier` value based on the processing mode actually used to serve the
+        #   request. This response value may be different from the value set in the
+        #   parameter.
+        # @param stop
+        #   Not supported with latest reasoning models `o3` and `o4-mini`.
+        #
+        #   Up to 4 sequences where the API will stop generating further tokens. The
+        #   returned text will not contain the stop sequence.
+        # @param store
+        #   Whether or not to store the output of this chat completion request for use in
+        #   our
+        #   [model distillation](https://developers.openai.com/api/docs/guides/supervised-fine-tuning#distilling-from-a-larger-model)
+        #   or [evals](https://developers.openai.com/api/docs/guides/evals) products.
+        #
+        #   Supports text and image inputs. Note: image inputs over 8MB will be dropped.
+        # @param stream_options
+        #   Options for streaming response. Only set this when you set `stream: true`.
+        # @param temperature
+        #   What sampling temperature to use, between 0 and 2. Higher values like 0.8 will
+        #   make the output more random, while lower values like 0.2 will make it more
+        #   focused and deterministic. We generally recommend altering this or `top_p` but
+        #   not both.
+        # @param tool_choice
+        #   Controls which (if any) tool is called by the model. `none` means the model will
+        #   not call any tool and instead generates a message. `auto` means the model can
+        #   pick between generating a message or calling one or more tools. `required` means
+        #   the model must call one or more tools. Specifying a particular tool via
+        #   `{"type": "function", "function": {"name": "my_function"}}` forces the model to
+        #   call that tool.
+        #
+        #   `none` is the default when no tools are present. `auto` is the default if tools
+        #   are present.
+        # @param tools
+        #   A list of tools the model may call. You can provide either
+        #   [custom tools](https://developers.openai.com/api/docs/guides/function-calling#custom-tools)
+        #   or
+        #   [function tools](https://developers.openai.com/api/docs/guides/function-calling).
+        # @param top_logprobs
+        #   An integer between 0 and 20 specifying the maximum number of most likely tokens
+        #   to return at each token position, each with an associated log probability. In
+        #   some cases, the number of returned tokens may be fewer than requested.
+        #   `logprobs` must be set to `true` if this parameter is used.
+        # @param top_p
+        #   An alternative to sampling with temperature, called nucleus sampling, where the
+        #   model considers the results of the tokens with top_p probability mass. So 0.1
+        #   means only the tokens comprising the top 10% probability mass are considered.
+        #
+        #   We generally recommend altering this or `temperature` but not both.
+        # @param user
+        #   This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use
+        #   `prompt_cache_key` instead to maintain caching optimizations. A stable
+        #   identifier for your end-users. Used to boost cache hit rates by better bucketing
+        #   similar requests and to help OpenAI detect and prevent abuse.
+        #   [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).
+        # @param verbosity
+        #   Constrains the verbosity of the model's response. Lower values will result in
+        #   more concise responses, while higher values will result in more verbose
+        #   responses. Currently supported values are `low`, `medium`, and `high`. The
+        #   default is `medium`.
+        # @param web_search_options
+        #   This tool searches the web for relevant results to use in a response. Learn more
+        #   about the
+        #   [web search tool](https://developers.openai.com/api/docs/guides/tools-web-search).
         def initialize: (
           messages: ::Array[OpenAI::Models::Chat::chat_completion_message_param],
           model: OpenAI::Models::Chat::CompletionCreateParams::model,
@@ -267,18 +789,52 @@ module OpenAI
           }
 
         class Function < OpenAI::Internal::Type::BaseModel
+          # The name of the function to be called. Must be a-z, A-Z, 0-9, or contain
+          # underscores and dashes, with a maximum length of 64.
           attr_accessor name: String
 
+          # A description of what the function does, used by the model to choose when and
+          # how to call the function.
           attr_reader description: String?
 
+          # A description of what the function does, used by the model to choose when and
+          # how to call the function.
           def description=: (String) -> String
 
+          # The parameters the functions accepts, described as a JSON Schema object. See the
+          # [guide](https://developers.openai.com/api/docs/guides/function-calling) for
+          # examples, and the
+          # [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for
+          # documentation about the format.
+          #
+          # Omitting `parameters` defines a function with an empty parameter list.
           attr_reader parameters: OpenAI::Models::function_parameters?
 
+          # The parameters the functions accepts, described as a JSON Schema object. See the
+          # [guide](https://developers.openai.com/api/docs/guides/function-calling) for
+          # examples, and the
+          # [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for
+          # documentation about the format.
+          #
+          # Omitting `parameters` defines a function with an empty parameter list.
           def parameters=: (
             OpenAI::Models::function_parameters
           ) -> OpenAI::Models::function_parameters
 
+          # @param name
+          #   The name of the function to be called. Must be a-z, A-Z, 0-9, or contain
+          #   underscores and dashes, with a maximum length of 64.
+          # @param description
+          #   A description of what the function does, used by the model to choose when and
+          #   how to call the function.
+          # @param parameters
+          #   The parameters the functions accepts, described as a JSON Schema object. See the
+          #   [guide](https://developers.openai.com/api/docs/guides/function-calling) for
+          #   examples, and the
+          #   [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for
+          #   documentation about the format.
+          #
+          #   Omitting `parameters` defines a function with an empty parameter list.
           def initialize: (
             name: String,
             ?description: String,
@@ -310,10 +866,18 @@ module OpenAI
           }
 
         class Moderation < OpenAI::Internal::Type::BaseModel
+          # The moderation model to use for moderated completions, e.g.
+          # 'omni-moderation-latest'.
           attr_accessor model: String
 
+          # The policy to apply to moderated response input and output.
           attr_accessor policy: OpenAI::Chat::CompletionCreateParams::Moderation::Policy?
 
+          # @param model
+          #   The moderation model to use for moderated completions, e.g.
+          #   'omni-moderation-latest'.
+          # @param policy
+          #   The policy to apply to moderated response input and output.
           def initialize: (
             model: String,
             ?policy: OpenAI::Chat::CompletionCreateParams::Moderation::Policy?
@@ -331,10 +895,16 @@ module OpenAI
             }
 
           class Policy < OpenAI::Internal::Type::BaseModel
+            # The moderation policy for the response input.
             attr_accessor input: OpenAI::Chat::CompletionCreateParams::Moderation::Policy::Input?
 
+            # The moderation policy for the response output.
             attr_accessor output: OpenAI::Chat::CompletionCreateParams::Moderation::Policy::Output?
 
+            # @param input
+            #   The moderation policy for the response input.
+            # @param output
+            #   The moderation policy for the response output.
             def initialize: (
               ?input: OpenAI::Chat::CompletionCreateParams::Moderation::Policy::Input?,
               ?output: OpenAI::Chat::CompletionCreateParams::Moderation::Policy::Output?
@@ -410,18 +980,47 @@ module OpenAI
           }
 
         class PromptCacheOptions < OpenAI::Internal::Type::BaseModel
+          # Controls whether OpenAI automatically creates an implicit cache breakpoint.
+          # Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint
+          # and writes up to the latest three explicit breakpoints in the request. With
+          # `explicit`, OpenAI does not create an implicit breakpoint and writes up to the
+          # latest four explicit breakpoints. If there are no explicit breakpoints, the
+          # request does not use prompt caching.
           attr_reader mode: OpenAI::Models::Chat::CompletionCreateParams::PromptCacheOptions::mode?
 
+          # Controls whether OpenAI automatically creates an implicit cache breakpoint.
+          # Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint
+          # and writes up to the latest three explicit breakpoints in the request. With
+          # `explicit`, OpenAI does not create an implicit breakpoint and writes up to the
+          # latest four explicit breakpoints. If there are no explicit breakpoints, the
+          # request does not use prompt caching.
           def mode=: (
             OpenAI::Models::Chat::CompletionCreateParams::PromptCacheOptions::mode
           ) -> OpenAI::Models::Chat::CompletionCreateParams::PromptCacheOptions::mode
 
+          # The minimum lifetime applied to every implicit and explicit cache breakpoint
+          # written by the request. Defaults to `30m`, which is currently the only supported
+          # value. The backend may retain cache entries for longer.
           attr_reader ttl: OpenAI::Models::Chat::CompletionCreateParams::PromptCacheOptions::ttl?
 
+          # The minimum lifetime applied to every implicit and explicit cache breakpoint
+          # written by the request. Defaults to `30m`, which is currently the only supported
+          # value. The backend may retain cache entries for longer.
           def ttl=: (
             OpenAI::Models::Chat::CompletionCreateParams::PromptCacheOptions::ttl
           ) -> OpenAI::Models::Chat::CompletionCreateParams::PromptCacheOptions::ttl
 
+          # @param mode
+          #   Controls whether OpenAI automatically creates an implicit cache breakpoint.
+          #   Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint
+          #   and writes up to the latest three explicit breakpoints in the request. With
+          #   `explicit`, OpenAI does not create an implicit breakpoint and writes up to the
+          #   latest four explicit breakpoints. If there are no explicit breakpoints, the
+          #   request does not use prompt caching.
+          # @param ttl
+          #   The minimum lifetime applied to every implicit and explicit cache breakpoint
+          #   written by the request. Defaults to `30m`, which is currently the only supported
+          #   value. The backend may retain cache entries for longer.
           def initialize: (
             ?mode: OpenAI::Models::Chat::CompletionCreateParams::PromptCacheOptions::mode,
             ?ttl: OpenAI::Models::Chat::CompletionCreateParams::PromptCacheOptions::ttl
@@ -521,14 +1120,24 @@ module OpenAI
           }
 
         class WebSearchOptions < OpenAI::Internal::Type::BaseModel
+          # High level guidance for the amount of context window space to use for the
+          # search. One of `low`, `medium`, or `high`. `medium` is the default.
           attr_reader search_context_size: OpenAI::Models::Chat::CompletionCreateParams::WebSearchOptions::search_context_size?
 
+          # High level guidance for the amount of context window space to use for the
+          # search. One of `low`, `medium`, or `high`. `medium` is the default.
           def search_context_size=: (
             OpenAI::Models::Chat::CompletionCreateParams::WebSearchOptions::search_context_size
           ) -> OpenAI::Models::Chat::CompletionCreateParams::WebSearchOptions::search_context_size
 
+          # Approximate location parameters for the search.
           attr_accessor user_location: OpenAI::Chat::CompletionCreateParams::WebSearchOptions::UserLocation?
 
+          # @param search_context_size
+          #   High level guidance for the amount of context window space to use for the
+          #   search. One of `low`, `medium`, or `high`. `medium` is the default.
+          # @param user_location
+          #   Approximate location parameters for the search.
           def initialize: (
             ?search_context_size: OpenAI::Models::Chat::CompletionCreateParams::WebSearchOptions::search_context_size,
             ?user_location: OpenAI::Chat::CompletionCreateParams::WebSearchOptions::UserLocation?
@@ -558,10 +1167,16 @@ module OpenAI
             }
 
           class UserLocation < OpenAI::Internal::Type::BaseModel
+            # Approximate location parameters for the search.
             attr_accessor approximate: OpenAI::Chat::CompletionCreateParams::WebSearchOptions::UserLocation::Approximate
 
+            # The type of location approximation. Always `approximate`.
             attr_accessor type: :approximate
 
+            # @param approximate
+            #   Approximate location parameters for the search.
+            # @param type
+            #   The type of location approximation. Always `approximate`.
             def initialize: (
               approximate: OpenAI::Chat::CompletionCreateParams::WebSearchOptions::UserLocation::Approximate,
               ?type: :approximate
@@ -581,22 +1196,44 @@ module OpenAI
               }
 
             class Approximate < OpenAI::Internal::Type::BaseModel
+              # Free text input for the city of the user, e.g. `San Francisco`.
               attr_reader city: String?
 
+              # Free text input for the city of the user, e.g. `San Francisco`.
               def city=: (String) -> String
 
+              # The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of
+              # the user, e.g. `US`.
               attr_reader country: String?
 
+              # The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of
+              # the user, e.g. `US`.
               def country=: (String) -> String
 
+              # Free text input for the region of the user, e.g. `California`.
               attr_reader region: String?
 
+              # Free text input for the region of the user, e.g. `California`.
               def region=: (String) -> String
 
+              # The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the
+              # user, e.g. `America/Los_Angeles`.
               attr_reader timezone: String?
 
+              # The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the
+              # user, e.g. `America/Los_Angeles`.
               def timezone=: (String) -> String
 
+              # @param city
+              #   Free text input for the city of the user, e.g. `San Francisco`.
+              # @param country
+              #   The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of
+              #   the user, e.g. `US`.
+              # @param region
+              #   Free text input for the region of the user, e.g. `California`.
+              # @param timezone
+              #   The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the
+              #   user, e.g. `America/Los_Angeles`.
               def initialize: (
                 ?city: String,
                 ?country: String,