deepgram.clients.speak.v1.rest.client

View Source

  1# Copyright 2024 Deepgram SDK contributors. All Rights Reserved.
  2# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
  3# SPDX-License-Identifier: MIT
  4
  5import logging
  6from typing import Dict, Union, Optional, cast
  7import io
  8
  9import httpx
 10
 11import deprecation  # type: ignore
 12from ..... import __version__
 13
 14from .....utils import verboselogs
 15from .....options import DeepgramClientOptions
 16from ....common import AbstractSyncRestClient
 17from ....common import DeepgramError, DeepgramTypeError
 18from .helpers import is_text_source
 19
 20from .options import SpeakRESTOptions, FileSource
 21from .response import SpeakRESTResponse
 22
 23
 24class SpeakRESTClient(AbstractSyncRestClient):
 25    """
 26    A client class for doing Text-to-Speech.
 27    Provides methods for speaking from text.
 28    """
 29
 30    _logger: verboselogs.VerboseLogger
 31    _config: DeepgramClientOptions
 32
 33    def __init__(self, config: DeepgramClientOptions):
 34        self._logger = verboselogs.VerboseLogger(__name__)
 35        self._logger.addHandler(logging.StreamHandler())
 36        self._logger.setLevel(config.verbose)
 37        self._config = config
 38        super().__init__(config)
 39
 40    # pylint: disable=too-many-positional-arguments
 41
 42    def stream_raw(
 43        self,
 44        source: FileSource,
 45        options: Optional[Union[Dict, SpeakRESTOptions]] = None,
 46        addons: Optional[Dict] = None,
 47        headers: Optional[Dict] = None,
 48        timeout: Optional[httpx.Timeout] = None,
 49        endpoint: str = "v1/speak",
 50        **kwargs,
 51    ) -> httpx.Response:
 52        """
 53        Speak from a text source and store as a Iterator[byte].
 54
 55        Args:
 56            source (TextSource): The text source to speak.
 57            options (SpeakRESTOptions): Additional options for the ingest (default is None).
 58            addons (Dict): Additional options for the request (default is None).
 59            headers (Dict): Additional headers for the request (default is None).
 60            timeout (httpx.Timeout): The timeout for the request (default is None).
 61            endpoint (str): The endpoint to use for the request (default is "v1/speak").
 62
 63        Returns:
 64            httpx.Response: The direct httpx.Response object from the speak request.
 65            For more information, see https://www.python-httpx.org/api/#response
 66
 67            IMPORTANT: The response object's `close()` method should be called when done
 68            in order to prevent connection leaks.
 69
 70        Raises:
 71            DeepgramTypeError: Raised for known API errors.
 72        """
 73        self._logger.debug("SpeakClient.stream ENTER")
 74
 75        url = f"{self._config.url}/{endpoint}"
 76        if is_text_source(source):
 77            body = source
 78        else:
 79            self._logger.error("Unknown speak source type")
 80            self._logger.debug("SpeakClient.stream LEAVE")
 81            raise DeepgramTypeError("Unknown speak source type")
 82
 83        if isinstance(options, SpeakRESTOptions) and not options.check():
 84            self._logger.error("options.check failed")
 85            self._logger.debug("SpeakClient.stream LEAVE")
 86            raise DeepgramError("Fatal speak options error")
 87
 88        self._logger.info("url: %s", url)
 89        self._logger.info("source: %s", source)
 90        if isinstance(options, SpeakRESTOptions):
 91            self._logger.info("SpeakRESTOptions switching class -> dict")
 92            options = options.to_dict()
 93        self._logger.info("options: %s", options)
 94        self._logger.info("addons: %s", addons)
 95        self._logger.info("headers: %s", headers)
 96
 97        result = self.post_raw(
 98            url,
 99            options=options,
100            addons=addons,
101            headers=headers,
102            json=body,
103            timeout=timeout,
104            **kwargs,
105        )
106
107        self._logger.info("result: %s", str(result))
108        self._logger.notice("speak succeeded")
109        self._logger.debug("SpeakClient.stream LEAVE")
110        return result
111
112    def stream_memory(
113        self,
114        source: FileSource,
115        options: Optional[Union[Dict, SpeakRESTOptions]] = None,
116        addons: Optional[Dict] = None,
117        headers: Optional[Dict] = None,
118        timeout: Optional[httpx.Timeout] = None,
119        endpoint: str = "v1/speak",
120        **kwargs,
121    ) -> SpeakRESTResponse:
122        """
123        Speak from a text source and store in memory.
124
125        Args:
126            source (TextSource): The text source to speak.
127            options (SpeakRESTOptions): Additional options for the ingest (default is None).
128            addons (Dict): Additional options for the request (default is None).
129            headers (Dict): Additional headers for the request (default is None).
130            timeout (httpx.Timeout): The timeout for the request (default is None).
131            endpoint (str): The endpoint to use for the request (default is "v1/speak").
132
133        Returns:
134            SpeakRESTResponse: The response from the speak request.
135
136        Raises:
137            DeepgramTypeError: Raised for known API errors.
138        """
139        self._logger.debug("SpeakClient.stream ENTER")
140
141        url = f"{self._config.url}/{endpoint}"
142        if is_text_source(source):
143            body = source
144        else:
145            self._logger.error("Unknown speak source type")
146            self._logger.debug("SpeakClient.stream LEAVE")
147            raise DeepgramTypeError("Unknown speak source type")
148
149        if isinstance(options, SpeakRESTOptions) and not options.check():
150            self._logger.error("options.check failed")
151            self._logger.debug("SpeakClient.stream LEAVE")
152            raise DeepgramError("Fatal speak options error")
153
154        self._logger.info("url: %s", url)
155        self._logger.info("source: %s", source)
156        if isinstance(options, SpeakRESTOptions):
157            self._logger.info("SpeakRESTOptions switching class -> dict")
158            options = options.to_dict()
159        self._logger.info("options: %s", options)
160        self._logger.info("addons: %s", addons)
161        self._logger.info("headers: %s", headers)
162
163        return_vals = [
164            "content-type",
165            "request-id",
166            "model-uuid",
167            "model-name",
168            "char-count",
169            "transfer-encoding",
170            "date",
171        ]
172        result = self.post_memory(
173            url,
174            options=options,
175            addons=addons,
176            headers=headers,
177            json=body,
178            timeout=timeout,
179            file_result=return_vals,
180            **kwargs,
181        )
182
183        self._logger.info("result: %s", result)
184        resp = SpeakRESTResponse(
185            content_type=str(result["content-type"]),
186            request_id=str(result["request-id"]),
187            model_uuid=str(result["model-uuid"]),
188            model_name=str(result["model-name"]),
189            characters=int(str(result["char-count"])),
190            transfer_encoding=str(result["transfer-encoding"]),
191            date=str(result["date"]),
192            stream=cast(io.BytesIO, result["stream"]),
193            stream_memory=cast(io.BytesIO, result["stream"]),
194        )
195        self._logger.verbose("resp Object: %s", resp)
196        self._logger.notice("speak succeeded")
197        self._logger.debug("SpeakClient.stream LEAVE")
198        return resp
199
200    @deprecation.deprecated(
201        deprecated_in="3.4.0",
202        removed_in="4.0.0",
203        current_version=__version__,
204        details="SpeakRESTClient.stream is deprecated. Use SpeakRESTClient.stream_memory instead.",
205    )
206    def stream(
207        self,
208        source: FileSource,
209        options: Optional[Union[Dict, SpeakRESTOptions]] = None,
210        addons: Optional[Dict] = None,
211        headers: Optional[Dict] = None,
212        timeout: Optional[httpx.Timeout] = None,
213        endpoint: str = "v1/speak",
214        **kwargs,
215    ) -> SpeakRESTResponse:
216        """
217        DEPRECATED: stream() is deprecated. Use stream_memory() instead.
218        """
219        return self.stream_memory(
220            source,
221            options=options,
222            addons=addons,
223            headers=headers,
224            timeout=timeout,
225            endpoint=endpoint,
226            **kwargs,
227        )
228
229    async def file(
230        self,
231        filename: str,
232        source: FileSource,
233        options: Optional[Union[Dict, SpeakRESTOptions]] = None,
234        addons: Optional[Dict] = None,
235        timeout: Optional[httpx.Timeout] = None,
236        endpoint: str = "v1/speak",
237        **kwargs,
238    ) -> SpeakRESTResponse:
239        """
240        Speak from a text source and save to a file.
241        """
242        return self.save(
243            filename,
244            source,
245            options=options,
246            addons=addons,
247            timeout=timeout,
248            endpoint=endpoint,
249            **kwargs,
250        )
251
252    def save(
253        self,
254        filename: str,
255        source: FileSource,
256        options: Optional[Union[Dict, SpeakRESTOptions]] = None,
257        addons: Optional[Dict] = None,
258        headers: Optional[Dict] = None,
259        timeout: Optional[httpx.Timeout] = None,
260        endpoint: str = "v1/speak",
261        **kwargs,
262    ) -> SpeakRESTResponse:
263        """
264        Speak from a text source and save to a file.
265
266        Args:
267            source (TextSource): The text source to speak.
268            options (SpeakRESTOptions): Additional options for the ingest (default is None).
269            addons (Dict): Additional options for the request (default is None).
270            headers (Dict): Additional headers for the request (default is None).
271            timeout (httpx.Timeout): The timeout for the request (default is None).
272            endpoint (str): The endpoint to use for the request (default is "v1/speak").
273
274        Returns:
275            SpeakRESTResponse: The response from the speak request.
276
277        Raises:
278            DeepgramTypeError: Raised for known API errors.
279        """
280        self._logger.debug("SpeakClient.save ENTER")
281
282        res = self.stream_memory(
283            source,
284            options=options,
285            addons=addons,
286            headers=headers,
287            timeout=timeout,
288            endpoint=endpoint,
289            **kwargs,
290        )
291
292        if res.stream is None:
293            self._logger.error("stream is None")
294            self._logger.debug("SpeakClient.save LEAVE")
295            raise DeepgramError("BytesIO stream is None")
296
297        # save to file
298        with open(filename, "wb+") as file:
299            file.write(res.stream.getbuffer())
300            file.flush()
301
302        # add filename to response
303        res.stream = None
304        res.filename = filename
305
306        self._logger.debug("SpeakClient.save LEAVE")
307        return res
308
309    # pylint: enable=too-many-positional-arguments

class SpeakRESTClient(deepgram.clients.common.v1.abstract_sync_rest.AbstractSyncRestClient): View Source

 25class SpeakRESTClient(AbstractSyncRestClient):
 26    """
 27    A client class for doing Text-to-Speech.
 28    Provides methods for speaking from text.
 29    """
 30
 31    _logger: verboselogs.VerboseLogger
 32    _config: DeepgramClientOptions
 33
 34    def __init__(self, config: DeepgramClientOptions):
 35        self._logger = verboselogs.VerboseLogger(__name__)
 36        self._logger.addHandler(logging.StreamHandler())
 37        self._logger.setLevel(config.verbose)
 38        self._config = config
 39        super().__init__(config)
 40
 41    # pylint: disable=too-many-positional-arguments
 42
 43    def stream_raw(
 44        self,
 45        source: FileSource,
 46        options: Optional[Union[Dict, SpeakRESTOptions]] = None,
 47        addons: Optional[Dict] = None,
 48        headers: Optional[Dict] = None,
 49        timeout: Optional[httpx.Timeout] = None,
 50        endpoint: str = "v1/speak",
 51        **kwargs,
 52    ) -> httpx.Response:
 53        """
 54        Speak from a text source and store as a Iterator[byte].
 55
 56        Args:
 57            source (TextSource): The text source to speak.
 58            options (SpeakRESTOptions): Additional options for the ingest (default is None).
 59            addons (Dict): Additional options for the request (default is None).
 60            headers (Dict): Additional headers for the request (default is None).
 61            timeout (httpx.Timeout): The timeout for the request (default is None).
 62            endpoint (str): The endpoint to use for the request (default is "v1/speak").
 63
 64        Returns:
 65            httpx.Response: The direct httpx.Response object from the speak request.
 66            For more information, see https://www.python-httpx.org/api/#response
 67
 68            IMPORTANT: The response object's `close()` method should be called when done
 69            in order to prevent connection leaks.
 70
 71        Raises:
 72            DeepgramTypeError: Raised for known API errors.
 73        """
 74        self._logger.debug("SpeakClient.stream ENTER")
 75
 76        url = f"{self._config.url}/{endpoint}"
 77        if is_text_source(source):
 78            body = source
 79        else:
 80            self._logger.error("Unknown speak source type")
 81            self._logger.debug("SpeakClient.stream LEAVE")
 82            raise DeepgramTypeError("Unknown speak source type")
 83
 84        if isinstance(options, SpeakRESTOptions) and not options.check():
 85            self._logger.error("options.check failed")
 86            self._logger.debug("SpeakClient.stream LEAVE")
 87            raise DeepgramError("Fatal speak options error")
 88
 89        self._logger.info("url: %s", url)
 90        self._logger.info("source: %s", source)
 91        if isinstance(options, SpeakRESTOptions):
 92            self._logger.info("SpeakRESTOptions switching class -> dict")
 93            options = options.to_dict()
 94        self._logger.info("options: %s", options)
 95        self._logger.info("addons: %s", addons)
 96        self._logger.info("headers: %s", headers)
 97
 98        result = self.post_raw(
 99            url,
100            options=options,
101            addons=addons,
102            headers=headers,
103            json=body,
104            timeout=timeout,
105            **kwargs,
106        )
107
108        self._logger.info("result: %s", str(result))
109        self._logger.notice("speak succeeded")
110        self._logger.debug("SpeakClient.stream LEAVE")
111        return result
112
113    def stream_memory(
114        self,
115        source: FileSource,
116        options: Optional[Union[Dict, SpeakRESTOptions]] = None,
117        addons: Optional[Dict] = None,
118        headers: Optional[Dict] = None,
119        timeout: Optional[httpx.Timeout] = None,
120        endpoint: str = "v1/speak",
121        **kwargs,
122    ) -> SpeakRESTResponse:
123        """
124        Speak from a text source and store in memory.
125
126        Args:
127            source (TextSource): The text source to speak.
128            options (SpeakRESTOptions): Additional options for the ingest (default is None).
129            addons (Dict): Additional options for the request (default is None).
130            headers (Dict): Additional headers for the request (default is None).
131            timeout (httpx.Timeout): The timeout for the request (default is None).
132            endpoint (str): The endpoint to use for the request (default is "v1/speak").
133
134        Returns:
135            SpeakRESTResponse: The response from the speak request.
136
137        Raises:
138            DeepgramTypeError: Raised for known API errors.
139        """
140        self._logger.debug("SpeakClient.stream ENTER")
141
142        url = f"{self._config.url}/{endpoint}"
143        if is_text_source(source):
144            body = source
145        else:
146            self._logger.error("Unknown speak source type")
147            self._logger.debug("SpeakClient.stream LEAVE")
148            raise DeepgramTypeError("Unknown speak source type")
149
150        if isinstance(options, SpeakRESTOptions) and not options.check():
151            self._logger.error("options.check failed")
152            self._logger.debug("SpeakClient.stream LEAVE")
153            raise DeepgramError("Fatal speak options error")
154
155        self._logger.info("url: %s", url)
156        self._logger.info("source: %s", source)
157        if isinstance(options, SpeakRESTOptions):
158            self._logger.info("SpeakRESTOptions switching class -> dict")
159            options = options.to_dict()
160        self._logger.info("options: %s", options)
161        self._logger.info("addons: %s", addons)
162        self._logger.info("headers: %s", headers)
163
164        return_vals = [
165            "content-type",
166            "request-id",
167            "model-uuid",
168            "model-name",
169            "char-count",
170            "transfer-encoding",
171            "date",
172        ]
173        result = self.post_memory(
174            url,
175            options=options,
176            addons=addons,
177            headers=headers,
178            json=body,
179            timeout=timeout,
180            file_result=return_vals,
181            **kwargs,
182        )
183
184        self._logger.info("result: %s", result)
185        resp = SpeakRESTResponse(
186            content_type=str(result["content-type"]),
187            request_id=str(result["request-id"]),
188            model_uuid=str(result["model-uuid"]),
189            model_name=str(result["model-name"]),
190            characters=int(str(result["char-count"])),
191            transfer_encoding=str(result["transfer-encoding"]),
192            date=str(result["date"]),
193            stream=cast(io.BytesIO, result["stream"]),
194            stream_memory=cast(io.BytesIO, result["stream"]),
195        )
196        self._logger.verbose("resp Object: %s", resp)
197        self._logger.notice("speak succeeded")
198        self._logger.debug("SpeakClient.stream LEAVE")
199        return resp
200
201    @deprecation.deprecated(
202        deprecated_in="3.4.0",
203        removed_in="4.0.0",
204        current_version=__version__,
205        details="SpeakRESTClient.stream is deprecated. Use SpeakRESTClient.stream_memory instead.",
206    )
207    def stream(
208        self,
209        source: FileSource,
210        options: Optional[Union[Dict, SpeakRESTOptions]] = None,
211        addons: Optional[Dict] = None,
212        headers: Optional[Dict] = None,
213        timeout: Optional[httpx.Timeout] = None,
214        endpoint: str = "v1/speak",
215        **kwargs,
216    ) -> SpeakRESTResponse:
217        """
218        DEPRECATED: stream() is deprecated. Use stream_memory() instead.
219        """
220        return self.stream_memory(
221            source,
222            options=options,
223            addons=addons,
224            headers=headers,
225            timeout=timeout,
226            endpoint=endpoint,
227            **kwargs,
228        )
229
230    async def file(
231        self,
232        filename: str,
233        source: FileSource,
234        options: Optional[Union[Dict, SpeakRESTOptions]] = None,
235        addons: Optional[Dict] = None,
236        timeout: Optional[httpx.Timeout] = None,
237        endpoint: str = "v1/speak",
238        **kwargs,
239    ) -> SpeakRESTResponse:
240        """
241        Speak from a text source and save to a file.
242        """
243        return self.save(
244            filename,
245            source,
246            options=options,
247            addons=addons,
248            timeout=timeout,
249            endpoint=endpoint,
250            **kwargs,
251        )
252
253    def save(
254        self,
255        filename: str,
256        source: FileSource,
257        options: Optional[Union[Dict, SpeakRESTOptions]] = None,
258        addons: Optional[Dict] = None,
259        headers: Optional[Dict] = None,
260        timeout: Optional[httpx.Timeout] = None,
261        endpoint: str = "v1/speak",
262        **kwargs,
263    ) -> SpeakRESTResponse:
264        """
265        Speak from a text source and save to a file.
266
267        Args:
268            source (TextSource): The text source to speak.
269            options (SpeakRESTOptions): Additional options for the ingest (default is None).
270            addons (Dict): Additional options for the request (default is None).
271            headers (Dict): Additional headers for the request (default is None).
272            timeout (httpx.Timeout): The timeout for the request (default is None).
273            endpoint (str): The endpoint to use for the request (default is "v1/speak").
274
275        Returns:
276            SpeakRESTResponse: The response from the speak request.
277
278        Raises:
279            DeepgramTypeError: Raised for known API errors.
280        """
281        self._logger.debug("SpeakClient.save ENTER")
282
283        res = self.stream_memory(
284            source,
285            options=options,
286            addons=addons,
287            headers=headers,
288            timeout=timeout,
289            endpoint=endpoint,
290            **kwargs,
291        )
292
293        if res.stream is None:
294            self._logger.error("stream is None")
295            self._logger.debug("SpeakClient.save LEAVE")
296            raise DeepgramError("BytesIO stream is None")
297
298        # save to file
299        with open(filename, "wb+") as file:
300            file.write(res.stream.getbuffer())
301            file.flush()
302
303        # add filename to response
304        res.stream = None
305        res.filename = filename
306
307        self._logger.debug("SpeakClient.save LEAVE")
308        return res
309
310    # pylint: enable=too-many-positional-arguments

A client class for doing Text-to-Speech. Provides methods for speaking from text.

SpeakRESTClient(config: deepgram.options.DeepgramClientOptions) View Source

34    def __init__(self, config: DeepgramClientOptions):
35        self._logger = verboselogs.VerboseLogger(__name__)
36        self._logger.addHandler(logging.StreamHandler())
37        self._logger.setLevel(config.verbose)
38        self._config = config
39        super().__init__(config)

def stream_raw( self, source: Union[deepgram.clients.common.TextSource, deepgram.clients.common.BufferSource, deepgram.clients.common.StreamSource], options: Union[Dict, deepgram.clients.speak.v1.rest.options.SpeakRESTOptions, NoneType] = None, addons: Optional[Dict] = None, headers: Optional[Dict] = None, timeout: Optional[httpx.Timeout] = None, endpoint: str = 'v1/speak', **kwargs) -> httpx.Response: View Source

 43    def stream_raw(
 44        self,
 45        source: FileSource,
 46        options: Optional[Union[Dict, SpeakRESTOptions]] = None,
 47        addons: Optional[Dict] = None,
 48        headers: Optional[Dict] = None,
 49        timeout: Optional[httpx.Timeout] = None,
 50        endpoint: str = "v1/speak",
 51        **kwargs,
 52    ) -> httpx.Response:
 53        """
 54        Speak from a text source and store as a Iterator[byte].
 55
 56        Args:
 57            source (TextSource): The text source to speak.
 58            options (SpeakRESTOptions): Additional options for the ingest (default is None).
 59            addons (Dict): Additional options for the request (default is None).
 60            headers (Dict): Additional headers for the request (default is None).
 61            timeout (httpx.Timeout): The timeout for the request (default is None).
 62            endpoint (str): The endpoint to use for the request (default is "v1/speak").
 63
 64        Returns:
 65            httpx.Response: The direct httpx.Response object from the speak request.
 66            For more information, see https://www.python-httpx.org/api/#response
 67
 68            IMPORTANT: The response object's `close()` method should be called when done
 69            in order to prevent connection leaks.
 70
 71        Raises:
 72            DeepgramTypeError: Raised for known API errors.
 73        """
 74        self._logger.debug("SpeakClient.stream ENTER")
 75
 76        url = f"{self._config.url}/{endpoint}"
 77        if is_text_source(source):
 78            body = source
 79        else:
 80            self._logger.error("Unknown speak source type")
 81            self._logger.debug("SpeakClient.stream LEAVE")
 82            raise DeepgramTypeError("Unknown speak source type")
 83
 84        if isinstance(options, SpeakRESTOptions) and not options.check():
 85            self._logger.error("options.check failed")
 86            self._logger.debug("SpeakClient.stream LEAVE")
 87            raise DeepgramError("Fatal speak options error")
 88
 89        self._logger.info("url: %s", url)
 90        self._logger.info("source: %s", source)
 91        if isinstance(options, SpeakRESTOptions):
 92            self._logger.info("SpeakRESTOptions switching class -> dict")
 93            options = options.to_dict()
 94        self._logger.info("options: %s", options)
 95        self._logger.info("addons: %s", addons)
 96        self._logger.info("headers: %s", headers)
 97
 98        result = self.post_raw(
 99            url,
100            options=options,
101            addons=addons,
102            headers=headers,
103            json=body,
104            timeout=timeout,
105            **kwargs,
106        )
107
108        self._logger.info("result: %s", str(result))
109        self._logger.notice("speak succeeded")
110        self._logger.debug("SpeakClient.stream LEAVE")
111        return result

Speak from a text source and store as a Iterator[byte].

Args: source (TextSource): The text source to speak. options (SpeakRESTOptions): Additional options for the ingest (default is None). addons (Dict): Additional options for the request (default is None). headers (Dict): Additional headers for the request (default is None). timeout (httpx.Timeout): The timeout for the request (default is None). endpoint (str): The endpoint to use for the request (default is "v1/speak").

Returns: httpx.Response: The direct httpx.Response object from the speak request. For more information, see https://www.python-httpx.org/api/#response

IMPORTANT: The response object's `close()` method should be called when done
in order to prevent connection leaks.

Raises: DeepgramTypeError: Raised for known API errors.

def stream_memory( self, source: Union[deepgram.clients.common.TextSource, deepgram.clients.common.BufferSource, deepgram.clients.common.StreamSource], options: Union[Dict, deepgram.clients.speak.v1.rest.options.SpeakRESTOptions, NoneType] = None, addons: Optional[Dict] = None, headers: Optional[Dict] = None, timeout: Optional[httpx.Timeout] = None, endpoint: str = 'v1/speak', **kwargs) -> deepgram.clients.speak.v1.rest.response.SpeakRESTResponse: View Source

113    def stream_memory(
114        self,
115        source: FileSource,
116        options: Optional[Union[Dict, SpeakRESTOptions]] = None,
117        addons: Optional[Dict] = None,
118        headers: Optional[Dict] = None,
119        timeout: Optional[httpx.Timeout] = None,
120        endpoint: str = "v1/speak",
121        **kwargs,
122    ) -> SpeakRESTResponse:
123        """
124        Speak from a text source and store in memory.
125
126        Args:
127            source (TextSource): The text source to speak.
128            options (SpeakRESTOptions): Additional options for the ingest (default is None).
129            addons (Dict): Additional options for the request (default is None).
130            headers (Dict): Additional headers for the request (default is None).
131            timeout (httpx.Timeout): The timeout for the request (default is None).
132            endpoint (str): The endpoint to use for the request (default is "v1/speak").
133
134        Returns:
135            SpeakRESTResponse: The response from the speak request.
136
137        Raises:
138            DeepgramTypeError: Raised for known API errors.
139        """
140        self._logger.debug("SpeakClient.stream ENTER")
141
142        url = f"{self._config.url}/{endpoint}"
143        if is_text_source(source):
144            body = source
145        else:
146            self._logger.error("Unknown speak source type")
147            self._logger.debug("SpeakClient.stream LEAVE")
148            raise DeepgramTypeError("Unknown speak source type")
149
150        if isinstance(options, SpeakRESTOptions) and not options.check():
151            self._logger.error("options.check failed")
152            self._logger.debug("SpeakClient.stream LEAVE")
153            raise DeepgramError("Fatal speak options error")
154
155        self._logger.info("url: %s", url)
156        self._logger.info("source: %s", source)
157        if isinstance(options, SpeakRESTOptions):
158            self._logger.info("SpeakRESTOptions switching class -> dict")
159            options = options.to_dict()
160        self._logger.info("options: %s", options)
161        self._logger.info("addons: %s", addons)
162        self._logger.info("headers: %s", headers)
163
164        return_vals = [
165            "content-type",
166            "request-id",
167            "model-uuid",
168            "model-name",
169            "char-count",
170            "transfer-encoding",
171            "date",
172        ]
173        result = self.post_memory(
174            url,
175            options=options,
176            addons=addons,
177            headers=headers,
178            json=body,
179            timeout=timeout,
180            file_result=return_vals,
181            **kwargs,
182        )
183
184        self._logger.info("result: %s", result)
185        resp = SpeakRESTResponse(
186            content_type=str(result["content-type"]),
187            request_id=str(result["request-id"]),
188            model_uuid=str(result["model-uuid"]),
189            model_name=str(result["model-name"]),
190            characters=int(str(result["char-count"])),
191            transfer_encoding=str(result["transfer-encoding"]),
192            date=str(result["date"]),
193            stream=cast(io.BytesIO, result["stream"]),
194            stream_memory=cast(io.BytesIO, result["stream"]),
195        )
196        self._logger.verbose("resp Object: %s", resp)
197        self._logger.notice("speak succeeded")
198        self._logger.debug("SpeakClient.stream LEAVE")
199        return resp

Speak from a text source and store in memory.

Returns: SpeakRESTResponse: The response from the speak request.

Raises: DeepgramTypeError: Raised for known API errors.

@deprecation.deprecated(deprecated_in='3.4.0', removed_in='4.0.0', current_version=__version__, details='SpeakRESTClient.stream is deprecated. Use SpeakRESTClient.stream_memory instead.')

def stream( self, source: Union[deepgram.clients.common.TextSource, deepgram.clients.common.BufferSource, deepgram.clients.common.StreamSource], options: Union[Dict, deepgram.clients.speak.v1.rest.options.SpeakRESTOptions, NoneType] = None, addons: Optional[Dict] = None, headers: Optional[Dict] = None, timeout: Optional[httpx.Timeout] = None, endpoint: str = 'v1/speak', **kwargs) -> deepgram.clients.speak.v1.rest.response.SpeakRESTResponse: View Source

201    @deprecation.deprecated(
202        deprecated_in="3.4.0",
203        removed_in="4.0.0",
204        current_version=__version__,
205        details="SpeakRESTClient.stream is deprecated. Use SpeakRESTClient.stream_memory instead.",
206    )
207    def stream(
208        self,
209        source: FileSource,
210        options: Optional[Union[Dict, SpeakRESTOptions]] = None,
211        addons: Optional[Dict] = None,
212        headers: Optional[Dict] = None,
213        timeout: Optional[httpx.Timeout] = None,
214        endpoint: str = "v1/speak",
215        **kwargs,
216    ) -> SpeakRESTResponse:
217        """
218        DEPRECATED: stream() is deprecated. Use stream_memory() instead.
219        """
220        return self.stream_memory(
221            source,
222            options=options,
223            addons=addons,
224            headers=headers,
225            timeout=timeout,
226            endpoint=endpoint,
227            **kwargs,
228        )

DEPRECATED: stream() is deprecated. Use stream_memory() instead.

async def file( self, filename: str, source: Union[deepgram.clients.common.TextSource, deepgram.clients.common.BufferSource, deepgram.clients.common.StreamSource], options: Union[Dict, deepgram.clients.speak.v1.rest.options.SpeakRESTOptions, NoneType] = None, addons: Optional[Dict] = None, timeout: Optional[httpx.Timeout] = None, endpoint: str = 'v1/speak', **kwargs) -> deepgram.clients.speak.v1.rest.response.SpeakRESTResponse: View Source

230    async def file(
231        self,
232        filename: str,
233        source: FileSource,
234        options: Optional[Union[Dict, SpeakRESTOptions]] = None,
235        addons: Optional[Dict] = None,
236        timeout: Optional[httpx.Timeout] = None,
237        endpoint: str = "v1/speak",
238        **kwargs,
239    ) -> SpeakRESTResponse:
240        """
241        Speak from a text source and save to a file.
242        """
243        return self.save(
244            filename,
245            source,
246            options=options,
247            addons=addons,
248            timeout=timeout,
249            endpoint=endpoint,
250            **kwargs,
251        )

Speak from a text source and save to a file.

def save( self, filename: str, source: Union[deepgram.clients.common.TextSource, deepgram.clients.common.BufferSource, deepgram.clients.common.StreamSource], options: Union[Dict, deepgram.clients.speak.v1.rest.options.SpeakRESTOptions, NoneType] = None, addons: Optional[Dict] = None, headers: Optional[Dict] = None, timeout: Optional[httpx.Timeout] = None, endpoint: str = 'v1/speak', **kwargs) -> deepgram.clients.speak.v1.rest.response.SpeakRESTResponse: View Source

253    def save(
254        self,
255        filename: str,
256        source: FileSource,
257        options: Optional[Union[Dict, SpeakRESTOptions]] = None,
258        addons: Optional[Dict] = None,
259        headers: Optional[Dict] = None,
260        timeout: Optional[httpx.Timeout] = None,
261        endpoint: str = "v1/speak",
262        **kwargs,
263    ) -> SpeakRESTResponse:
264        """
265        Speak from a text source and save to a file.
266
267        Args:
268            source (TextSource): The text source to speak.
269            options (SpeakRESTOptions): Additional options for the ingest (default is None).
270            addons (Dict): Additional options for the request (default is None).
271            headers (Dict): Additional headers for the request (default is None).
272            timeout (httpx.Timeout): The timeout for the request (default is None).
273            endpoint (str): The endpoint to use for the request (default is "v1/speak").
274
275        Returns:
276            SpeakRESTResponse: The response from the speak request.
277
278        Raises:
279            DeepgramTypeError: Raised for known API errors.
280        """
281        self._logger.debug("SpeakClient.save ENTER")
282
283        res = self.stream_memory(
284            source,
285            options=options,
286            addons=addons,
287            headers=headers,
288            timeout=timeout,
289            endpoint=endpoint,
290            **kwargs,
291        )
292
293        if res.stream is None:
294            self._logger.error("stream is None")
295            self._logger.debug("SpeakClient.save LEAVE")
296            raise DeepgramError("BytesIO stream is None")
297
298        # save to file
299        with open(filename, "wb+") as file:
300            file.write(res.stream.getbuffer())
301            file.flush()
302
303        # add filename to response
304        res.stream = None
305        res.filename = filename
306
307        self._logger.debug("SpeakClient.save LEAVE")
308        return res

Speak from a text source and save to a file.

Returns: SpeakRESTResponse: The response from the speak request.

Raises: DeepgramTypeError: Raised for known API errors.

Inherited Members

deepgram.clients.common.v1.abstract_sync_rest.AbstractSyncRestClient: get; post_raw; post_memory; post; put; patch; delete