main
1# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
2
3from __future__ import annotations
4
5import logging
6from typing import TYPE_CHECKING, Union, Mapping, cast
7from typing_extensions import Literal, overload, assert_never
8
9import httpx
10
11from ... import _legacy_response
12from ..._types import Body, Omit, Query, Headers, NotGiven, FileTypes, omit, not_given
13from ..._utils import extract_files, maybe_transform, deepcopy_minimal, async_maybe_transform
14from ..._compat import cached_property
15from ..._resource import SyncAPIResource, AsyncAPIResource
16from ..._response import to_streamed_response_wrapper, async_to_streamed_response_wrapper
17from ...types.audio import translation_create_params
18from ..._base_client import make_request_options
19from ...types.audio_model import AudioModel
20from ...types.audio.translation import Translation
21from ...types.audio_response_format import AudioResponseFormat
22from ...types.audio.translation_verbose import TranslationVerbose
23
24__all__ = ["Translations", "AsyncTranslations"]
25
26log: logging.Logger = logging.getLogger("openai.audio.transcriptions")
27
28
29class Translations(SyncAPIResource):
30 @cached_property
31 def with_raw_response(self) -> TranslationsWithRawResponse:
32 """
33 This property can be used as a prefix for any HTTP method call to return
34 the raw response object instead of the parsed content.
35
36 For more information, see https://www.github.com/openai/openai-python#accessing-raw-response-data-eg-headers
37 """
38 return TranslationsWithRawResponse(self)
39
40 @cached_property
41 def with_streaming_response(self) -> TranslationsWithStreamingResponse:
42 """
43 An alternative to `.with_raw_response` that doesn't eagerly read the response body.
44
45 For more information, see https://www.github.com/openai/openai-python#with_streaming_response
46 """
47 return TranslationsWithStreamingResponse(self)
48
49 @overload
50 def create(
51 self,
52 *,
53 file: FileTypes,
54 model: Union[str, AudioModel],
55 response_format: Union[Literal["json"], Omit] = omit,
56 prompt: str | Omit = omit,
57 temperature: float | Omit = omit,
58 # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
59 # The extra values given here take precedence over values defined on the client or passed to this method.
60 extra_headers: Headers | None = None,
61 extra_query: Query | None = None,
62 extra_body: Body | None = None,
63 timeout: float | httpx.Timeout | None | NotGiven = not_given,
64 ) -> Translation: ...
65
66 @overload
67 def create(
68 self,
69 *,
70 file: FileTypes,
71 model: Union[str, AudioModel],
72 response_format: Literal["verbose_json"],
73 prompt: str | Omit = omit,
74 temperature: float | Omit = omit,
75 # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
76 # The extra values given here take precedence over values defined on the client or passed to this method.
77 extra_headers: Headers | None = None,
78 extra_query: Query | None = None,
79 extra_body: Body | None = None,
80 timeout: float | httpx.Timeout | None | NotGiven = not_given,
81 ) -> TranslationVerbose: ...
82
83 @overload
84 def create(
85 self,
86 *,
87 file: FileTypes,
88 model: Union[str, AudioModel],
89 response_format: Literal["text", "srt", "vtt"],
90 prompt: str | Omit = omit,
91 temperature: float | Omit = omit,
92 # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
93 # The extra values given here take precedence over values defined on the client or passed to this method.
94 extra_headers: Headers | None = None,
95 extra_query: Query | None = None,
96 extra_body: Body | None = None,
97 timeout: float | httpx.Timeout | None | NotGiven = not_given,
98 ) -> str: ...
99
100 def create(
101 self,
102 *,
103 file: FileTypes,
104 model: Union[str, AudioModel],
105 prompt: str | Omit = omit,
106 response_format: Union[Literal["json", "text", "srt", "verbose_json", "vtt"], Omit] = omit,
107 temperature: float | Omit = omit,
108 # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
109 # The extra values given here take precedence over values defined on the client or passed to this method.
110 extra_headers: Headers | None = None,
111 extra_query: Query | None = None,
112 extra_body: Body | None = None,
113 timeout: float | httpx.Timeout | None | NotGiven = not_given,
114 ) -> Translation | TranslationVerbose | str:
115 """
116 Translates audio into English.
117
118 Args:
119 file: The audio file object (not file name) translate, in one of these formats: flac,
120 mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm.
121
122 model: ID of the model to use. Only `whisper-1` (which is powered by our open source
123 Whisper V2 model) is currently available.
124
125 prompt: An optional text to guide the model's style or continue a previous audio
126 segment. The
127 [prompt](https://platform.openai.com/docs/guides/speech-to-text#prompting)
128 should be in English.
129
130 response_format: The format of the output, in one of these options: `json`, `text`, `srt`,
131 `verbose_json`, or `vtt`.
132
133 temperature: The sampling temperature, between 0 and 1. Higher values like 0.8 will make the
134 output more random, while lower values like 0.2 will make it more focused and
135 deterministic. If set to 0, the model will use
136 [log probability](https://en.wikipedia.org/wiki/Log_probability) to
137 automatically increase the temperature until certain thresholds are hit.
138
139 extra_headers: Send extra headers
140
141 extra_query: Add additional query parameters to the request
142
143 extra_body: Add additional JSON properties to the request
144
145 timeout: Override the client-level default timeout for this request, in seconds
146 """
147 body = deepcopy_minimal(
148 {
149 "file": file,
150 "model": model,
151 "prompt": prompt,
152 "response_format": response_format,
153 "temperature": temperature,
154 }
155 )
156 files = extract_files(cast(Mapping[str, object], body), paths=[["file"]])
157 # It should be noted that the actual Content-Type header that will be
158 # sent to the server will contain a `boundary` parameter, e.g.
159 # multipart/form-data; boundary=---abc--
160 extra_headers = {"Content-Type": "multipart/form-data", **(extra_headers or {})}
161 return self._post( # type: ignore[return-value]
162 "/audio/translations",
163 body=maybe_transform(body, translation_create_params.TranslationCreateParams),
164 files=files,
165 options=make_request_options(
166 extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
167 ),
168 cast_to=_get_response_format_type(response_format),
169 )
170
171
172class AsyncTranslations(AsyncAPIResource):
173 @cached_property
174 def with_raw_response(self) -> AsyncTranslationsWithRawResponse:
175 """
176 This property can be used as a prefix for any HTTP method call to return
177 the raw response object instead of the parsed content.
178
179 For more information, see https://www.github.com/openai/openai-python#accessing-raw-response-data-eg-headers
180 """
181 return AsyncTranslationsWithRawResponse(self)
182
183 @cached_property
184 def with_streaming_response(self) -> AsyncTranslationsWithStreamingResponse:
185 """
186 An alternative to `.with_raw_response` that doesn't eagerly read the response body.
187
188 For more information, see https://www.github.com/openai/openai-python#with_streaming_response
189 """
190 return AsyncTranslationsWithStreamingResponse(self)
191
192 @overload
193 async def create(
194 self,
195 *,
196 file: FileTypes,
197 model: Union[str, AudioModel],
198 response_format: Union[Literal["json"], Omit] = omit,
199 prompt: str | Omit = omit,
200 temperature: float | Omit = omit,
201 # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
202 # The extra values given here take precedence over values defined on the client or passed to this method.
203 extra_headers: Headers | None = None,
204 extra_query: Query | None = None,
205 extra_body: Body | None = None,
206 timeout: float | httpx.Timeout | None | NotGiven = not_given,
207 ) -> Translation: ...
208
209 @overload
210 async def create(
211 self,
212 *,
213 file: FileTypes,
214 model: Union[str, AudioModel],
215 response_format: Literal["verbose_json"],
216 prompt: str | Omit = omit,
217 temperature: float | Omit = omit,
218 # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
219 # The extra values given here take precedence over values defined on the client or passed to this method.
220 extra_headers: Headers | None = None,
221 extra_query: Query | None = None,
222 extra_body: Body | None = None,
223 timeout: float | httpx.Timeout | None | NotGiven = not_given,
224 ) -> TranslationVerbose: ...
225
226 @overload
227 async def create(
228 self,
229 *,
230 file: FileTypes,
231 model: Union[str, AudioModel],
232 response_format: Literal["text", "srt", "vtt"],
233 prompt: str | Omit = omit,
234 temperature: float | Omit = omit,
235 # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
236 # The extra values given here take precedence over values defined on the client or passed to this method.
237 extra_headers: Headers | None = None,
238 extra_query: Query | None = None,
239 extra_body: Body | None = None,
240 timeout: float | httpx.Timeout | None | NotGiven = not_given,
241 ) -> str: ...
242
243 async def create(
244 self,
245 *,
246 file: FileTypes,
247 model: Union[str, AudioModel],
248 prompt: str | Omit = omit,
249 response_format: Union[AudioResponseFormat, Omit] = omit,
250 temperature: float | Omit = omit,
251 # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
252 # The extra values given here take precedence over values defined on the client or passed to this method.
253 extra_headers: Headers | None = None,
254 extra_query: Query | None = None,
255 extra_body: Body | None = None,
256 timeout: float | httpx.Timeout | None | NotGiven = not_given,
257 ) -> Translation | TranslationVerbose | str:
258 """
259 Translates audio into English.
260
261 Args:
262 file: The audio file object (not file name) translate, in one of these formats: flac,
263 mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm.
264
265 model: ID of the model to use. Only `whisper-1` (which is powered by our open source
266 Whisper V2 model) is currently available.
267
268 prompt: An optional text to guide the model's style or continue a previous audio
269 segment. The
270 [prompt](https://platform.openai.com/docs/guides/speech-to-text#prompting)
271 should be in English.
272
273 response_format: The format of the output, in one of these options: `json`, `text`, `srt`,
274 `verbose_json`, or `vtt`.
275
276 temperature: The sampling temperature, between 0 and 1. Higher values like 0.8 will make the
277 output more random, while lower values like 0.2 will make it more focused and
278 deterministic. If set to 0, the model will use
279 [log probability](https://en.wikipedia.org/wiki/Log_probability) to
280 automatically increase the temperature until certain thresholds are hit.
281
282 extra_headers: Send extra headers
283
284 extra_query: Add additional query parameters to the request
285
286 extra_body: Add additional JSON properties to the request
287
288 timeout: Override the client-level default timeout for this request, in seconds
289 """
290 body = deepcopy_minimal(
291 {
292 "file": file,
293 "model": model,
294 "prompt": prompt,
295 "response_format": response_format,
296 "temperature": temperature,
297 }
298 )
299 files = extract_files(cast(Mapping[str, object], body), paths=[["file"]])
300 # It should be noted that the actual Content-Type header that will be
301 # sent to the server will contain a `boundary` parameter, e.g.
302 # multipart/form-data; boundary=---abc--
303 extra_headers = {"Content-Type": "multipart/form-data", **(extra_headers or {})}
304 return await self._post(
305 "/audio/translations",
306 body=await async_maybe_transform(body, translation_create_params.TranslationCreateParams),
307 files=files,
308 options=make_request_options(
309 extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
310 ),
311 cast_to=_get_response_format_type(response_format),
312 )
313
314
315class TranslationsWithRawResponse:
316 def __init__(self, translations: Translations) -> None:
317 self._translations = translations
318
319 self.create = _legacy_response.to_raw_response_wrapper(
320 translations.create,
321 )
322
323
324class AsyncTranslationsWithRawResponse:
325 def __init__(self, translations: AsyncTranslations) -> None:
326 self._translations = translations
327
328 self.create = _legacy_response.async_to_raw_response_wrapper(
329 translations.create,
330 )
331
332
333class TranslationsWithStreamingResponse:
334 def __init__(self, translations: Translations) -> None:
335 self._translations = translations
336
337 self.create = to_streamed_response_wrapper(
338 translations.create,
339 )
340
341
342class AsyncTranslationsWithStreamingResponse:
343 def __init__(self, translations: AsyncTranslations) -> None:
344 self._translations = translations
345
346 self.create = async_to_streamed_response_wrapper(
347 translations.create,
348 )
349
350
351def _get_response_format_type(
352 response_format: AudioResponseFormat | Omit,
353) -> type[Translation | TranslationVerbose | str]:
354 if isinstance(response_format, Omit) or response_format is None: # pyright: ignore[reportUnnecessaryComparison]
355 return Translation
356
357 if response_format == "json":
358 return Translation
359 elif response_format == "verbose_json":
360 return TranslationVerbose
361 elif response_format == "srt" or response_format == "text" or response_format == "vtt":
362 return str
363 elif TYPE_CHECKING and response_format != "diarized_json": # type: ignore[unreachable]
364 assert_never(response_format)
365 else:
366 log.warning("Unexpected audio response format: %s", response_format)
367 return Translation