openai_interface/audio/
translations.rs

1//! Translates audio into English.
2//!
3//! Endpoint: `POST /audio/translations` (multipart/form-data request).
4//!
5//! Response shapes depend on `response_format`, same as transcriptions:
6//!
7//! - `json` and `verbose_json` deserialize into the typed
8//!   [`TranslationResponse`] via `get_response`.
9//! - `text`, `srt`, and `vtt` return plain text; use
10//!   `get_response_string` for those.
11//!
12//! > ![warn] This module is untested!
13//! > No OpenAI-compatible provider accessible to this project implements
14//! > this endpoint, and no OpenAI API key was available for testing. If you
15//! > encounter any issues, please report them on the repository.
16
17use std::path::PathBuf;
18
19use serde::{Deserialize, Serialize};
20use url::Url;
21
22use crate::{
23    audio::{AudioResponseFormat, transcriptions::TranscriptionVerbose},
24    errors::OapiError,
25    rest::RequestOptions,
26    rest::post::{Post, PostNoStream},
27};
28
29/// Translates audio into English. Only `whisper-1` (which is powered by the
30/// open source Whisper V2 model) is currently available.
31#[derive(Debug, Serialize, Default, Clone)]
32pub struct TranslationRequest {
33    /// The audio file (as a path) to translate, in one of these formats:
34    /// flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm. The request must
35    /// include enough format metadata for the file to be identified; an
36    /// extension-bearing filename satisfies this.
37    #[serde(skip_serializing)]
38    pub file: PathBuf,
39    /// ID of the model to use. Only `whisper-1` (which is powered by the
40    /// open source Whisper V2 model) is currently available.
41    pub model: String,
42    /// An optional text to guide the model's style or continue a previous
43    /// audio segment. The prompt should be in English.
44    #[serde(skip_serializing_if = "Option::is_none")]
45    pub prompt: Option<String>,
46    /// The format of the output, in one of these options: `json`, `text`,
47    /// `srt`, `verbose_json`, or `vtt`.
48    ///
49    /// With `json` / `verbose_json`, use `get_response`; with `text` /
50    /// `srt` / `vtt`, use `get_response_string`.
51    #[serde(skip_serializing_if = "Option::is_none")]
52    pub response_format: Option<AudioResponseFormat>,
53    /// The sampling temperature, between 0 and 1. Higher values like 0.8
54    /// will make the output more random, while lower values like 0.2 will
55    /// make it more focused and deterministic.
56    #[serde(skip_serializing_if = "Option::is_none")]
57    pub temperature: Option<f32>,
58}
59
60/// The typed translation response: `json` yields a plain
61/// [`Translation`], `verbose_json` yields a [`TranscriptionVerbose`].
62#[derive(Debug, Deserialize, Clone)]
63#[serde(untagged)]
64pub enum TranslationResponse {
65    /// The `verbose_json` response shape (requires `duration` and
66    /// `language`).
67    Verbose(TranscriptionVerbose),
68    /// The `json` response shape.
69    Plain(Translation),
70}
71
72/// Represents a translation response returned by the model.
73#[derive(Debug, Deserialize, Clone)]
74pub struct Translation {
75    /// The translated text.
76    pub text: String,
77}
78
79crate::impl_from_str!(TranslationResponse);
80
81impl Post for TranslationRequest {
82    #[inline]
83    fn is_streaming(&self) -> bool {
84        false
85    }
86
87    /// Builds the URL for the request.
88    ///
89    /// `base_url` should be like <https://api.openai.com/v1>
90    fn build_url(&self, base_url: &str) -> Result<String, OapiError> {
91        let mut url = Url::parse(base_url.trim_end_matches('/')).map_err(OapiError::UrlError)?;
92        url.path_segments_mut()
93            .map_err(|_| OapiError::UrlCannotBeBase(base_url.to_string()))?
94            .push("audio")
95            .push("translations");
96
97        Ok(url.to_string())
98    }
99}
100
101impl PostNoStream for TranslationRequest {
102    type Response = TranslationResponse;
103
104    /// Sends a translation POST request using multipart/form-data format,
105    /// following the field layout of the official SDK.
106    async fn get_response_string(
107        &self,
108        client: &reqwest::Client,
109        base_url: &str,
110        options: &RequestOptions,
111    ) -> Result<String, OapiError> {
112        if !self.file.exists() {
113            return Err(OapiError::FileNotFoundError(self.file.clone()));
114        }
115
116        let content = tokio::fs::read(&self.file).await?;
117        let file_name = self
118            .file
119            .file_name()
120            .and_then(|name| name.to_str())
121            .ok_or_else(|| OapiError::ResponseError("Invalid file name".to_string()))?
122            .to_string();
123
124        let file_part = reqwest::multipart::Part::bytes(content).file_name(file_name);
125        let mut form = reqwest::multipart::Form::new().part("file", file_part);
126
127        form = form.text("model", self.model.clone());
128
129        if let Some(prompt) = &self.prompt {
130            form = form.text("prompt", prompt.clone());
131        }
132        if let Some(response_format) = self.response_format {
133            let literal = crate::audio::enum_to_literal(&response_format)?;
134            form = form.text("response_format", literal);
135        }
136        if let Some(temperature) = self.temperature {
137            form = form.text("temperature", temperature.to_string());
138        }
139
140        let url = self.build_url(base_url)?;
141        crate::rest::post::post_multipart_json(client, url, form, options).await
142    }
143}
144
145#[cfg(test)]
146mod tests {
147    use super::*;
148
149    #[test]
150    fn test_build_url() {
151        let request = TranslationRequest::default();
152        let url = request.build_url("https://api.openai.com/v1/").unwrap();
153        assert_eq!(url, "https://api.openai.com/v1/audio/translations");
154    }
155
156    /// Deserializes a `json` translation response.
157    ///
158    /// No accessible provider implements this endpoint, so this fixture is
159    /// NOT captured from a live response. The structure follows the schema
160    /// of openai-python `types/audio/translation.py`; the values are
161    /// constructed for the test.
162    #[test]
163    fn parse_plain_response() {
164        let content = r#"{
165            "text": "The quick brown fox jumped over the lazy dog."
166        }"#;
167
168        let response: TranslationResponse = content.parse().unwrap();
169        let TranslationResponse::Plain(translation) = response else {
170            panic!("expected plain translation");
171        };
172        assert_eq!(
173            translation.text,
174            "The quick brown fox jumped over the lazy dog."
175        );
176    }
177}
openai_interface/audio/translations.rs

openai_interface/audio/
translations.rs
