main
1# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
2
3from __future__ import annotations
4
5from typing import Union
6from typing_extensions import Literal
7
8import httpx
9
10from ... import _legacy_response
11from ..._types import Body, Omit, Query, Headers, NotGiven, omit, not_given
12from ..._utils import maybe_transform, async_maybe_transform
13from ..._compat import cached_property
14from ..._resource import SyncAPIResource, AsyncAPIResource
15from ..._response import (
16 StreamedBinaryAPIResponse,
17 AsyncStreamedBinaryAPIResponse,
18 to_custom_streamed_response_wrapper,
19 async_to_custom_streamed_response_wrapper,
20)
21from ...types.audio import speech_create_params
22from ..._base_client import make_request_options
23from ...types.audio.speech_model import SpeechModel
24
25__all__ = ["Speech", "AsyncSpeech"]
26
27
28class Speech(SyncAPIResource):
29 @cached_property
30 def with_raw_response(self) -> SpeechWithRawResponse:
31 """
32 This property can be used as a prefix for any HTTP method call to return
33 the raw response object instead of the parsed content.
34
35 For more information, see https://www.github.com/openai/openai-python#accessing-raw-response-data-eg-headers
36 """
37 return SpeechWithRawResponse(self)
38
39 @cached_property
40 def with_streaming_response(self) -> SpeechWithStreamingResponse:
41 """
42 An alternative to `.with_raw_response` that doesn't eagerly read the response body.
43
44 For more information, see https://www.github.com/openai/openai-python#with_streaming_response
45 """
46 return SpeechWithStreamingResponse(self)
47
48 def create(
49 self,
50 *,
51 input: str,
52 model: Union[str, SpeechModel],
53 voice: Union[
54 str, Literal["alloy", "ash", "ballad", "coral", "echo", "sage", "shimmer", "verse", "marin", "cedar"]
55 ],
56 instructions: str | Omit = omit,
57 response_format: Literal["mp3", "opus", "aac", "flac", "wav", "pcm"] | Omit = omit,
58 speed: float | Omit = omit,
59 stream_format: Literal["sse", "audio"] | Omit = omit,
60 # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
61 # The extra values given here take precedence over values defined on the client or passed to this method.
62 extra_headers: Headers | None = None,
63 extra_query: Query | None = None,
64 extra_body: Body | None = None,
65 timeout: float | httpx.Timeout | None | NotGiven = not_given,
66 ) -> _legacy_response.HttpxBinaryResponseContent:
67 """
68 Generates audio from the input text.
69
70 Args:
71 input: The text to generate audio for. The maximum length is 4096 characters.
72
73 model:
74 One of the available [TTS models](https://platform.openai.com/docs/models#tts):
75 `tts-1`, `tts-1-hd` or `gpt-4o-mini-tts`.
76
77 voice: The voice to use when generating the audio. Supported voices are `alloy`, `ash`,
78 `ballad`, `coral`, `echo`, `fable`, `onyx`, `nova`, `sage`, `shimmer`, and
79 `verse`. Previews of the voices are available in the
80 [Text to speech guide](https://platform.openai.com/docs/guides/text-to-speech#voice-options).
81
82 instructions: Control the voice of your generated audio with additional instructions. Does not
83 work with `tts-1` or `tts-1-hd`.
84
85 response_format: The format to audio in. Supported formats are `mp3`, `opus`, `aac`, `flac`,
86 `wav`, and `pcm`.
87
88 speed: The speed of the generated audio. Select a value from `0.25` to `4.0`. `1.0` is
89 the default.
90
91 stream_format: The format to stream the audio in. Supported formats are `sse` and `audio`.
92 `sse` is not supported for `tts-1` or `tts-1-hd`.
93
94 extra_headers: Send extra headers
95
96 extra_query: Add additional query parameters to the request
97
98 extra_body: Add additional JSON properties to the request
99
100 timeout: Override the client-level default timeout for this request, in seconds
101 """
102 extra_headers = {"Accept": "application/octet-stream", **(extra_headers or {})}
103 return self._post(
104 "/audio/speech",
105 body=maybe_transform(
106 {
107 "input": input,
108 "model": model,
109 "voice": voice,
110 "instructions": instructions,
111 "response_format": response_format,
112 "speed": speed,
113 "stream_format": stream_format,
114 },
115 speech_create_params.SpeechCreateParams,
116 ),
117 options=make_request_options(
118 extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
119 ),
120 cast_to=_legacy_response.HttpxBinaryResponseContent,
121 )
122
123
124class AsyncSpeech(AsyncAPIResource):
125 @cached_property
126 def with_raw_response(self) -> AsyncSpeechWithRawResponse:
127 """
128 This property can be used as a prefix for any HTTP method call to return
129 the raw response object instead of the parsed content.
130
131 For more information, see https://www.github.com/openai/openai-python#accessing-raw-response-data-eg-headers
132 """
133 return AsyncSpeechWithRawResponse(self)
134
135 @cached_property
136 def with_streaming_response(self) -> AsyncSpeechWithStreamingResponse:
137 """
138 An alternative to `.with_raw_response` that doesn't eagerly read the response body.
139
140 For more information, see https://www.github.com/openai/openai-python#with_streaming_response
141 """
142 return AsyncSpeechWithStreamingResponse(self)
143
144 async def create(
145 self,
146 *,
147 input: str,
148 model: Union[str, SpeechModel],
149 voice: Union[
150 str, Literal["alloy", "ash", "ballad", "coral", "echo", "sage", "shimmer", "verse", "marin", "cedar"]
151 ],
152 instructions: str | Omit = omit,
153 response_format: Literal["mp3", "opus", "aac", "flac", "wav", "pcm"] | Omit = omit,
154 speed: float | Omit = omit,
155 stream_format: Literal["sse", "audio"] | Omit = omit,
156 # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
157 # The extra values given here take precedence over values defined on the client or passed to this method.
158 extra_headers: Headers | None = None,
159 extra_query: Query | None = None,
160 extra_body: Body | None = None,
161 timeout: float | httpx.Timeout | None | NotGiven = not_given,
162 ) -> _legacy_response.HttpxBinaryResponseContent:
163 """
164 Generates audio from the input text.
165
166 Args:
167 input: The text to generate audio for. The maximum length is 4096 characters.
168
169 model:
170 One of the available [TTS models](https://platform.openai.com/docs/models#tts):
171 `tts-1`, `tts-1-hd` or `gpt-4o-mini-tts`.
172
173 voice: The voice to use when generating the audio. Supported voices are `alloy`, `ash`,
174 `ballad`, `coral`, `echo`, `fable`, `onyx`, `nova`, `sage`, `shimmer`, and
175 `verse`. Previews of the voices are available in the
176 [Text to speech guide](https://platform.openai.com/docs/guides/text-to-speech#voice-options).
177
178 instructions: Control the voice of your generated audio with additional instructions. Does not
179 work with `tts-1` or `tts-1-hd`.
180
181 response_format: The format to audio in. Supported formats are `mp3`, `opus`, `aac`, `flac`,
182 `wav`, and `pcm`.
183
184 speed: The speed of the generated audio. Select a value from `0.25` to `4.0`. `1.0` is
185 the default.
186
187 stream_format: The format to stream the audio in. Supported formats are `sse` and `audio`.
188 `sse` is not supported for `tts-1` or `tts-1-hd`.
189
190 extra_headers: Send extra headers
191
192 extra_query: Add additional query parameters to the request
193
194 extra_body: Add additional JSON properties to the request
195
196 timeout: Override the client-level default timeout for this request, in seconds
197 """
198 extra_headers = {"Accept": "application/octet-stream", **(extra_headers or {})}
199 return await self._post(
200 "/audio/speech",
201 body=await async_maybe_transform(
202 {
203 "input": input,
204 "model": model,
205 "voice": voice,
206 "instructions": instructions,
207 "response_format": response_format,
208 "speed": speed,
209 "stream_format": stream_format,
210 },
211 speech_create_params.SpeechCreateParams,
212 ),
213 options=make_request_options(
214 extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
215 ),
216 cast_to=_legacy_response.HttpxBinaryResponseContent,
217 )
218
219
220class SpeechWithRawResponse:
221 def __init__(self, speech: Speech) -> None:
222 self._speech = speech
223
224 self.create = _legacy_response.to_raw_response_wrapper(
225 speech.create,
226 )
227
228
229class AsyncSpeechWithRawResponse:
230 def __init__(self, speech: AsyncSpeech) -> None:
231 self._speech = speech
232
233 self.create = _legacy_response.async_to_raw_response_wrapper(
234 speech.create,
235 )
236
237
238class SpeechWithStreamingResponse:
239 def __init__(self, speech: Speech) -> None:
240 self._speech = speech
241
242 self.create = to_custom_streamed_response_wrapper(
243 speech.create,
244 StreamedBinaryAPIResponse,
245 )
246
247
248class AsyncSpeechWithStreamingResponse:
249 def __init__(self, speech: AsyncSpeech) -> None:
250 self._speech = speech
251
252 self.create = async_to_custom_streamed_response_wrapper(
253 speech.create,
254 AsyncStreamedBinaryAPIResponse,
255 )