openai_interface/chat/create/

request.rs

//! This module contains the request body and POST method for the chat completion API.

use std::collections::HashMap;

use serde::{Deserialize, Serialize};
use url::Url;

use crate::{
    chat::ServiceTier,
    errors::OapiError,
    rest::post::{Post, PostNoStream, PostStream},
};

/// Creates a model response for the given chat conversation.
///
/// # Example
///
/// ```rust,no_run
/// use futures_util::StreamExt;
/// use openai_interface::chat::create::request::{Message, RequestBody};
/// use openai_interface::rest::{default_client, post::PostStream, RequestOptions};
///
/// const DEEPSEEK_CHAT_URL: &'static str = "https://api.deepseek.com";
/// const DEEPSEEK_MODEL: &'static str = "deepseek-v4-flash";
///
/// #[tokio::main]
/// async fn main() -> Result<(), Box<dyn std::error::Error>> {
///     // Needs the `ferritls` cargo feature; drop this line if you install
///     // your own rustls crypto provider (see `openai_interface::rest`).
///     # #[cfg(feature = "ferritls")]
///     openai_interface::rest::install_crypto_provider().ok();
///
///     let request = RequestBody {
///         messages: vec![
///             Message::system("This is a request of test purpose. Reply briefly"),
///             Message::user("What's your name?"),
///         ],
///         model: DEEPSEEK_MODEL.to_string(),
///         stream: Some(true),
///         ..Default::default()
///     };
///
///     let mut response = request
///         .get_stream_response_string(&default_client(), DEEPSEEK_CHAT_URL, &RequestOptions::bearer("YOUR_API_KEY"))
///         .await?;
///
///     while let Some(chunk) = response.next().await {
///         println!("{}", chunk?);
///     }
///     Ok(())
/// }
/// ```
#[derive(Serialize, Deserialize, Debug, Default, Clone)]
pub struct RequestBody {
    /// Parameters for audio output. Required when audio output is requested
    /// with `modalities: ["audio"]`.
    /// [Learn more](https://platform.openai.com/docs/guides/audio).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub audio: Option<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.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub frequency_penalty: Option<f32>,

    /// 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`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub logprobs: Option<bool>,

    /// An upper bound for the number of tokens that can be generated for a completion,
    /// including visible output tokens and reasoning tokens.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub max_completion_tokens: Option<u32>,

    /// The maximum number of tokens that can be generated in the chat completion.
    /// Deprecated according to OpenAI's Python SDK in favour of
    /// `max_completion_tokens`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub max_tokens: Option<u32>,

    /// A list of messages comprising the conversation so far.
    pub messages: Vec<Message>,

    /// 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.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub logit_bias: Option<HashMap<u32, i32>>,

    /// Configuration for running moderation on the request input and
    /// generated output.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub moderation: Option<ChatModerationParam>,

    /// 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.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub metadata: Option<HashMap<String, String>>,

    /// 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://platform.openai.com/docs/guides/audio). To request that
    /// this model generate both text and audio responses, you can use:
    ///
    /// `["text", "audio"]`
    #[serde(skip_serializing_if = "Option::is_none")]
    pub modalities: Option<Vec<Modality>>,

    /// Name of the model to use to generate the response.
    pub model: String, // The type of this attribute needs improvements.

    /// 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.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub n: Option<u32>,

    /// Whether to enable
    /// [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling)
    /// during tool use.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub parallel_tool_calls: Option<bool>,

    /// Static predicted output content, such as the content of a text file that is
    /// being regenerated.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub prediction: Option<ChatCompletionPredictionContentParam>,

    /// 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.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub presence_penalty: Option<f32>,

    /// Used by OpenAI to cache responses for similar requests to optimize your cache
    /// hit rates. Replaces the `user` field.
    /// [Learn more](https://platform.openai.com/docs/guides/prompt-caching).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub prompt_cache_key: Option<String>,

    /// Options for prompt caching. Supported for `gpt-5.6` and later models.
    /// By default, OpenAI automatically chooses one implicit cache breakpoint;
    /// set `mode` to `explicit` to disable the implicit breakpoint.
    /// [Learn more](https://platform.openai.com/docs/guides/prompt-caching).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub prompt_cache_options: Option<PromptCacheOptions>,

    /// Constrains effort on reasoning for
    /// [reasoning models](https://platform.openai.com/docs/guides/reasoning).
    /// Currently supported values are `none`, `minimal`, `low`, `medium`,
    /// `high`, `xhigh`, and `max` (model-dependent). Reducing reasoning
    /// effort can result in faster responses and fewer tokens used on
    /// reasoning in a response. Defaults are provider- and model-dependent:
    /// e.g. `medium` for GPT-5.5. Providers map unsupported values to the
    /// nearest effort level.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reasoning_effort: Option<ReasoningEffort>,

    /// 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://platform.openai.com/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.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub response_format: Option<ResponseFormat>,

    /// 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. It is recommended to hash their username or email address, in
    /// order to avoid sending any identifying information.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub safety_identifier: Option<String>,

    /// If specified, the system will make a best effort to sample deterministically. Determinism
    /// is not guaranteed, and you should refer to the `system_fingerprint` response parameter to
    /// monitor changes in the backend.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub seed: Option<i64>,

    /// 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://platform.openai.com/docs/guides/flex-processing)' or
    ///   '[priority](https://openai.com/api-priority-processing/)', then the request
    ///   will be processed with the corresponding service tier.
    /// - 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.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub service_tier: Option<ServiceTier>,

    /// Up to 4 sequences where the API will stop generating further tokens. The
    /// returned text will not contain the stop sequence.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub stop: Option<StopKeywords>,

    /// Whether or not to store the output of this chat completion request for use in
    /// our [model distillation](https://platform.openai.com/docs/guides/distillation)
    /// or [evals](https://platform.openai.com/docs/guides/evals) products.
    ///
    /// Supports text and image inputs. Note: image inputs over 8MB will be dropped.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub store: Option<bool>,

    /// Whether to stream back partial progress. If set to `true` (or left as
    /// `Some(true)`), tokens will be sent as data-only
    /// [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format)
    /// as they become available, with the stream terminated by a `data: [DONE]`
    /// message.
    ///
    /// Although it is optional, you should explicitly designate it
    /// for an expected response.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub stream: Option<bool>,

    /// Options for streaming response. Only set this when you set `stream: true`
    #[serde(skip_serializing_if = "Option::is_none")]
    pub stream_options: Option<StreamOptions>,

    /// 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. It is generally recommended to alter this or `top_p` but
    /// not both.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub temperature: Option<f32>,

    /// 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.
    ///
    /// It is generally recommended to alter this or `temperature` but not both.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub top_p: Option<f32>,

    /// 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.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tool_choice: Option<ToolChoice>,

    /// A list of tools the model may call.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tools: Option<Vec<RequestTool>>,

    /// An integer between 0 and 20 specifying the number of most likely tokens to
    /// return at each token position, each with an associated log probability.
    /// `logprobs` must be set to `true` if this parameter is used.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub top_logprobs: Option<u32>,

    /// DeepSeek: controls the switch between thinking and non-thinking mode.
    /// Defaults to `enabled`. See
    /// [the DeepSeek API reference](https://api-docs.deepseek.com/api/create-chat-completion).
    #[cfg(feature = "deepseek")]
    #[serde(skip_serializing_if = "Option::is_none")]
    pub thinking: Option<DeepSeekThinking>,

    /// DeepSeek: a custom user ID. Allowed character set is `[a-zA-Z0-9\-_]`
    /// with a maximum length of 512. Do not include user privacy information.
    /// It can be used to distinguish user identities for content safety
    /// review, isolate KVCache, and schedule users.
    #[cfg(feature = "deepseek")]
    #[serde(skip_serializing_if = "Option::is_none")]
    pub user_id: Option<String>,

    /// Qwen: whether to enable thinking mode for hybrid-thinking models such
    /// as Qwen3. When set to `true`, the thinking content is returned in the
    /// `reasoning_content` field.
    #[cfg(feature = "qwen")]
    #[serde(skip_serializing_if = "Option::is_none")]
    pub enable_thinking: Option<bool>,
    /// Qwen: the maximum number of tokens available for the model's thinking
    /// (chain-of-thought) process.
    #[cfg(feature = "qwen")]
    #[serde(skip_serializing_if = "Option::is_none")]
    pub thinking_budget: Option<u32>,
    /// Qwen: the size of the candidate set for sampling during generation.
    /// Set to `null` or a value greater than 100 to disable `top_k` sampling.
    #[cfg(feature = "qwen")]
    #[serde(skip_serializing_if = "Option::is_none")]
    pub top_k: Option<u32>,

    /// 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://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub user: Option<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`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub verbosity: Option<LowMediumHighEnum>,

    /// This tool searches the web for relevant results to use in a response. Learn more
    /// about the
    /// [web search tool](https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat).
    #[serde(rename = "web_search_options", skip_serializing_if = "Option::is_none")]
    pub web_search_options: Option<WebSearchOptions>,

    /// Other request bodies that are not in standard OpenAI API and
    /// not covered by the fields above.
    #[serde(flatten, default, skip_serializing_if = "Option::is_none")]
    pub extra_body_map: Option<serde_json::Map<String, serde_json::Value>>,
}

/// A message in the conversation, tagged by `role`.
///
/// Construct messages through the convenience constructors
/// ([`Message::system`], [`Message::user`], [`Message::assistant`],
/// [`Message::tool`], [`Message::function`], [`Message::developer`]) or by
/// building the payload structs directly (`Message::User(UserMessage {
/// ..Default::default() })`), which stays source-compatible when new
/// optional fields are added.
///
/// Deserialization of an unknown `role` is an error: a message with an
/// unrecognized role cannot be forwarded, so it is treated as invalid input
/// rather than silently mapped onto a catch-all.
#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(tag = "role", rename_all = "lowercase")]
pub enum Message {
    /// The role of the message author is `system`.
    /// The field `{ role = "system" }` is added automatically.
    System(SystemMessage),
    /// The role of the message author is `user`.
    /// The field `{ role = "user" }` is added automatically.
    User(UserMessage),
    /// The role of the message author is `assistant`.
    /// The field `{ role = "assistant" }` is added automatically.
    Assistant(AssistantMessage),
    /// The role of the message author is `tool`.
    /// The field `{ role = "tool" }` is added automatically.
    Tool(ToolMessage),
    /// The role of the message author is `function`.
    /// The field `{ role = "function" }` is added automatically.
    Function(FunctionMessage),
    /// The role of the message author is `developer`.
    /// The field `{ role = "developer" }` is added automatically.
    Developer(DeveloperMessage),
}

impl Message {
    /// A system message with the given content: plain text, or an array of
    /// text content parts.
    #[must_use]
    pub fn system(content: impl Into<MessageContent>) -> Self {
        Self::System(SystemMessage {
            content: content.into(),
            name: None,
        })
    }

    /// A user message with the given content: plain text, or an array of
    /// multimodal content parts (`text`, `image_url`, `input_audio`,
    /// `file`).
    #[must_use]
    pub fn user(content: impl Into<MessageContent>) -> Self {
        Self::User(UserMessage {
            content: content.into(),
            name: None,
        })
    }

    /// An assistant message with the given text content. Build
    /// [`AssistantMessage`] directly for tool calls, audio, or reasoning
    /// content.
    #[must_use]
    pub fn assistant(content: impl Into<String>) -> Self {
        Self::Assistant(AssistantMessage {
            content: Some(content.into()),
            ..Default::default()
        })
    }

    /// A tool message responding to the tool call with the given ID.
    #[must_use]
    pub fn tool(content: impl Into<MessageContent>, tool_call_id: impl Into<String>) -> Self {
        Self::Tool(ToolMessage {
            content: content.into(),
            tool_call_id: tool_call_id.into(),
        })
    }

    /// A deprecated `function` message responding to the named function
    /// call.
    #[must_use]
    pub fn function(name: impl Into<String>, content: impl Into<String>) -> Self {
        Self::Function(FunctionMessage {
            content: content.into(),
            name: name.into(),
        })
    }

    /// A developer message with the given content: plain text, or an array
    /// of text content parts.
    #[must_use]
    pub fn developer(content: impl Into<MessageContent>) -> Self {
        Self::Developer(DeveloperMessage {
            content: content.into(),
            name: None,
        })
    }
}

/// A `system` message payload.
#[derive(Serialize, Deserialize, Debug, Clone, Default)]
pub struct SystemMessage {
    /// The contents of the system message: plain text, or an array of
    /// text content parts.
    pub content: MessageContent,
    /// An optional name for the participant.
    ///
    /// Provides the model information to differentiate between
    /// participants of the same role.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
}

/// A `user` message payload.
#[derive(Serialize, Deserialize, Debug, Clone, Default)]
pub struct UserMessage {
    /// The contents of the user message: plain text, or an array of
    /// multimodal content parts (`text`, `image_url`, `input_audio`,
    /// `file`).
    pub content: MessageContent,
    /// An optional name for the participant.
    ///
    /// Provides the model information to differentiate between
    /// participants of the same role.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
}

/// An `assistant` message payload.
#[derive(Serialize, Deserialize, Debug, Clone, Default)]
pub struct AssistantMessage {
    /// The contents of the assistant message. Required unless `tool_calls`
    /// or `function_call` is specified. (Note that `function_call` is deprecated
    /// in favour of `tool_calls`.)
    pub content: Option<String>,
    /// Data about a previous audio response from the model. Required for
    /// multi-turn audio conversations.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub audio: Option<AssistantAudio>,
    /// The refusal message by the assistant.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub refusal: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// DeepSeek (Beta): set this to `true` to force the model to start its
    /// answer by the content of the supplied prefix in this assistant
    /// message. Requires `base_url = "https://api.deepseek.com/beta"`.
    #[cfg(feature = "deepseek")]
    #[serde(default, skip_serializing_if = "is_false")]
    pub prefix: bool,
    /// The reasoning contents of the assistant message produced by thinking
    /// models (DeepSeek, Qwen3, and other reasoning models served by
    /// OpenAI-compatible backends), before the final answer. Feed it back
    /// in multi-turn thinking conversations; DeepSeek's Beta
    /// [Chat Prefix Completion](https://api-docs.deepseek.com/guides/chat_prefix_completion)
    /// also uses it as the CoT input of the last assistant message
    /// (with `prefix` set to `true`).
    #[cfg(feature = "reasoning")]
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reasoning_content: Option<String>,

    /// The tool calls generated by the model, such as function calls.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tool_calls: Option<Vec<AssistantToolCall>>,
}

/// A `tool` message payload.
#[derive(Serialize, Deserialize, Debug, Clone, Default)]
pub struct ToolMessage {
    /// The contents of the tool message: plain text, or an array of
    /// text content parts.
    pub content: MessageContent,
    /// Tool call that this message is responding to.
    pub tool_call_id: String,
}

/// A deprecated `function` message payload.
#[derive(Serialize, Deserialize, Debug, Clone, Default)]
pub struct FunctionMessage {
    /// The contents of the function message.
    pub content: String,
    /// The name of the function to call.
    pub name: String,
}

/// A `developer` message payload.
#[derive(Serialize, Deserialize, Debug, Clone, Default)]
pub struct DeveloperMessage {
    /// The contents of the developer message: plain text, or an array of
    /// text content parts.
    pub content: MessageContent,
    /// An optional name for the participant.
    ///
    /// Provides the model information to differentiate between
    /// participants of the same role.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
}

/// The contents of a user message: either plain text, or an array of
/// multimodal content parts.
#[derive(Debug, Serialize, Deserialize, Clone)]
#[serde(untagged)]
pub enum MessageContent {
    /// A plain-text message content.
    Text(String),
    /// An array of multimodal content parts (`text`, `image_url`,
    /// `input_audio`, `file`).
    Parts(Vec<ContentPart>),
}

impl From<&str> for MessageContent {
    fn from(value: &str) -> Self {
        Self::Text(value.to_string())
    }
}

impl From<String> for MessageContent {
    fn from(value: String) -> Self {
        Self::Text(value)
    }
}

impl From<Vec<ContentPart>> for MessageContent {
    fn from(value: Vec<ContentPart>) -> Self {
        Self::Parts(value)
    }
}

impl Default for MessageContent {
    fn default() -> Self {
        Self::Text(String::new())
    }
}

/// A content part of a multimodal user message.
#[derive(Debug, Serialize, Deserialize, Clone)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum ContentPart {
    /// Learn about [text inputs](https://platform.openai.com/docs/guides/text).
    Text {
        /// The text content.
        text: String,
        /// Marks the exact end of a reusable prompt prefix. Inherits its TTL
        /// from the request's `prompt_cache_options.ttl`.
        #[serde(skip_serializing_if = "Option::is_none")]
        prompt_cache_breakpoint: Option<PromptCacheBreakpoint>,
    },
    /// Learn about [image inputs](https://platform.openai.com/docs/guides/vision).
    ImageUrl {
        /// Contains either an image URL or a data URL for a base64 encoded image.
        image_url: ContentPartImageUrl,
        /// Marks the exact end of a reusable prompt prefix. Inherits its TTL
        /// from the request's `prompt_cache_options.ttl`.
        #[serde(skip_serializing_if = "Option::is_none")]
        prompt_cache_breakpoint: Option<PromptCacheBreakpoint>,
    },
    /// Learn about [audio inputs](https://platform.openai.com/docs/guides/audio).
    InputAudio {
        /// The audio input data and its format.
        input_audio: ContentPartInputAudio,
        /// Marks the exact end of a reusable prompt prefix. Inherits its TTL
        /// from the request's `prompt_cache_options.ttl`.
        #[serde(skip_serializing_if = "Option::is_none")]
        prompt_cache_breakpoint: Option<PromptCacheBreakpoint>,
    },
    /// Learn about [file inputs](https://platform.openai.com/docs/guides/text).
    File {
        /// The file input: base64 data, an uploaded file ID, or both with a
        /// filename.
        file: ContentPartFile,
        /// Marks the exact end of a reusable prompt prefix. Inherits its TTL
        /// from the request's `prompt_cache_options.ttl`.
        #[serde(skip_serializing_if = "Option::is_none")]
        prompt_cache_breakpoint: Option<PromptCacheBreakpoint>,
    },
}

/// Marks the exact end of a reusable prompt prefix.
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct PromptCacheBreakpoint {
    /// The breakpoint mode. Always `explicit`.
    pub mode: PromptCacheBreakpointMode,
}

/// The breakpoint mode. Always `explicit`.
#[derive(Debug, Serialize, Deserialize, Clone)]
#[serde(rename_all = "lowercase")]
pub enum PromptCacheBreakpointMode {
    Explicit,
}

/// Contains either an image URL or a data URL for a base64 encoded image.
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct ContentPartImageUrl {
    /// Either a URL of the image or the base64 encoded image data.
    pub url: String,
    /// Specifies the detail level of the image.
    /// [Learn more](https://platform.openai.com/docs/guides/vision#low-or-high-fidelity-image-understanding).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub detail: Option<ImageDetail>,
}

/// The detail level of an image input.
#[derive(Debug, Serialize, Deserialize, Clone, Copy)]
#[serde(rename_all = "lowercase")]
pub enum ImageDetail {
    Auto,
    Low,
    High,
}

/// Base64 encoded audio input data.
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct ContentPartInputAudio {
    /// Base64 encoded audio data.
    pub data: String,
    /// The format of the encoded audio data. Currently supports `wav` and
    /// `mp3`.
    pub format: InputAudioFormat,
}

/// The format of the encoded audio data.
#[derive(Debug, Serialize, Deserialize, Clone, Copy)]
#[serde(rename_all = "lowercase")]
pub enum InputAudioFormat {
    Wav,
    Mp3,
}

/// A file input for a content part. At least one of `file_data` and
/// `file_id` should be provided.
#[derive(Debug, Serialize, Deserialize, Clone, Default)]
pub struct ContentPartFile {
    /// The base64 encoded file data, used when passing the file to the model
    /// as a string.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub file_data: Option<String>,
    /// The ID of an uploaded file to use as input.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub file_id: Option<String>,
    /// The name of the file, used when passing the file to the model as a
    /// string.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub filename: Option<String>,
}

/// Configuration for running moderation on the request input and generated
/// output.
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct ChatModerationParam {
    /// The moderation model to use for moderated completions, e.g.
    /// `omni-moderation-latest`.
    pub model: String,
    /// The policy to apply to moderated response input and output.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub policy: Option<ModerationPolicyParam>,
}

/// The policy to apply to moderated response input and output.
#[derive(Debug, Serialize, Deserialize, Clone, Default)]
pub struct ModerationPolicyParam {
    /// The moderation policy for the response input.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub input: Option<ModerationPolicySideParam>,
    /// The moderation policy for the response output.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub output: Option<ModerationPolicySideParam>,
}

/// The moderation policy for one side (input or output) of the response.
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct ModerationPolicySideParam {
    /// `score` returns moderation results; `block` additionally blocks
    /// flagged content.
    pub mode: ModerationPolicyMode,
}

/// The moderation policy mode.
#[derive(Debug, Serialize, Deserialize, Clone, Copy)]
#[serde(rename_all = "lowercase")]
pub enum ModerationPolicyMode {
    Score,
    Block,
}

/// Options for prompt caching.
#[derive(Debug, Serialize, Deserialize, Clone, Default)]
pub struct PromptCacheOptions {
    /// Controls whether OpenAI automatically creates an implicit cache
    /// breakpoint. Defaults to `implicit`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub mode: Option<PromptCacheMode>,
    /// The minimum lifetime applied to every implicit and explicit cache
    /// breakpoint written by the request. Defaults to `30m`, currently the
    /// only supported value.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub ttl: Option<PromptCacheTtl>,
}

/// The prompt cache breakpoint mode.
#[derive(Debug, Serialize, Deserialize, Clone, Copy)]
#[serde(rename_all = "lowercase")]
pub enum PromptCacheMode {
    Implicit,
    Explicit,
}

/// The prompt cache TTL. Currently only `30m` is supported.
#[derive(Debug, Serialize, Deserialize, Clone, Copy)]
pub enum PromptCacheTtl {
    #[serde(rename = "30m")]
    ThirtyMinutes,
}

#[derive(Debug, Serialize, Deserialize, Clone)]
#[serde(tag = "type", rename_all = "lowercase")]
pub enum AssistantToolCall {
    Function {
        /// The ID of the tool call.
        id: String,
        /// The function that the model called.
        function: ToolCallFunction,
    },
    Custom {
        /// The ID of the tool call.
        id: String,
        /// The custom tool that the model called.
        custom: ToolCallCustom,
    },
}

#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct ToolCallFunction {
    /// The arguments to call the function with, as generated by the model in JSON
    /// format. Note that the model does not always generate valid JSON, and may
    /// hallucinate parameters not defined by your function schema. Validate the
    /// arguments in your code before calling your function.
    pub arguments: String,
    /// The name of the function to call.
    pub name: String,
}

#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct ToolCallCustom {
    /// The input for the custom tool call generated by the model.
    pub input: String,
    /// The name of the custom tool to call.
    pub name: String,
}

/// Data about a previous audio response from the model, referenced in an
/// assistant message for multi-turn audio conversations.
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct AssistantAudio {
    /// Unique identifier for a previous audio response in a multi-turn
    /// conversation.
    pub id: String,
    /// The audio data (base64 encoded) to insert as context. Optional.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub data: Option<String>,
}

#[derive(Debug, Serialize, Deserialize, Clone)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum ResponseFormat {
    /// The type of response format being defined. Always `json_schema`.
    JsonSchema {
        /// Structured Outputs configuration options, including a JSON Schema.
        json_schema: JSONSchema,
    },
    /// The type of response format being defined. Always `json_object`.
    JsonObject,
    /// The type of response format being defined. Always `text`.
    Text,
}

#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct JSONSchema {
    /// The name of the response format. Must be a-z, A-Z, 0-9, or contain
    /// underscores and dashes, with a maximum length of 64.
    pub name: String,
    /// A description of what the response format is for, used by the model to determine
    /// how to respond in the format.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
    /// The schema for the response format, described as a JSON Schema object. Learn how
    /// to build JSON schemas [here](https://json-schema.org/).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub schema: Option<serde_json::Map<String, serde_json::Value>>,
    /// Whether to enable strict schema adherence when generating the output. If set to
    /// true, the model will always follow the exact schema defined in the `schema`
    /// field. Only a subset of JSON Schema is supported when `strict` is `true`. To
    /// learn more, read the
    /// [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub strict: Option<bool>,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(rename_all = "snake_case")]
pub enum Modality {
    Text,
    Audio,
}

/// Parameters for audio output of a chat completion.
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct ChatCompletionAudioParam {
    /// Specifies the output audio format. Must be one of `wav`, `aac`, `mp3`,
    /// `flac`, `opus`, or `pcm16`.
    pub format: AudioFormat,
    /// The voice the model uses to respond.
    pub voice: Voice,
}

/// The output audio format of a chat completion.
#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(rename_all = "snake_case")]
pub enum AudioFormat {
    Wav,
    Aac,
    Mp3,
    Flac,
    Opus,
    Pcm16,
}

/// The voice the model uses to respond with audio output.
#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(untagged)]
pub enum Voice {
    /// A built-in voice name, e.g. `alloy`, `ash`, `ballad`, `coral`, `echo`,
    /// `sage`, `shimmer`, or `verse`.
    BuiltIn(String),
    /// A custom voice reference, e.g. `{ "id": "voice_1234" }`.
    Custom {
        /// The custom voice ID, e.g. `voice_1234`.
        id: String,
    },
}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct ChatCompletionPredictionContentParam {
    /// The content that should be matched when generating a model response. If
    /// generated tokens would match this content, the entire model response can be
    /// returned much more quickly.
    pub content: ChatCompletionPredictionContentParamContent,

    /// The type of the predicted content you want to provide.
    /// This type is currently always `content`.
    #[serde(rename = "type")]
    pub type_: ChatCompletionPredictionContentParamType,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(untagged)]
pub enum ChatCompletionPredictionContentParamContent {
    Text(String),
    ChatCompletionContentPartTextParam {
        /// The text content.
        text: String,
        /// The type of the content part.
        #[serde(rename = "type")]
        type_: ChatCompletionContentPartTextParamType,
    },
}

#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(rename_all = "snake_case")]
pub enum ChatCompletionContentPartTextParamType {
    Text,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(rename_all = "snake_case")]
pub enum ChatCompletionPredictionContentParamType {
    Content,
}

/// DeepSeek: skip-serialization helper for the Beta `prefix` message field.
#[cfg(feature = "deepseek")]
#[inline]
fn is_false(value: &bool) -> bool {
    !value
}

#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(untagged)]
pub enum StopKeywords {
    Word(String),
    Words(Vec<String>),
}

#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(rename_all = "snake_case")]
pub enum LowMediumHighEnum {
    Low,
    Medium,
    High,
}

#[derive(Serialize, Deserialize, Debug, Clone, Default)]
pub struct WebSearchOptions {
    /// 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.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub search_context_size: Option<LowMediumHighEnum>,

    #[serde(skip_serializing_if = "Option::is_none")]
    pub user_location: Option<WebSearchOptionsUserLocation>,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum WebSearchOptionsUserLocation {
    /// The type of location approximation. Always `approximate`.
    Approximate {
        /// Approximate location parameters for the search.
        approximate: WebSearchOptionsUserLocationApproximate,
    },
}

#[derive(Serialize, Deserialize, Debug, Clone, Default)]
pub struct WebSearchOptionsUserLocationApproximate {
    /// Free text input for the city of the user, e.g. `San Francisco`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub city: Option<String>,

    /// The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of
    /// the user, e.g. `US`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub country: Option<String>,

    /// Free text input for the region of the user, e.g. `California`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub region: Option<String>,

    /// The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the
    /// user, e.g. `America/Los_Angeles`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub timezone: Option<String>,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct StreamOptions {
    /// If set, an additional chunk will be streamed before the `data: [DONE]` message.
    ///
    /// The `usage` field on this chunk shows the token usage statistics for the entire
    /// request, and the `choices` field will always be an empty array.
    ///
    /// All other chunks will also include a `usage` field, but with a null value.
    /// **NOTE:** If the stream is interrupted, you may not receive the final usage
    /// chunk which contains the total token usage for the request.
    pub include_usage: bool,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum RequestTool {
    /// The type of the tool. Currently, only `function` is supported.
    Function { function: ToolFunction },
    /// The type of the custom tool. Always `custom`.
    Custom {
        /// Properties of the custom tool.
        custom: ToolCustom,
    },
}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct ToolFunction {
    /// 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.
    pub name: String,
    /// A description of what the function does, used by the model to choose when and
    /// how to call the function.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
    /// The parameters the functions accepts, described as a JSON Schema object.
    ///
    /// See the
    /// [openai function calling guide](https://platform.openai.com/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.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub parameters: Option<serde_json::Map<String, serde_json::Value>>,
    /// Whether to enable strict schema adherence when generating the function call.
    ///
    /// If set to true, the model will follow the exact schema defined in the
    /// `parameters` field. Only a subset of JSON Schema is supported when `strict` is
    /// `true`. Learn more about Structured Outputs in the
    /// [openai function calling guide](https://platform.openai.com/docs/guides/function-calling).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub strict: Option<bool>,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct ToolCustom {
    /// The name of the custom tool, used to identify it in tool calls.
    pub name: String,
    /// Optional description of the custom tool, used to provide more context.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
    /// The input format for the custom tool. Default is unconstrained text.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub format: Option<ToolCustomFormat>,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(rename_all = "snake_case", tag = "type")]
pub enum ToolCustomFormat {
    /// Unconstrained text format. Always `text`.
    Text,
    /// Grammar format. Always `grammar`.
    Grammar {
        /// Your chosen grammar.
        grammar: ToolCustomFormatGrammarGrammar,
    },
}

#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct ToolCustomFormatGrammarGrammar {
    /// The grammar definition.
    pub definition: String,
    /// The syntax of the grammar definition. One of `lark` or `regex`.
    pub syntax: ToolCustomFormatGrammarGrammarSyntax,
}

#[derive(Debug, Serialize, Deserialize, Clone)]
#[serde(rename_all = "snake_case")]
pub enum ToolCustomFormatGrammarGrammarSyntax {
    Lark,
    Regex,
}

#[derive(Debug, Serialize, Deserialize, Clone)]
#[serde(rename_all = "snake_case")]
pub enum ToolChoice {
    None,
    Auto,
    Required,
    #[serde(untagged)]
    Specific(ToolChoiceSpecific),
}

#[derive(Debug, Serialize, Deserialize, Clone)]
#[serde(rename_all = "snake_case", tag = "type")]
pub enum ToolChoiceSpecific {
    /// Allowed tool configuration type. Always `allowed_tools`.
    AllowedTools {
        /// Constrains the tools available to the model to a pre-defined set.
        allowed_tools: ToolChoiceAllowedTools,
    },
    /// For function calling, the type is always `function`.
    Function { function: ToolChoiceFunction },
    /// For custom tool calling, the type is always `custom`.
    Custom { custom: ToolChoiceCustom },
}

#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct ToolChoiceAllowedTools {
    /// Constrains the tools available to the model to a pre-defined set.
    ///
    /// - `auto` allows the model to pick from among the allowed tools and generate a
    ///   message.
    /// - `required` requires the model to call one or more of the allowed tools.
    pub mode: ToolChoiceAllowedToolsMode,
    /// A list of tool definitions that the model should be allowed to call.
    ///
    /// For the Chat Completions API, the list of tool definitions might look like:
    ///
    /// ```json
    /// [
    ///   { "type": "function", "function": { "name": "get_weather" } },
    ///   { "type": "function", "function": { "name": "get_time" } }
    /// ]
    /// ```
    pub tools: Vec<serde_json::Map<String, serde_json::Value>>,
}

/// The mode for allowed tools in tool choice.
///
/// Controls how the model should handle the set of allowed tools:
///
/// - `auto` allows the model to pick from among the allowed tools and generate a
///   message.
/// - `required` requires the model to call one or more of the allowed tools.
#[derive(Debug, Serialize, Deserialize, Clone)]
#[serde(rename_all = "lowercase")]
pub enum ToolChoiceAllowedToolsMode {
    /// The model can choose whether to use the allowed tools or not.
    Auto,
    /// The model must use at least one of the allowed tools.
    Required,
}

#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct ToolChoiceFunction {
    /// The name of the function to call.
    pub name: String,
}

#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct ToolChoiceCustom {
    /// The name of the custom tool to call.
    pub name: String,
}

/// DeepSeek: controls the switch between thinking and non-thinking mode.
#[cfg(feature = "deepseek")]
#[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq)]
pub struct DeepSeekThinking {
    /// Whether to use thinking mode (`enabled`) or non-thinking mode
    /// (`disabled`). Defaults to `enabled`.
    #[serde(rename = "type")]
    pub type_: DeepSeekThinkingType,
}

/// DeepSeek: whether thinking mode is enabled or disabled.
#[cfg(feature = "deepseek")]
#[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum DeepSeekThinkingType {
    Enabled,
    Disabled,
}

/// Constrains the effort on reasoning for reasoning models. This is an
/// official OpenAI parameter; reasoning providers such as DeepSeek and Qwen
/// accept a subset of these values and map the rest to their nearest effort
/// level.
#[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum ReasoningEffort {
    None,
    Minimal,
    Low,
    Medium,
    High,
    Xhigh,
    Max,
}

impl RequestBody {
    /// Whether this request asks for a streamed response. Defaults to
    /// `false` when [`RequestBody::stream`] is `None`.
    pub fn is_streaming(&self) -> bool {
        self.stream.unwrap_or(false)
    }
}

impl Post for RequestBody {
    fn is_streaming(&self) -> bool {
        RequestBody::is_streaming(self)
    }

    /// Builds the URL for the request.
    ///
    /// `base_url` should be like <https://api.openai.com/v1>
    fn build_url(&self, base_url: &str) -> Result<String, OapiError> {
        let mut url = Url::parse(base_url.trim_end_matches('/')).map_err(OapiError::UrlError)?;
        url.path_segments_mut()
            .map_err(|_| OapiError::UrlCannotBeBase(base_url.to_string()))?
            .push("chat")
            .push("completions");

        Ok(url.to_string())
    }
}

impl PostNoStream for RequestBody {
    type Response = super::response::no_streaming::ChatCompletion;
}

impl PostStream for RequestBody {
    type Response = super::response::streaming::ChatCompletionChunk;
}

#[cfg(test)]
mod request_test {
    use futures_util::StreamExt;

    use super::*;

    const DEEPSEEK_CHAT_URL: &str = "https://api.deepseek.com";
    const DEEPSEEK_MODEL: &str = "deepseek-v4-flash";

    fn deepseek_api_key() -> Option<String> {
        std::env::var("DEEPSEEK_API_KEY")
            .ok()
            .map(|key| key.trim().to_string())
            .filter(|key| !key.is_empty())
    }

    #[tokio::test]
    async fn test_deepseek_no_stream() {
        let Some(api_key) = deepseek_api_key() else {
            println!("Skipping: set DEEPSEEK_API_KEY to run this test");
            return;
        };

        let request = RequestBody {
            messages: vec![
                Message::system("This is a request of test purpose. Reply briefly"),
                Message::user("What's your name?"),
            ],
            model: DEEPSEEK_MODEL.to_string(),
            stream: Some(false),
            ..Default::default()
        };

        let response = request
            .get_response_string(
                &crate::rest::default_client(),
                DEEPSEEK_CHAT_URL,
                &crate::rest::RequestOptions::bearer(&api_key),
            )
            .await
            .unwrap();

        println!("{}", response);

        assert!(response.to_ascii_lowercase().contains("deepseek"));
    }

    #[tokio::test]
    async fn test_deepseek_stream() {
        let Some(api_key) = deepseek_api_key() else {
            println!("Skipping: set DEEPSEEK_API_KEY to run this test");
            return;
        };

        let request = RequestBody {
            messages: vec![
                Message::system("This is a request of test purpose. Reply briefly"),
                Message::user("Who are you?"),
            ],
            model: DEEPSEEK_MODEL.to_string(),
            stream: Some(true),
            ..Default::default()
        };

        let mut response = request
            .get_stream_response_string(
                &crate::rest::default_client(),
                DEEPSEEK_CHAT_URL,
                &crate::rest::RequestOptions::bearer(&api_key),
            )
            .await
            .unwrap();

        while let Some(chunk) = response.next().await {
            println!("{}", chunk.unwrap());
        }
    }

    /// Assistant tool calls serialize with the official `type` tag
    /// (`{"type":"function",...}` / `{"type":"custom",...}`), not `role`.
    #[test]
    fn assistant_tool_call_serialization() {
        let function_call = AssistantToolCall::Function {
            id: "call_abc".to_string(),
            function: ToolCallFunction {
                arguments: "{\"city\":\"paris\"}".to_string(),
                name: "get_weather".to_string(),
            },
        };
        let json = serde_json::to_string(&function_call).unwrap();
        assert!(json.contains(r#""type":"function""#), "json: {json}");
        assert!(!json.contains(r#""role""#), "json: {json}");

        let custom_call = AssistantToolCall::Custom {
            id: "call_def".to_string(),
            custom: ToolCallCustom {
                input: "2+2".to_string(),
                name: "calculator".to_string(),
            },
        };
        let json = serde_json::to_string(&custom_call).unwrap();
        assert!(json.contains(r#""type":"custom""#), "json: {json}");
        assert!(!json.contains(r#""role""#), "json: {json}");
    }

    /// The `prediction` parameter sends its discriminator as `type`, not
    /// as the Rust field name `type_`.
    #[test]
    fn prediction_type_serialization() {
        let prediction = ChatCompletionPredictionContentParam {
            content: ChatCompletionPredictionContentParamContent::Text(
                "The capital of France is Paris.".to_string(),
            ),
            type_: ChatCompletionPredictionContentParamType::Content,
        };
        let json = serde_json::to_string(&prediction).unwrap();
        assert!(json.contains(r#""type":"content""#), "json: {json}");
        assert!(!json.contains("type_"), "json: {json}");
    }

    /// `tool_choice: allowed_tools` sends `tools` as a JSON array of tool
    /// definitions, matching the official `Iterable[Dict[str, object]]`.
    #[test]
    fn allowed_tools_choice_serialization() {
        let mut weather = serde_json::Map::new();
        weather.insert("type".to_string(), serde_json::json!("function"));
        weather.insert(
            "function".to_string(),
            serde_json::json!({ "name": "get_weather" }),
        );

        let choice = ToolChoiceSpecific::AllowedTools {
            allowed_tools: ToolChoiceAllowedTools {
                mode: ToolChoiceAllowedToolsMode::Required,
                tools: vec![weather],
            },
        };
        let json = serde_json::to_string(&choice).unwrap();
        assert!(json.contains(r#""type":"allowed_tools""#), "json: {json}");
        assert!(json.contains(r#""mode":"required""#), "json: {json}");
        // `tools` must serialize as an array, not an object.
        assert!(json.contains(r#""tools":[{"#), "json: {json}");
    }

    /// `web_search_options` sends `search_context_size` as optional and the
    /// user location nested under an `approximate` key.
    #[test]
    fn web_search_options_serialization() {
        let options = WebSearchOptions {
            search_context_size: None,
            user_location: Some(WebSearchOptionsUserLocation::Approximate {
                approximate: WebSearchOptionsUserLocationApproximate {
                    city: Some("San Francisco".to_string()),
                    country: None,
                    region: None,
                    timezone: None,
                },
            }),
        };
        let json = serde_json::to_string(&options).unwrap();
        assert!(!json.contains("search_context_size"), "json: {json}");
        assert!(json.contains(r#""type":"approximate""#), "json: {json}");
        assert!(
            json.contains(r#""approximate":{"city":"San Francisco"}"#),
            "json: {json}"
        );
    }

    /// `JSONSchema`/`ToolFunction` optional fields are omitted when unset.
    #[test]
    fn json_schema_optional_fields_serialization() {
        let schema = JSONSchema {
            name: "Answer".to_string(),
            description: None,
            schema: None,
            strict: None,
        };
        let json = serde_json::to_string(&schema).unwrap();
        assert_eq!(json, r#"{"name":"Answer"}"#);

        let function = ToolFunction {
            name: "get_weather".to_string(),
            description: None,
            parameters: None,
            strict: None,
        };
        let json = serde_json::to_string(&function).unwrap();
        assert_eq!(json, r#"{"name":"get_weather"}"#);
    }

    /// Plain-text user messages keep the official wire format: `content`
    /// is a JSON string, not a parts array.
    #[test]
    fn user_text_content_serialization() {
        let request = RequestBody {
            messages: vec![Message::user("Hi")],
            model: "gpt-4o".to_string(),
            ..Default::default()
        };

        let json = serde_json::to_string(&request).unwrap();
        assert!(json.contains(r#""content":"Hi""#), "json: {json}");
    }

    /// Messages deserialize from client JSON through the payload structs
    /// (request-side parity for proxies and servers).
    #[test]
    fn message_deserialization() {
        let system: Message =
            serde_json::from_str(r#"{"role":"system","content":"Be terse"}"#).unwrap();
        assert!(matches!(
            system,
            Message::System(SystemMessage {
                content: MessageContent::Text(_),
                name: None
            })
        ));

        let user: Message =
            serde_json::from_str(r#"{"role":"user","content":"Hi","name":"jimmy"}"#).unwrap();
        let Message::User(user) = user else {
            panic!("must be a user message");
        };
        assert_eq!(user.name.as_deref(), Some("jimmy"));

        let assistant: Message = serde_json::from_str(
            r#"{"role":"assistant","content":null,"tool_calls":[{"type":"function","id":"call_1","function":{"name":"f","arguments":"{}"}}]}"#,
        )
        .unwrap();
        let Message::Assistant(assistant) = assistant else {
            panic!("must be an assistant message");
        };
        assert_eq!(assistant.content, None);
        assert_eq!(assistant.tool_calls.expect("tool calls").len(), 1);

        let tool: Message =
            serde_json::from_str(r#"{"role":"tool","content":"42","tool_call_id":"call_1"}"#)
                .unwrap();
        let Message::Tool(tool) = tool else {
            panic!("must be a tool message");
        };
        assert_eq!(tool.tool_call_id, "call_1");

        let developer: Message =
            serde_json::from_str(r#"{"role":"developer","content":"New rules"}"#).unwrap();
        assert!(matches!(developer, Message::Developer(_)));

        let function: Message =
            serde_json::from_str(r#"{"role":"function","name":"f","content":"ok"}"#).unwrap();
        assert!(matches!(function, Message::Function(_)));
    }

    /// An unknown role is a hard error: such a message cannot be forwarded
    /// to any backend, so it must not be silently mapped onto a catch-all.
    #[test]
    fn unknown_role_fails_deserialization() {
        let result = serde_json::from_str::<Message>(r#"{"role":"weird","content":"x"}"#);
        assert!(result.is_err(), "unknown roles must be rejected");
    }

    /// A full request body deserializes back from client JSON; unknown
    /// top-level fields are captured into `extra_body_map` and survive
    /// re-serialization, so proxying is lossless.
    #[test]
    fn request_body_deserializes_with_extra_fields() {
        let json = r#"{
            "model": "qwen-plus",
            "messages": [{"role": "user", "content": "Hi"}],
            "stream": true,
            "vendor_extension": {"depth": 3}
        }"#;
        let request = serde_json::from_str::<RequestBody>(json).unwrap();
        assert_eq!(request.model, "qwen-plus");
        assert_eq!(request.stream, Some(true));
        assert_eq!(request.messages.len(), 1);

        let extra = request
            .extra_body_map
            .as_ref()
            .expect("extra fields captured");
        assert_eq!(
            extra.get("vendor_extension"),
            Some(&serde_json::json!({"depth": 3}))
        );

        let serialized = serde_json::to_value(&request).unwrap();
        assert_eq!(serialized["vendor_extension"]["depth"], 3);
    }

    /// The convenience constructors produce the official wire shapes.
    #[test]
    fn message_constructors() {
        let request = RequestBody {
            messages: vec![
                Message::system("Be terse"),
                Message::user("Hi"),
                Message::assistant("Hello!"),
                Message::tool(r#"{"temp":21}"#, "call_1"),
            ],
            model: "gpt-4o".to_string(),
            ..Default::default()
        };

        let json = serde_json::to_string(&request).unwrap();
        assert!(json.contains(r#""role":"system","content":"Be terse""#),);
        assert!(json.contains(r#""role":"user","content":"Hi""#));
        assert!(json.contains(r#""role":"assistant","content":"Hello!""#));
        assert!(
            json.contains(r#""role":"tool","content":"{\"temp\":21}","tool_call_id":"call_1""#)
        );
    }

    /// System, developer and tool messages serialize `content` as a plain
    /// string by default and as a text-part array when parts are supplied
    /// (the official "string or array of content parts" shapes).
    #[test]
    fn system_developer_tool_content_serialization() {
        let request = RequestBody {
            messages: vec![
                Message::system("Be terse"),
                Message::developer(MessageContent::Parts(vec![ContentPart::Text {
                    text: "Prefer Rust".to_string(),
                    prompt_cache_breakpoint: None,
                }])),
                Message::tool(
                    MessageContent::Parts(vec![ContentPart::Text {
                        text: r#"{"temp": 21}"#.to_string(),
                        prompt_cache_breakpoint: None,
                    }]),
                    "call_1",
                ),
            ],
            model: "gpt-4o".to_string(),
            ..Default::default()
        };

        let json = serde_json::to_string(&request).unwrap();
        assert!(
            json.contains(r#""role":"system","content":"Be terse""#),
            "json: {json}"
        );
        assert!(
            json.contains(r#""role":"developer","content":[{"type":"text","text":"Prefer Rust"}]"#),
            "json: {json}"
        );
        assert!(
            json.contains(
                r#""role":"tool","content":[{"type":"text","text":"{\"temp\": 21}"}],"tool_call_id":"call_1""#
            ),
            "json: {json}"
        );
    }

    /// Multimodal user messages serialize as content-part arrays with the
    /// official shapes, including `prompt_cache_breakpoint`.
    #[test]
    fn multimodal_content_serialization() {
        let request = RequestBody {
            messages: vec![Message::user(MessageContent::Parts(vec![
                ContentPart::ImageUrl {
                    image_url: ContentPartImageUrl {
                        url: "https://example.com/cat.png".to_string(),
                        detail: Some(ImageDetail::High),
                    },
                    prompt_cache_breakpoint: None,
                },
                ContentPart::Text {
                    text: "What's in this image?".to_string(),
                    prompt_cache_breakpoint: Some(PromptCacheBreakpoint {
                        mode: PromptCacheBreakpointMode::Explicit,
                    }),
                },
            ]))],
            model: "gpt-4o".to_string(),
            ..Default::default()
        };

        let json = serde_json::to_string(&request).unwrap();
        assert!(json.contains(r#""type":"image_url""#), "json: {json}");
        assert!(
            json.contains(r#""url":"https://example.com/cat.png""#),
            "json: {json}"
        );
        assert!(json.contains(r#""detail":"high""#), "json: {json}");
        assert!(json.contains(r#""type":"text""#), "json: {json}");
        assert!(
            json.contains(r#""prompt_cache_breakpoint":{"mode":"explicit"}"#),
            "json: {json}"
        );
    }

    /// `input_audio` and `file` content parts serialize with the official
    /// shapes.
    #[test]
    fn audio_and_file_content_serialization() {
        let content = MessageContent::Parts(vec![
            ContentPart::InputAudio {
                input_audio: ContentPartInputAudio {
                    data: "aGVsbG8=".to_string(),
                    format: InputAudioFormat::Wav,
                },
                prompt_cache_breakpoint: None,
            },
            ContentPart::File {
                file: ContentPartFile {
                    file_id: Some("file-abc".to_string()),
                    ..Default::default()
                },
                prompt_cache_breakpoint: None,
            },
        ]);

        let json = serde_json::to_string(&content).unwrap();
        assert!(json.contains(r#""type":"input_audio""#), "json: {json}");
        assert!(json.contains(r#""data":"aGVsbG8=""#), "json: {json}");
        assert!(json.contains(r#""format":"wav""#), "json: {json}");
        assert!(json.contains(r#""type":"file""#), "json: {json}");
        assert!(
            json.contains(r#""file":{"file_id":"file-abc"}"#),
            "json: {json}"
        );
        // Optional file fields are omitted when unset.
        assert!(!json.contains("file_data"), "json: {json}");
    }

    /// `logit_bias`, `moderation` and `prompt_cache_options` serialize as
    /// the official request parameters (token-id keys as JSON strings).
    #[test]
    fn new_params_serialization() {
        let mut logit_bias = HashMap::new();
        logit_bias.insert(40u32, -100i32);

        let request = RequestBody {
            messages: vec![Message::user("Hi")],
            model: "gpt-5".to_string(),
            logit_bias: Some(logit_bias),
            moderation: Some(ChatModerationParam {
                model: "omni-moderation-latest".to_string(),
                policy: Some(ModerationPolicyParam {
                    input: Some(ModerationPolicySideParam {
                        mode: ModerationPolicyMode::Block,
                    }),
                    output: None,
                }),
            }),
            prompt_cache_options: Some(PromptCacheOptions {
                mode: Some(PromptCacheMode::Explicit),
                ttl: Some(PromptCacheTtl::ThirtyMinutes),
            }),
            ..Default::default()
        };

        let json = serde_json::to_string(&request).unwrap();
        assert!(json.contains(r#""logit_bias":{"40":-100}"#), "json: {json}");
        assert!(
            json.contains(
                r#""moderation":{"model":"omni-moderation-latest","policy":{"input":{"mode":"block"}}}"#
            ),
            "json: {json}"
        );
        assert!(
            json.contains(r#""prompt_cache_options":{"mode":"explicit","ttl":"30m"}"#),
            "json: {json}"
        );
    }

    /// Serializes the OpenAI `reasoning_effort` parameter.
    #[test]
    fn reasoning_effort_serialization() {
        let request = RequestBody {
            messages: vec![Message::user("What's your name?")],
            model: "gpt-5".to_string(),
            reasoning_effort: Some(ReasoningEffort::Xhigh),
            ..Default::default()
        };

        let json = serde_json::to_string(&request).unwrap();
        assert!(
            json.contains(r#""reasoning_effort":"xhigh""#),
            "json: {json}"
        );
    }

    /// Serializes the DeepSeek Beta chat prefix completion fields.
    #[cfg(feature = "deepseek")]
    #[test]
    fn deepseek_assistant_prefix_serialization() {
        let request = RequestBody {
            messages: vec![
                Message::user("Please write quick sort code"),
                Message::Assistant(AssistantMessage {
                    content: Some("```python\n".to_string()),
                    prefix: true,
                    ..Default::default()
                }),
            ],
            model: DEEPSEEK_MODEL.to_string(),
            ..Default::default()
        };

        let json = serde_json::to_string(&request).unwrap();
        assert!(json.contains(r#""prefix":true"#), "json: {json}");
    }

    /// Serializes the DeepSeek `thinking`, `reasoning_effort` and `user_id`
    /// request parameters.
    #[cfg(feature = "deepseek")]
    #[test]
    fn deepseek_thinking_params_serialization() {
        let request = RequestBody {
            messages: vec![Message::user("What's your name?")],
            model: DEEPSEEK_MODEL.to_string(),
            thinking: Some(DeepSeekThinking {
                type_: DeepSeekThinkingType::Disabled,
            }),
            user_id: Some("user-123".to_string()),
            ..Default::default()
        };

        let json = serde_json::to_string(&request).unwrap();
        assert!(
            json.contains(r#""thinking":{"type":"disabled"}"#),
            "json: {json}"
        );
        assert!(json.contains(r#""user_id":"user-123""#), "json: {json}");
    }

    /// Serializes the Qwen `enable_thinking`, `thinking_budget` and `top_k`
    /// request parameters.
    #[cfg(feature = "qwen")]
    #[test]
    fn qwen_params_serialization() {
        let request = RequestBody {
            messages: vec![Message::user("What's your name?")],
            model: "qwen-plus".to_string(),
            enable_thinking: Some(false),
            thinking_budget: Some(1024),
            top_k: Some(20),
            ..Default::default()
        };

        let json = serde_json::to_string(&request).unwrap();
        assert!(json.contains(r#""enable_thinking":false"#), "json: {json}");
        assert!(json.contains(r#""thinking_budget":1024"#), "json: {json}");
        assert!(json.contains(r#""top_k":20"#), "json: {json}");
    }

    const QWEN_CHAT_URL: &str = "https://dashscope.aliyuncs.com/compatible-mode/v1";
    /// Qwen's multimodal flash model: accepts text, image and audio inputs
    /// through its OpenAI-compatible endpoint.
    const QWEN_MULTIMODAL_MODEL: &str = "qwen3.8-flash";

    fn qwen_api_key() -> Option<String> {
        std::env::var("QWEN_API_KEY")
            .ok()
            .map(|key| key.trim().to_string())
            .filter(|key| !key.is_empty())
    }

    /// Real request: a user message with an `image_url` content part. The
    /// image is the football sample used in Alibaba Cloud Model Studio's own
    /// documentation. Requires `QWEN_API_KEY`; skipped otherwise.
    #[tokio::test]
    async fn test_qwen_image_input() -> Result<(), anyhow::Error> {
        let Some(api_key) = qwen_api_key() else {
            println!("Skipping: set QWEN_API_KEY to run this test");
            return Ok(());
        };

        let request = RequestBody {
            messages: vec![
                Message::system("This is a request of test purpose. Reply briefly"),
                Message::user(MessageContent::Parts(vec![
                    ContentPart::ImageUrl {
                        image_url: ContentPartImageUrl {
                            url: "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/xzsgiz/football1.jpg"
                                .to_string(),
                            detail: None,
                        },
                        prompt_cache_breakpoint: None,
                    },
                    ContentPart::Text {
                        text: "What is shown in this image? Answer with one short sentence."
                            .to_string(),
                        prompt_cache_breakpoint: None,
                    },
                ])),
            ],
            model: QWEN_MULTIMODAL_MODEL.to_string(),
            ..Default::default()
        };

        let response = request
            .get_response(
                &crate::rest::default_client(),
                QWEN_CHAT_URL,
                &crate::rest::RequestOptions::bearer(&api_key),
            )
            .await?;

        let content = response.choices[0]
            .message
            .content
            .clone()
            .unwrap_or_default();
        println!("image response: {content}");
        assert!(
            !content.trim().is_empty(),
            "empty content for a valid image request"
        );
        Ok(())
    }

    /// Real request: a user message with an `input_audio` content part
    /// carrying a public audio URL (the cherry sample from the Model Studio
    /// docs), answered by the streaming response. Requires `QWEN_API_KEY`;
    /// skipped otherwise.
    ///
    /// Uses `qwen-omni-turbo`: Qwen's Omni models are the multimodal class
    /// that accepts audio input on the OpenAI-compatible endpoint, and they
    /// require `stream: true`. (`qwen3.8-flash` rejects `input_audio` with a
    /// provider-side `400 incorrect modal 'audio'` error, verified with
    /// plain curl.)
    #[tokio::test]
    async fn test_qwen_audio_input() -> Result<(), anyhow::Error> {
        let Some(api_key) = qwen_api_key() else {
            println!("Skipping: set QWEN_API_KEY to run this test");
            return Ok(());
        };

        let request = RequestBody {
            messages: vec![Message::user(MessageContent::Parts(vec![
                ContentPart::InputAudio {
                    input_audio: ContentPartInputAudio {
                        data: "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250211/tixcef/cherry.wav"
                            .to_string(),
                        format: InputAudioFormat::Wav,
                    },
                    prompt_cache_breakpoint: None,
                },
                ContentPart::Text {
                    text: "What does the speaker say in this audio? Reply briefly."
                        .to_string(),
                    prompt_cache_breakpoint: None,
                },
            ]))],
            model: "qwen-omni-turbo".to_string(),
            stream: Some(true),
            modalities: Some(vec![Modality::Text]),
            ..Default::default()
        };

        let mut stream = request
            .get_stream_response(
                &crate::rest::default_client(),
                QWEN_CHAT_URL,
                &crate::rest::RequestOptions::bearer(&api_key),
            )
            .await?;

        let mut message = String::new();
        while let Some(chunk) = stream.next().await {
            let chunk = chunk?;
            if let Some(choice) = chunk.choices.first()
                && let Some(content) = choice.delta.content.as_deref()
            {
                message.push_str(content);
            }
        }

        println!("audio response: {message}");
        assert!(
            !message.trim().is_empty(),
            "empty content for a valid audio request"
        );
        Ok(())
    }

    /// Real request: a plain-text user message (the wire format of
    /// [`MessageContent::Text`]). Requires `QWEN_API_KEY`; skipped otherwise.
    #[tokio::test]
    async fn test_qwen_text_input() -> Result<(), anyhow::Error> {
        let Some(api_key) = qwen_api_key() else {
            println!("Skipping: set QWEN_API_KEY to run this test");
            return Ok(());
        };

        let request = RequestBody {
            messages: vec![Message::user("Reply with exactly one word.")],
            model: QWEN_MULTIMODAL_MODEL.to_string(),
            ..Default::default()
        };

        let response = request
            .get_response(
                &crate::rest::default_client(),
                QWEN_CHAT_URL,
                &crate::rest::RequestOptions::bearer(&api_key),
            )
            .await?;

        let content = response.choices[0]
            .message
            .content
            .clone()
            .unwrap_or_default();
        println!("text response: {content}");
        assert!(!content.trim().is_empty(), "empty content for text input");
        Ok(())
    }

    /// Real request: streaming a multimodal (image + text) user message.
    /// Requires `QWEN_API_KEY`; skipped otherwise.
    #[tokio::test]
    async fn test_qwen_multimodal_stream() -> Result<(), anyhow::Error> {
        let Some(api_key) = qwen_api_key() else {
            println!("Skipping: set QWEN_API_KEY to run this test");
            return Ok(());
        };

        let request = RequestBody {
            messages: vec![Message::user(MessageContent::Parts(vec![
                ContentPart::ImageUrl {
                    image_url: ContentPartImageUrl {
                        url: "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/xzsgiz/football1.jpg"
                            .to_string(),
                        detail: None,
                    },
                    prompt_cache_breakpoint: None,
                },
                ContentPart::Text {
                    text: "What is shown in this image? Answer with one short sentence."
                        .to_string(),
                    prompt_cache_breakpoint: None,
                },
            ]))],
            model: QWEN_MULTIMODAL_MODEL.to_string(),
            stream: Some(true),
            ..Default::default()
        };

        let mut stream = request
            .get_stream_response(
                &crate::rest::default_client(),
                QWEN_CHAT_URL,
                &crate::rest::RequestOptions::bearer(&api_key),
            )
            .await?;

        let mut message = String::new();
        while let Some(chunk) = stream.next().await {
            let chunk = chunk?;
            if let Some(choice) = chunk.choices.first()
                && let Some(content) = choice.delta.content.as_deref()
            {
                message.push_str(content);
            }
        }

        println!("streamed message: {message}");
        assert!(
            !message.trim().is_empty(),
            "empty streamed content for a valid image request"
        );
        Ok(())
    }
}