linger-openai-sdk 0.1.1

use crate::error::LingerError;
use crate::transport::{BodyStream, HttpRequest};
use crate::RequestId;
use bytes::Bytes;
use serde::{Deserialize, Serialize};
use serde_json::Value;
use std::collections::BTreeMap;

/// EN: Request body for `POST /v1/audio/speech`.
/// 中文：`POST /v1/audio/speech` 的请求体。
#[derive(Clone, Debug, Serialize, PartialEq)]
#[non_exhaustive]
pub struct CreateSpeechRequest {
    /// EN: Text-to-speech model id.
    /// 中文：文本转语音模型 ID。
    pub model: String,
    /// EN: Text input to synthesize.
    /// 中文：要合成的文本输入。
    pub input: String,
    /// EN: Voice used for synthesized audio.
    /// 中文：合成音频使用的声音。
    pub voice: String,
    /// EN: Optional audio response format.
    /// 中文：可选的音频响应格式。
    #[serde(skip_serializing_if = "Option::is_none")]
    pub response_format: Option<String>,
    /// EN: Optional playback speed.
    /// 中文：可选的播放速度。
    #[serde(skip_serializing_if = "Option::is_none")]
    pub speed: Option<f32>,
    /// EN: Optional model instructions.
    /// 中文：可选的模型指令。
    #[serde(skip_serializing_if = "Option::is_none")]
    pub instructions: Option<String>,
    /// EN: Optional audio stream response format.
    /// 中文：可选的音频流响应格式。
    #[serde(skip_serializing_if = "Option::is_none")]
    pub stream_format: Option<String>,
    /// EN: Forward-compatible optional fields not yet covered by handwritten types.
    /// 中文：手写类型尚未覆盖的前向兼容可选字段。
    #[serde(flatten)]
    pub extra: BTreeMap<String, Value>,
}

impl CreateSpeechRequest {
    /// EN: Starts building a speech request.
    /// 中文：开始构建语音请求。
    pub fn builder() -> CreateSpeechRequestBuilder {
        CreateSpeechRequestBuilder::default()
    }
}

/// EN: Builder for speech requests.
/// 中文：语音请求的构建器。
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
pub struct CreateSpeechRequestBuilder {
    model: Option<String>,
    input: Option<String>,
    voice: Option<String>,
    response_format: Option<String>,
    speed: Option<f32>,
    instructions: Option<String>,
    stream_format: Option<String>,
    extra: BTreeMap<String, Value>,
}

impl CreateSpeechRequestBuilder {
    /// EN: Sets the speech model id.
    /// 中文：设置语音模型 ID。
    pub fn model(mut self, model: impl Into<String>) -> Self {
        self.model = Some(model.into());
        self
    }

    /// EN: Sets text input to synthesize.
    /// 中文：设置要合成的文本输入。
    pub fn input(mut self, input: impl Into<String>) -> Self {
        self.input = Some(input.into());
        self
    }

    /// EN: Sets the voice.
    /// 中文：设置声音。
    pub fn voice(mut self, voice: impl Into<String>) -> Self {
        self.voice = Some(voice.into());
        self
    }

    /// EN: Sets the optional audio response format.
    /// 中文：设置可选的音频响应格式。
    pub fn response_format(mut self, response_format: impl Into<String>) -> Self {
        self.response_format = Some(response_format.into());
        self
    }

    /// EN: Sets the optional playback speed.
    /// 中文：设置可选的播放速度。
    pub fn speed(mut self, speed: f32) -> Self {
        self.speed = Some(speed);
        self
    }

    /// EN: Sets optional model instructions.
    /// 中文：设置可选的模型指令。
    pub fn instructions(mut self, instructions: impl Into<String>) -> Self {
        self.instructions = Some(instructions.into());
        self
    }

    /// EN: Sets the optional audio stream response format, such as `audio` or `sse`.
    /// 中文：设置可选的音频流响应格式，例如 `audio` 或 `sse`。
    pub fn stream_format(mut self, stream_format: impl Into<String>) -> Self {
        self.stream_format = Some(stream_format.into());
        self
    }

    /// EN: Adds a forward-compatible JSON field.
    /// 中文：添加前向兼容的 JSON 字段。
    pub fn extra(mut self, name: impl Into<String>, value: Value) -> Self {
        self.extra.insert(name.into(), value);
        self
    }

    /// EN: Builds and validates the request.
    /// 中文：构建并校验请求。
    pub fn build(self) -> Result<CreateSpeechRequest, LingerError> {
        let model = required_string("model", self.model)?;
        let input = required_string("input", self.input)?;
        let voice = required_string("voice", self.voice)?;
        validate_max_chars("input", &input, 4096)?;
        validate_optional_string("response_format", self.response_format.as_deref())?;
        validate_optional_string("instructions", self.instructions.as_deref())?;
        if let Some(instructions) = self.instructions.as_deref() {
            validate_max_chars("instructions", instructions, 4096)?;
        }
        validate_optional_string("stream_format", self.stream_format.as_deref())?;
        if self
            .speed
            .is_some_and(|speed| !(0.25..=4.0).contains(&speed))
        {
            return Err(LingerError::invalid_config(
                "speed must be between 0.25 and 4.0",
            ));
        }
        Ok(CreateSpeechRequest {
            model,
            input,
            voice,
            response_format: self.response_format,
            speed: self.speed,
            instructions: self.instructions,
            stream_format: self.stream_format,
            extra: self.extra,
        })
    }
}

/// EN: Streaming speech audio response.
/// 中文：流式语音音频响应。
pub struct AudioSpeechResponse {
    request_id: Option<RequestId>,
    content_type: Option<String>,
    body: BodyStream,
}

impl AudioSpeechResponse {
    pub(crate) fn new(
        request_id: Option<RequestId>,
        content_type: Option<String>,
        body: BodyStream,
    ) -> Self {
        Self {
            request_id,
            content_type,
            body,
        }
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }

    /// EN: Returns the response content type, when present.
    /// 中文：返回响应内容类型，如存在。
    pub fn content_type(&self) -> Option<&str> {
        self.content_type.as_deref()
    }

    /// EN: Consumes this response and returns the incremental audio stream.
    /// 中文：消耗此响应并返回增量音频流。
    pub fn into_stream(self) -> BodyStream {
        self.body
    }
}

/// EN: Uploadable audio file bytes and multipart metadata.
/// 中文：可上传音频文件字节及 multipart 元数据。
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub struct AudioUpload {
    /// EN: Filename sent in the multipart part.
    /// 中文：multipart 分段中发送的文件名。
    pub filename: String,
    /// EN: Content type sent for the audio part.
    /// 中文：音频分段发送的内容类型。
    pub content_type: String,
    content: Bytes,
}

impl AudioUpload {
    /// EN: Creates an upload from already available bytes without copying them.
    /// 中文：通过已可用字节创建上传对象，不复制这些字节。
    pub fn from_bytes(
        filename: impl Into<String>,
        content: impl Into<Bytes>,
    ) -> Result<Self, LingerError> {
        let filename = filename.into();
        validate_header_param("filename", &filename)?;
        Ok(Self {
            filename,
            content_type: "application/octet-stream".to_string(),
            content: content.into(),
        })
    }

    /// EN: Sets the audio part content type.
    /// 中文：设置音频分段的内容类型。
    pub fn content_type(mut self, content_type: impl Into<String>) -> Result<Self, LingerError> {
        let content_type = content_type.into();
        validate_header_value("content_type", &content_type)?;
        self.content_type = content_type;
        Ok(self)
    }
}

/// EN: Request body descriptor for `POST /v1/audio/voice_consents`.
/// 中文：`POST /v1/audio/voice_consents` 的请求体描述。
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub struct CreateVoiceConsentRequest {
    /// EN: Label for the consent recording.
    /// 中文：consent 录音标签。
    pub name: String,
    /// EN: BCP 47 language tag for the consent phrase.
    /// 中文：consent 短语的 BCP 47 语言标签。
    pub language: String,
    /// EN: Consent recording audio file.
    /// 中文：consent 录音音频文件。
    pub recording: AudioUpload,
}

impl CreateVoiceConsentRequest {
    /// EN: Starts building a voice-consent request.
    /// 中文：开始构建 voice consent 请求。
    pub fn builder() -> CreateVoiceConsentRequestBuilder {
        CreateVoiceConsentRequestBuilder::default()
    }

    pub(crate) fn apply_multipart_body(&self, request: &mut HttpRequest) {
        let fields = vec![
            ("name".to_string(), self.name.clone()),
            ("language".to_string(), self.language.clone()),
        ];
        apply_audio_multipart(request, "recording", &self.recording, fields);
    }
}

/// EN: Builder for voice-consent requests.
/// 中文：voice consent 请求的构建器。
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
pub struct CreateVoiceConsentRequestBuilder {
    name: Option<String>,
    language: Option<String>,
    recording: Option<AudioUpload>,
}

impl CreateVoiceConsentRequestBuilder {
    /// EN: Sets the consent recording label.
    /// 中文：设置 consent 录音标签。
    pub fn name(mut self, name: impl Into<String>) -> Self {
        self.name = Some(name.into());
        self
    }

    /// EN: Sets the consent phrase language.
    /// 中文：设置 consent 短语语言。
    pub fn language(mut self, language: impl Into<String>) -> Self {
        self.language = Some(language.into());
        self
    }

    /// EN: Sets the consent recording file.
    /// 中文：设置 consent 录音文件。
    pub fn recording(mut self, recording: AudioUpload) -> Self {
        self.recording = Some(recording);
        self
    }

    /// EN: Builds and validates the request.
    /// 中文：构建并校验请求。
    pub fn build(self) -> Result<CreateVoiceConsentRequest, LingerError> {
        let name = required_string("name", self.name)?;
        let language = required_string("language", self.language)?;
        let recording = self
            .recording
            .ok_or_else(|| LingerError::invalid_config("recording is required"))?;
        Ok(CreateVoiceConsentRequest {
            name,
            language,
            recording,
        })
    }
}

/// EN: JSON request body for `POST /v1/audio/voice_consents/{consent_id}`.
/// 中文：`POST /v1/audio/voice_consents/{consent_id}` 的 JSON 请求体。
#[derive(Clone, Debug, Serialize, PartialEq, Eq)]
#[non_exhaustive]
pub struct UpdateVoiceConsentRequest {
    /// EN: Updated label for this consent recording.
    /// 中文：此 consent 录音更新后的标签。
    pub name: String,
}

impl UpdateVoiceConsentRequest {
    /// EN: Starts building a voice consent update request.
    /// 中文：开始构建 voice consent 更新请求。
    pub fn builder() -> UpdateVoiceConsentRequestBuilder {
        UpdateVoiceConsentRequestBuilder::default()
    }
}

/// EN: Builder for voice consent update requests.
/// 中文：voice consent 更新请求的构建器。
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
pub struct UpdateVoiceConsentRequestBuilder {
    name: Option<String>,
}

impl UpdateVoiceConsentRequestBuilder {
    /// EN: Sets the updated consent recording label.
    /// 中文：设置更新后的 consent 录音标签。
    pub fn name(mut self, name: impl Into<String>) -> Self {
        self.name = Some(name.into());
        self
    }

    /// EN: Builds and validates the request.
    /// 中文：构建并校验请求。
    pub fn build(self) -> Result<UpdateVoiceConsentRequest, LingerError> {
        let name = required_string("name", self.name)?;
        Ok(UpdateVoiceConsentRequest { name })
    }
}

/// EN: Query parameters for `GET /v1/audio/voice_consents`.
/// 中文：`GET /v1/audio/voice_consents` 的查询参数。
#[derive(Clone, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct AudioVoiceConsentListRequest {
    /// EN: Maximum number of consent recordings to retrieve.
    /// 中文：要获取的最大 consent 录音数量。
    pub limit: Option<u8>,
    /// EN: Cursor after which the next page starts.
    /// 中文：下一页开始位置之前的游标。
    pub after: Option<String>,
}

impl AudioVoiceConsentListRequest {
    /// EN: Starts building voice consent list query parameters.
    /// 中文：开始构建 voice consent 列表查询参数。
    pub fn builder() -> AudioVoiceConsentListRequestBuilder {
        AudioVoiceConsentListRequestBuilder::default()
    }

    pub(crate) fn path(&self) -> String {
        path_with_query(
            "/v1/audio/voice_consents",
            AudioListQuery {
                limit: self.limit,
                after: self.after.as_deref(),
            },
        )
    }
}

/// EN: Builder for voice consent list query parameters.
/// 中文：voice consent 列表查询参数的构建器。
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
pub struct AudioVoiceConsentListRequestBuilder {
    limit: Option<u8>,
    after: Option<String>,
}

impl AudioVoiceConsentListRequestBuilder {
    /// EN: Sets the maximum number of consent recordings to retrieve.
    /// 中文：设置要获取的最大 consent 录音数量。
    pub fn limit(mut self, limit: u8) -> Self {
        self.limit = Some(limit);
        self
    }

    /// EN: Sets the cursor after which the next page starts.
    /// 中文：设置下一页开始位置之前的游标。
    pub fn after(mut self, after: impl Into<String>) -> Self {
        self.after = Some(after.into());
        self
    }

    /// EN: Builds and validates the query parameters.
    /// 中文：构建并校验查询参数。
    pub fn build(self) -> Result<AudioVoiceConsentListRequest, LingerError> {
        if let Some(limit) = self.limit {
            if limit == 0 || limit > 100 {
                return Err(LingerError::invalid_config(
                    "limit must be between 1 and 100",
                ));
            }
        }
        if let Some(after) = &self.after {
            if after.trim().is_empty() {
                return Err(LingerError::invalid_config("after must not be empty"));
            }
        }
        Ok(AudioVoiceConsentListRequest {
            limit: self.limit,
            after: self.after,
        })
    }
}

/// EN: Request body descriptor for `POST /v1/audio/voices`.
/// 中文：`POST /v1/audio/voices` 的请求体描述。
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub struct CreateVoiceRequest {
    /// EN: Name for the new custom voice.
    /// 中文：新自定义 voice 的名称。
    pub name: String,
    /// EN: Consent recording id authorizing this voice.
    /// 中文：授权此 voice 的 consent 录音 ID。
    pub consent: String,
    /// EN: Sample audio recording for the custom voice.
    /// 中文：用于自定义 voice 的示例录音。
    pub audio_sample: AudioUpload,
}

impl CreateVoiceRequest {
    /// EN: Starts building a custom voice request.
    /// 中文：开始构建自定义 voice 请求。
    pub fn builder() -> CreateVoiceRequestBuilder {
        CreateVoiceRequestBuilder::default()
    }

    pub(crate) fn apply_multipart_body(&self, request: &mut HttpRequest) {
        let fields = vec![
            ("name".to_string(), self.name.clone()),
            ("consent".to_string(), self.consent.clone()),
        ];
        apply_audio_multipart(request, "audio_sample", &self.audio_sample, fields);
    }
}

/// EN: Builder for custom voice requests.
/// 中文：自定义 voice 请求的构建器。
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
pub struct CreateVoiceRequestBuilder {
    name: Option<String>,
    consent: Option<String>,
    audio_sample: Option<AudioUpload>,
}

impl CreateVoiceRequestBuilder {
    /// EN: Sets the new custom voice name.
    /// 中文：设置新自定义 voice 的名称。
    pub fn name(mut self, name: impl Into<String>) -> Self {
        self.name = Some(name.into());
        self
    }

    /// EN: Sets the consent recording id.
    /// 中文：设置 consent 录音 ID。
    pub fn consent(mut self, consent: impl Into<String>) -> Self {
        self.consent = Some(consent.into());
        self
    }

    /// EN: Sets the sample audio recording.
    /// 中文：设置示例录音。
    pub fn audio_sample(mut self, audio_sample: AudioUpload) -> Self {
        self.audio_sample = Some(audio_sample);
        self
    }

    /// EN: Builds and validates the request.
    /// 中文：构建并校验请求。
    pub fn build(self) -> Result<CreateVoiceRequest, LingerError> {
        let name = required_string("name", self.name)?;
        let consent = required_string("consent", self.consent)?;
        let audio_sample = self
            .audio_sample
            .ok_or_else(|| LingerError::invalid_config("audio_sample is required"))?;
        Ok(CreateVoiceRequest {
            name,
            consent,
            audio_sample,
        })
    }
}

/// EN: Request body descriptor for `POST /v1/audio/transcriptions`.
/// 中文：`POST /v1/audio/transcriptions` 的请求体描述。
#[derive(Clone, Debug, PartialEq)]
#[non_exhaustive]
pub struct CreateTranscriptionRequest {
    /// EN: Audio file to transcribe.
    /// 中文：要转写的音频文件。
    pub file: AudioUpload,
    /// EN: Transcription model id.
    /// 中文：转写模型 ID。
    pub model: String,
    /// EN: Optional input language.
    /// 中文：可选的输入语言。
    pub language: Option<String>,
    /// EN: Optional prompt.
    /// 中文：可选提示。
    pub prompt: Option<String>,
    /// EN: Optional response format.
    /// 中文：可选响应格式。
    pub response_format: Option<String>,
    /// EN: Optional sampling temperature.
    /// 中文：可选采样温度。
    pub temperature: Option<f32>,
    /// EN: Optional timestamp granularities to populate.
    /// 中文：要填充的可选时间戳粒度。
    pub timestamp_granularities: Vec<String>,
    /// EN: Optional chunking strategy.
    /// 中文：可选分块策略。
    pub chunking_strategy: Option<String>,
    /// EN: Optional known speaker names for diarized transcription.
    /// 中文：用于说话人分离转写的可选已知说话人名称。
    pub known_speaker_names: Vec<String>,
    /// EN: Optional known speaker audio reference data URLs.
    /// 中文：可选的已知说话人音频引用 data URL。
    pub known_speaker_references: Vec<String>,
    include_logprobs: bool,
}

impl CreateTranscriptionRequest {
    /// EN: Starts building a transcription request.
    /// 中文：开始构建转写请求。
    pub fn builder() -> CreateTranscriptionRequestBuilder {
        CreateTranscriptionRequestBuilder::default()
    }

    pub(crate) fn apply_multipart_body(&self, request: &mut HttpRequest) {
        let mut fields = Vec::new();
        fields.push(("model".to_string(), self.model.clone()));
        push_optional_field(&mut fields, "language", self.language.as_deref());
        push_optional_field(&mut fields, "prompt", self.prompt.as_deref());
        push_optional_field(
            &mut fields,
            "response_format",
            self.response_format.as_deref(),
        );
        if let Some(temperature) = self.temperature {
            fields.push(("temperature".to_string(), temperature.to_string()));
        }
        for granularity in &self.timestamp_granularities {
            fields.push(("timestamp_granularities[]".to_string(), granularity.clone()));
        }
        push_optional_field(
            &mut fields,
            "chunking_strategy",
            self.chunking_strategy.as_deref(),
        );
        for name in &self.known_speaker_names {
            fields.push(("known_speaker_names[]".to_string(), name.clone()));
        }
        for reference in &self.known_speaker_references {
            fields.push(("known_speaker_references[]".to_string(), reference.clone()));
        }
        if self.include_logprobs {
            fields.push(("include[]".to_string(), "logprobs".to_string()));
        }
        apply_audio_multipart(request, "file", &self.file, fields);
    }
}

/// EN: Builder for transcription requests.
/// 中文：转写请求的构建器。
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
pub struct CreateTranscriptionRequestBuilder {
    file: Option<AudioUpload>,
    model: Option<String>,
    language: Option<String>,
    prompt: Option<String>,
    response_format: Option<String>,
    temperature: Option<f32>,
    timestamp_granularities: Vec<String>,
    chunking_strategy: Option<String>,
    known_speaker_names: Vec<String>,
    known_speaker_references: Vec<String>,
    include_logprobs: bool,
}

impl CreateTranscriptionRequestBuilder {
    /// EN: Sets the audio file.
    /// 中文：设置音频文件。
    pub fn file(mut self, file: AudioUpload) -> Self {
        self.file = Some(file);
        self
    }

    /// EN: Sets the transcription model id.
    /// 中文：设置转写模型 ID。
    pub fn model(mut self, model: impl Into<String>) -> Self {
        self.model = Some(model.into());
        self
    }

    /// EN: Sets the optional language.
    /// 中文：设置可选语言。
    pub fn language(mut self, language: impl Into<String>) -> Self {
        self.language = Some(language.into());
        self
    }

    /// EN: Sets the optional prompt.
    /// 中文：设置可选提示。
    pub fn prompt(mut self, prompt: impl Into<String>) -> Self {
        self.prompt = Some(prompt.into());
        self
    }

    /// EN: Sets the optional response format.
    /// 中文：设置可选响应格式。
    pub fn response_format(mut self, response_format: impl Into<String>) -> Self {
        self.response_format = Some(response_format.into());
        self
    }

    /// EN: Sets the optional temperature.
    /// 中文：设置可选 temperature。
    pub fn temperature(mut self, temperature: f32) -> Self {
        self.temperature = Some(temperature);
        self
    }

    /// EN: Adds a timestamp granularity such as `word` or `segment`.
    /// 中文：添加一个时间戳粒度，例如 `word` 或 `segment`。
    pub fn timestamp_granularity(mut self, granularity: impl Into<String>) -> Self {
        self.timestamp_granularities.push(granularity.into());
        self
    }

    /// EN: Replaces the timestamp granularity list.
    /// 中文：替换时间戳粒度列表。
    pub fn timestamp_granularities(
        mut self,
        granularities: impl IntoIterator<Item = impl Into<String>>,
    ) -> Self {
        self.timestamp_granularities = granularities.into_iter().map(Into::into).collect();
        self
    }

    /// EN: Sets the transcription chunking strategy to documented `auto`.
    /// 中文：将转写分块策略设置为官方文档中的 `auto`。
    pub fn chunking_strategy_auto(mut self) -> Self {
        self.chunking_strategy = Some("auto".to_string());
        self
    }

    /// EN: Adds a known speaker name for diarized transcription.
    /// 中文：为说话人分离转写添加一个已知说话人名称。
    pub fn known_speaker_name(mut self, name: impl Into<String>) -> Self {
        self.known_speaker_names.push(name.into());
        self
    }

    /// EN: Replaces the known speaker name list.
    /// 中文：替换已知说话人名称列表。
    pub fn known_speaker_names(
        mut self,
        names: impl IntoIterator<Item = impl Into<String>>,
    ) -> Self {
        self.known_speaker_names = names.into_iter().map(Into::into).collect();
        self
    }

    /// EN: Adds a known speaker reference audio data URL.
    /// 中文：添加一个已知说话人引用音频 data URL。
    pub fn known_speaker_reference(mut self, reference: impl Into<String>) -> Self {
        self.known_speaker_references.push(reference.into());
        self
    }

    /// EN: Replaces the known speaker reference list.
    /// 中文：替换已知说话人引用列表。
    pub fn known_speaker_references(
        mut self,
        references: impl IntoIterator<Item = impl Into<String>>,
    ) -> Self {
        self.known_speaker_references = references.into_iter().map(Into::into).collect();
        self
    }

    /// EN: Includes token log probabilities in the transcription response.
    /// 中文：在转写响应中包含 token 对数概率。
    pub fn include_logprobs(mut self) -> Self {
        self.include_logprobs = true;
        self
    }

    /// EN: Builds and validates the request.
    /// 中文：构建并校验请求。
    pub fn build(self) -> Result<CreateTranscriptionRequest, LingerError> {
        let file = self
            .file
            .ok_or_else(|| LingerError::invalid_config("file is required"))?;
        let model = required_string("model", self.model)?;
        validate_optional_string("language", self.language.as_deref())?;
        validate_optional_string("prompt", self.prompt.as_deref())?;
        validate_optional_string("response_format", self.response_format.as_deref())?;
        validate_optional_string("chunking_strategy", self.chunking_strategy.as_deref())?;
        validate_string_items("timestamp_granularities", &self.timestamp_granularities)?;
        validate_limited_string_items("known_speaker_names", &self.known_speaker_names, 4)?;
        validate_limited_string_items(
            "known_speaker_references",
            &self.known_speaker_references,
            4,
        )?;
        Ok(CreateTranscriptionRequest {
            file,
            model,
            language: self.language,
            prompt: self.prompt,
            response_format: self.response_format,
            temperature: self.temperature,
            timestamp_granularities: self.timestamp_granularities,
            chunking_strategy: self.chunking_strategy,
            known_speaker_names: self.known_speaker_names,
            known_speaker_references: self.known_speaker_references,
            include_logprobs: self.include_logprobs,
        })
    }
}

/// EN: Request body descriptor for `POST /v1/audio/translations`.
/// 中文：`POST /v1/audio/translations` 的请求体描述。
#[derive(Clone, Debug, PartialEq)]
#[non_exhaustive]
pub struct CreateTranslationRequest {
    /// EN: Audio file to translate.
    /// 中文：要翻译的音频文件。
    pub file: AudioUpload,
    /// EN: Translation model id.
    /// 中文：翻译模型 ID。
    pub model: String,
    /// EN: Optional prompt.
    /// 中文：可选提示。
    pub prompt: Option<String>,
    /// EN: Optional response format.
    /// 中文：可选响应格式。
    pub response_format: Option<String>,
    /// EN: Optional sampling temperature.
    /// 中文：可选采样温度。
    pub temperature: Option<f32>,
}

impl CreateTranslationRequest {
    /// EN: Starts building a translation request.
    /// 中文：开始构建翻译请求。
    pub fn builder() -> CreateTranslationRequestBuilder {
        CreateTranslationRequestBuilder::default()
    }

    pub(crate) fn apply_multipart_body(&self, request: &mut HttpRequest) {
        let mut fields = Vec::new();
        fields.push(("model".to_string(), self.model.clone()));
        push_optional_field(&mut fields, "prompt", self.prompt.as_deref());
        push_optional_field(
            &mut fields,
            "response_format",
            self.response_format.as_deref(),
        );
        if let Some(temperature) = self.temperature {
            fields.push(("temperature".to_string(), temperature.to_string()));
        }
        apply_audio_multipart(request, "file", &self.file, fields);
    }
}

/// EN: Builder for translation requests.
/// 中文：翻译请求的构建器。
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
pub struct CreateTranslationRequestBuilder {
    file: Option<AudioUpload>,
    model: Option<String>,
    prompt: Option<String>,
    response_format: Option<String>,
    temperature: Option<f32>,
}

impl CreateTranslationRequestBuilder {
    /// EN: Sets the audio file.
    /// 中文：设置音频文件。
    pub fn file(mut self, file: AudioUpload) -> Self {
        self.file = Some(file);
        self
    }

    /// EN: Sets the translation model id.
    /// 中文：设置翻译模型 ID。
    pub fn model(mut self, model: impl Into<String>) -> Self {
        self.model = Some(model.into());
        self
    }

    /// EN: Sets the optional prompt.
    /// 中文：设置可选提示。
    pub fn prompt(mut self, prompt: impl Into<String>) -> Self {
        self.prompt = Some(prompt.into());
        self
    }

    /// EN: Sets the optional response format.
    /// 中文：设置可选响应格式。
    pub fn response_format(mut self, response_format: impl Into<String>) -> Self {
        self.response_format = Some(response_format.into());
        self
    }

    /// EN: Sets the optional temperature.
    /// 中文：设置可选 temperature。
    pub fn temperature(mut self, temperature: f32) -> Self {
        self.temperature = Some(temperature);
        self
    }

    /// EN: Builds and validates the request.
    /// 中文：构建并校验请求。
    pub fn build(self) -> Result<CreateTranslationRequest, LingerError> {
        let file = self
            .file
            .ok_or_else(|| LingerError::invalid_config("file is required"))?;
        let model = required_string("model", self.model)?;
        validate_optional_string("prompt", self.prompt.as_deref())?;
        validate_optional_string("response_format", self.response_format.as_deref())?;
        Ok(CreateTranslationRequest {
            file,
            model,
            prompt: self.prompt,
            response_format: self.response_format,
            temperature: self.temperature,
        })
    }
}

/// EN: JSON transcription response.
/// 中文：JSON 转写响应。
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
#[non_exhaustive]
pub struct AudioTranscription {
    /// EN: Transcribed text.
    /// 中文：转写文本。
    pub text: String,
    /// EN: Additional fields preserved for forward compatibility.
    /// 中文：为前向兼容保留的额外字段。
    #[serde(flatten)]
    pub extra: BTreeMap<String, Value>,
    /// EN: OpenAI request id from response headers.
    /// 中文：响应头中的 OpenAI 请求 ID。
    #[serde(skip)]
    request_id: Option<RequestId>,
}

impl AudioTranscription {
    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
        self.request_id = request_id;
        self
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }
}

/// EN: JSON translation response.
/// 中文：JSON 翻译响应。
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
#[non_exhaustive]
pub struct AudioTranslation {
    /// EN: Translated text.
    /// 中文：翻译文本。
    pub text: String,
    /// EN: Additional fields preserved for forward compatibility.
    /// 中文：为前向兼容保留的额外字段。
    #[serde(flatten)]
    pub extra: BTreeMap<String, Value>,
    /// EN: OpenAI request id from response headers.
    /// 中文：响应头中的 OpenAI 请求 ID。
    #[serde(skip)]
    request_id: Option<RequestId>,
}

impl AudioTranslation {
    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
        self.request_id = request_id;
        self
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }
}

/// EN: Voice consent recording used to authorize custom voice creation.
/// 中文：用于授权创建自定义语音的 voice consent 录音。
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
#[non_exhaustive]
pub struct AudioVoiceConsent {
    /// EN: API object type, normally `audio.voice_consent`.
    /// 中文：API 对象类型，通常为 `audio.voice_consent`。
    pub object: String,
    /// EN: Consent recording id.
    /// 中文：consent 录音 ID。
    pub id: String,
    /// EN: Label provided when the consent recording was uploaded.
    /// 中文：上传 consent 录音时提供的标签。
    pub name: String,
    /// EN: BCP 47 language tag for the consent phrase.
    /// 中文：consent 短语的 BCP 47 语言标签。
    pub language: String,
    /// EN: Unix timestamp for creation.
    /// 中文：创建时间的 Unix 时间戳。
    pub created_at: u64,
    /// EN: OpenAI request id from response headers.
    /// 中文：响应头中的 OpenAI 请求 ID。
    #[serde(skip)]
    request_id: Option<RequestId>,
}

impl AudioVoiceConsent {
    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
        self.request_id = request_id;
        self
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }
}

/// EN: Paginated voice consent list.
/// 中文：分页 voice consent 列表。
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
#[non_exhaustive]
pub struct AudioVoiceConsentPage {
    /// EN: API list object type.
    /// 中文：API 列表对象类型。
    pub object: String,
    /// EN: Voice consent recordings on this page.
    /// 中文：本页 voice consent 录音。
    #[serde(default)]
    pub data: Vec<AudioVoiceConsent>,
    /// EN: First voice consent id on this page.
    /// 中文：本页第一个 voice consent ID。
    #[serde(default)]
    pub first_id: Option<String>,
    /// EN: Last voice consent id on this page.
    /// 中文：本页最后一个 voice consent ID。
    #[serde(default)]
    pub last_id: Option<String>,
    /// EN: Whether more voice consents are available.
    /// 中文：是否还有更多 voice consent。
    pub has_more: bool,
    /// EN: OpenAI request id from response headers.
    /// 中文：响应头中的 OpenAI 请求 ID。
    #[serde(skip)]
    request_id: Option<RequestId>,
}

impl AudioVoiceConsentPage {
    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
        self.request_id = request_id;
        self
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }
}

/// EN: Deletion result returned for voice consent recordings.
/// 中文：voice consent 录音的删除结果。
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
#[non_exhaustive]
pub struct AudioVoiceConsentDeletion {
    /// EN: Deleted voice consent id.
    /// 中文：已删除的 voice consent ID。
    pub id: String,
    /// EN: API object type, normally `audio.voice_consent`.
    /// 中文：API 对象类型，通常为 `audio.voice_consent`。
    pub object: String,
    /// EN: Whether the voice consent was deleted.
    /// 中文：voice consent 是否已删除。
    pub deleted: bool,
    /// EN: OpenAI request id from response headers.
    /// 中文：响应头中的 OpenAI 请求 ID。
    #[serde(skip)]
    request_id: Option<RequestId>,
}

impl AudioVoiceConsentDeletion {
    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
        self.request_id = request_id;
        self
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }
}

/// EN: Custom voice returned by the Audio Voices API.
/// 中文：Audio Voices API 返回的自定义 voice。
#[derive(Clone, Debug, Deserialize, PartialEq, Eq)]
#[non_exhaustive]
pub struct AudioVoice {
    /// EN: API object type, normally `audio.voice`.
    /// 中文：API 对象类型，通常为 `audio.voice`。
    pub object: String,
    /// EN: Voice identifier usable in audio output endpoints.
    /// 中文：可用于音频输出端点的 voice 标识符。
    pub id: String,
    /// EN: Voice name.
    /// 中文：voice 名称。
    pub name: String,
    /// EN: Unix timestamp for creation.
    /// 中文：创建时间的 Unix 时间戳。
    pub created_at: u64,
    /// EN: OpenAI request id from response headers.
    /// 中文：响应头中的 OpenAI 请求 ID。
    #[serde(skip)]
    request_id: Option<RequestId>,
}

impl AudioVoice {
    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
        self.request_id = request_id;
        self
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }
}

fn apply_audio_multipart(
    request: &mut HttpRequest,
    file_field_name: &str,
    file: &AudioUpload,
    fields: Vec<(String, String)>,
) {
    let boundary = multipart_boundary(&file.content);
    request.insert_header(
        "content-type",
        format!("multipart/form-data; boundary={boundary}"),
    );
    let mut chunks = Vec::new();
    for (name, value) in fields {
        chunks.push(Ok(Bytes::from(format!(
            "--{boundary}\r\nContent-Disposition: form-data; name=\"{name}\"\r\n\r\n{value}\r\n"
        ))));
    }
    chunks.push(Ok(Bytes::from(format!(
        "--{boundary}\r\nContent-Disposition: form-data; name=\"{}\"; filename=\"{}\"\r\nContent-Type: {}\r\n\r\n",
        escape_multipart_param(file_field_name),
        escape_multipart_param(&file.filename),
        file.content_type
    ))));
    chunks.push(Ok(file.content.clone()));
    chunks.push(Ok(Bytes::from(format!("\r\n--{boundary}--\r\n"))));
    request.set_body_stream(futures_util::stream::iter(chunks));
}

fn push_optional_field(fields: &mut Vec<(String, String)>, name: &str, value: Option<&str>) {
    if let Some(value) = value {
        fields.push((name.to_string(), value.to_string()));
    }
}

fn multipart_boundary(content: &Bytes) -> String {
    for counter in 0.. {
        let boundary = format!("linger-openai-sdk-audio-boundary-{counter}");
        if !contains_bytes(content, boundary.as_bytes()) {
            return boundary;
        }
    }
    unreachable!("unbounded boundary counter")
}

fn contains_bytes(haystack: &[u8], needle: &[u8]) -> bool {
    if needle.is_empty() {
        return true;
    }
    haystack
        .windows(needle.len())
        .any(|window| window == needle)
}

fn required_string(name: &str, value: Option<String>) -> Result<String, LingerError> {
    value
        .filter(|value| !value.trim().is_empty())
        .ok_or_else(|| LingerError::invalid_config(format!("{name} is required")))
}

fn validate_optional_string(name: &str, value: Option<&str>) -> Result<(), LingerError> {
    if value.is_some_and(|value| value.trim().is_empty()) {
        return Err(LingerError::invalid_config(format!(
            "{name} must not be empty"
        )));
    }
    Ok(())
}

fn validate_max_chars(name: &str, value: &str, max_chars: usize) -> Result<(), LingerError> {
    if value.chars().count() > max_chars {
        return Err(LingerError::invalid_config(format!(
            "{name} must be at most {max_chars} characters"
        )));
    }
    Ok(())
}

fn validate_string_items(name: &str, values: &[String]) -> Result<(), LingerError> {
    if values.iter().any(|value| value.trim().is_empty()) {
        return Err(LingerError::invalid_config(format!(
            "{name} must not contain empty values"
        )));
    }
    Ok(())
}

fn validate_limited_string_items(
    name: &str,
    values: &[String],
    max: usize,
) -> Result<(), LingerError> {
    validate_string_items(name, values)?;
    if values.len() > max {
        return Err(LingerError::invalid_config(format!(
            "{name} must contain at most {max} values"
        )));
    }
    Ok(())
}

fn validate_header_param(name: &str, value: &str) -> Result<(), LingerError> {
    if value.trim().is_empty() {
        return Err(LingerError::invalid_config(format!("{name} is required")));
    }
    validate_header_value(name, value)
}

fn validate_header_value(name: &str, value: &str) -> Result<(), LingerError> {
    if value.contains('\r') || value.contains('\n') {
        return Err(LingerError::invalid_config(format!(
            "{name} must not contain CR or LF"
        )));
    }
    Ok(())
}

fn escape_multipart_param(value: &str) -> String {
    value.replace('\\', "\\\\").replace('"', "\\\"")
}

struct AudioListQuery<'a> {
    limit: Option<u8>,
    after: Option<&'a str>,
}

fn path_with_query(base: &str, params: AudioListQuery<'_>) -> String {
    let mut query = Vec::new();
    if let Some(limit) = params.limit {
        query.push(format!("limit={limit}"));
    }
    if let Some(after) = params.after {
        query.push(format!("after={}", encode_query_value(after)));
    }
    if query.is_empty() {
        base.to_string()
    } else {
        format!("{base}?{}", query.join("&"))
    }
}

fn encode_query_value(value: &str) -> String {
    let mut encoded = String::new();
    for byte in value.bytes() {
        match byte {
            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'.' | b'_' | b'~' => {
                encoded.push(byte as char);
            }
            _ => {
                const HEX: &[u8; 16] = b"0123456789ABCDEF";
                encoded.push('%');
                encoded.push(HEX[(byte >> 4) as usize] as char);
                encoded.push(HEX[(byte & 0x0F) as usize] as char);
            }
        }
    }
    encoded
}