cartesia 2.0.4__py3-none-any.whl → 2.0.6__py3-none-any.whl

cartesia/stt/client.py

@@ -0,0 +1,456 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+from ..core.client_wrapper import SyncClientWrapper
+from .. import core
+from .types.stt_encoding import SttEncoding
+from .types.timestamp_granularity import TimestampGranularity
+from ..core.request_options import RequestOptions
+from .types.transcription_response import TranscriptionResponse
+from ..core.pydantic_utilities import parse_obj_as
+from json.decoder import JSONDecodeError
+from ..core.api_error import ApiError
+from ..core.client_wrapper import AsyncClientWrapper
+
+# this is used as the default value for optional parameters
+OMIT = typing.cast(typing.Any, ...)
+
+
+class SttClient:
+    def __init__(self, *, client_wrapper: SyncClientWrapper):
+        self._client_wrapper = client_wrapper
+
+    def transcribe(
+        self,
+        *,
+        file: core.File,
+        model: str,
+        encoding: typing.Optional[SttEncoding] = None,
+        sample_rate: typing.Optional[int] = None,
+        language: typing.Optional[str] = OMIT,
+        timestamp_granularities: typing.Optional[typing.List[TimestampGranularity]] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> TranscriptionResponse:
+        """
+        Transcribes audio files into text using Cartesia's Speech-to-Text API.
+
+        Upload an audio file and receive a complete transcription response. Supports arbitrarily long audio files with automatic intelligent chunking for longer audio.
+
+        **Supported audio formats:** flac, m4a, mp3, mp4, mpeg, mpga, oga, ogg, wav, webm
+
+        **Response format:** Returns JSON with transcribed text, duration, and language. Include `timestamp_granularities: ["word"]` to get word-level timestamps.
+
+        **Pricing:** Batch transcription is priced at **1 credit per 2 seconds** of audio processed.
+
+        <Note>
+        For migrating from the OpenAI SDK, see our [OpenAI Whisper to Cartesia Ink Migration Guide](/api-reference/stt/migrate-from-open-ai).
+        </Note>
+
+        Parameters
+        ----------
+        file : core.File
+            See core.File for more documentation
+
+        model : str
+            ID of the model to use for transcription. Use `ink-whisper` for the latest Cartesia Whisper model.
+
+
+        encoding : typing.Optional[SttEncoding]
+            The encoding format to process the audio as. If not specified, the audio file will be decoded automatically.
+
+            **Supported formats:**
+            - `pcm_s16le` - 16-bit signed integer PCM, little-endian (recommended for best performance)
+            - `pcm_s32le` - 32-bit signed integer PCM, little-endian
+            - `pcm_f16le` - 16-bit floating point PCM, little-endian
+            - `pcm_f32le` - 32-bit floating point PCM, little-endian
+            - `pcm_mulaw` - 8-bit μ-law encoded PCM
+            - `pcm_alaw` - 8-bit A-law encoded PCM
+
+        sample_rate : typing.Optional[int]
+            The sample rate of the audio in Hz.
+
+        language : typing.Optional[str]
+            The language of the input audio in ISO-639-1 format. Defaults to `en`.
+
+            <Accordion title="Supported languages">
+              - `en` (English)
+              - `zh` (Chinese)
+              - `de` (German)
+              - `es` (Spanish)
+              - `ru` (Russian)
+              - `ko` (Korean)
+              - `fr` (French)
+              - `ja` (Japanese)
+              - `pt` (Portuguese)
+              - `tr` (Turkish)
+              - `pl` (Polish)
+              - `ca` (Catalan)
+              - `nl` (Dutch)
+              - `ar` (Arabic)
+              - `sv` (Swedish)
+              - `it` (Italian)
+              - `id` (Indonesian)
+              - `hi` (Hindi)
+              - `fi` (Finnish)
+              - `vi` (Vietnamese)
+              - `he` (Hebrew)
+              - `uk` (Ukrainian)
+              - `el` (Greek)
+              - `ms` (Malay)
+              - `cs` (Czech)
+              - `ro` (Romanian)
+              - `da` (Danish)
+              - `hu` (Hungarian)
+              - `ta` (Tamil)
+              - `no` (Norwegian)
+              - `th` (Thai)
+              - `ur` (Urdu)
+              - `hr` (Croatian)
+              - `bg` (Bulgarian)
+              - `lt` (Lithuanian)
+              - `la` (Latin)
+              - `mi` (Maori)
+              - `ml` (Malayalam)
+              - `cy` (Welsh)
+              - `sk` (Slovak)
+              - `te` (Telugu)
+              - `fa` (Persian)
+              - `lv` (Latvian)
+              - `bn` (Bengali)
+              - `sr` (Serbian)
+              - `az` (Azerbaijani)
+              - `sl` (Slovenian)
+              - `kn` (Kannada)
+              - `et` (Estonian)
+              - `mk` (Macedonian)
+              - `br` (Breton)
+              - `eu` (Basque)
+              - `is` (Icelandic)
+              - `hy` (Armenian)
+              - `ne` (Nepali)
+              - `mn` (Mongolian)
+              - `bs` (Bosnian)
+              - `kk` (Kazakh)
+              - `sq` (Albanian)
+              - `sw` (Swahili)
+              - `gl` (Galician)
+              - `mr` (Marathi)
+              - `pa` (Punjabi)
+              - `si` (Sinhala)
+              - `km` (Khmer)
+              - `sn` (Shona)
+              - `yo` (Yoruba)
+              - `so` (Somali)
+              - `af` (Afrikaans)
+              - `oc` (Occitan)
+              - `ka` (Georgian)
+              - `be` (Belarusian)
+              - `tg` (Tajik)
+              - `sd` (Sindhi)
+              - `gu` (Gujarati)
+              - `am` (Amharic)
+              - `yi` (Yiddish)
+              - `lo` (Lao)
+              - `uz` (Uzbek)
+              - `fo` (Faroese)
+              - `ht` (Haitian Creole)
+              - `ps` (Pashto)
+              - `tk` (Turkmen)
+              - `nn` (Nynorsk)
+              - `mt` (Maltese)
+              - `sa` (Sanskrit)
+              - `lb` (Luxembourgish)
+              - `my` (Myanmar)
+              - `bo` (Tibetan)
+              - `tl` (Tagalog)
+              - `mg` (Malagasy)
+              - `as` (Assamese)
+              - `tt` (Tatar)
+              - `haw` (Hawaiian)
+              - `ln` (Lingala)
+              - `ha` (Hausa)
+              - `ba` (Bashkir)
+              - `jw` (Javanese)
+              - `su` (Sundanese)
+              - `yue` (Cantonese)
+            </Accordion>
+
+
+        timestamp_granularities : typing.Optional[typing.List[TimestampGranularity]]
+            The timestamp granularities to populate for this transcription. Currently only `word` level timestamps are supported.
+
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        TranscriptionResponse
+
+        Examples
+        --------
+        from cartesia import Cartesia
+
+        client = Cartesia(
+            api_key="YOUR_API_KEY",
+        )
+        client.stt.transcribe(
+            model="ink-whisper",
+            language="en",
+        )
+        """
+        _response = self._client_wrapper.httpx_client.request(
+            "stt",
+            method="POST",
+            params={
+                "encoding": encoding,
+                "sample_rate": sample_rate,
+            },
+            data={
+                "model": model,
+                "language": language,
+                "timestamp_granularities[]": timestamp_granularities,
+            },
+            files={
+                "file": file,
+            },
+            request_options=request_options,
+            omit=OMIT,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                return typing.cast(
+                    TranscriptionResponse,
+                    parse_obj_as(
+                        type_=TranscriptionResponse,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, body=_response.text)
+        raise ApiError(status_code=_response.status_code, body=_response_json)
+
+
+class AsyncSttClient:
+    def __init__(self, *, client_wrapper: AsyncClientWrapper):
+        self._client_wrapper = client_wrapper
+
+    async def transcribe(
+        self,
+        *,
+        file: core.File,
+        model: str,
+        encoding: typing.Optional[SttEncoding] = None,
+        sample_rate: typing.Optional[int] = None,
+        language: typing.Optional[str] = OMIT,
+        timestamp_granularities: typing.Optional[typing.List[TimestampGranularity]] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> TranscriptionResponse:
+        """
+        Transcribes audio files into text using Cartesia's Speech-to-Text API.
+
+        Upload an audio file and receive a complete transcription response. Supports arbitrarily long audio files with automatic intelligent chunking for longer audio.
+
+        **Supported audio formats:** flac, m4a, mp3, mp4, mpeg, mpga, oga, ogg, wav, webm
+
+        **Response format:** Returns JSON with transcribed text, duration, and language. Include `timestamp_granularities: ["word"]` to get word-level timestamps.
+
+        **Pricing:** Batch transcription is priced at **1 credit per 2 seconds** of audio processed.
+
+        <Note>
+        For migrating from the OpenAI SDK, see our [OpenAI Whisper to Cartesia Ink Migration Guide](/api-reference/stt/migrate-from-open-ai).
+        </Note>
+
+        Parameters
+        ----------
+        file : core.File
+            See core.File for more documentation
+
+        model : str
+            ID of the model to use for transcription. Use `ink-whisper` for the latest Cartesia Whisper model.
+
+
+        encoding : typing.Optional[SttEncoding]
+            The encoding format to process the audio as. If not specified, the audio file will be decoded automatically.
+
+            **Supported formats:**
+            - `pcm_s16le` - 16-bit signed integer PCM, little-endian (recommended for best performance)
+            - `pcm_s32le` - 32-bit signed integer PCM, little-endian
+            - `pcm_f16le` - 16-bit floating point PCM, little-endian
+            - `pcm_f32le` - 32-bit floating point PCM, little-endian
+            - `pcm_mulaw` - 8-bit μ-law encoded PCM
+            - `pcm_alaw` - 8-bit A-law encoded PCM
+
+        sample_rate : typing.Optional[int]
+            The sample rate of the audio in Hz.
+
+        language : typing.Optional[str]
+            The language of the input audio in ISO-639-1 format. Defaults to `en`.
+
+            <Accordion title="Supported languages">
+              - `en` (English)
+              - `zh` (Chinese)
+              - `de` (German)
+              - `es` (Spanish)
+              - `ru` (Russian)
+              - `ko` (Korean)
+              - `fr` (French)
+              - `ja` (Japanese)
+              - `pt` (Portuguese)
+              - `tr` (Turkish)
+              - `pl` (Polish)
+              - `ca` (Catalan)
+              - `nl` (Dutch)
+              - `ar` (Arabic)
+              - `sv` (Swedish)
+              - `it` (Italian)
+              - `id` (Indonesian)
+              - `hi` (Hindi)
+              - `fi` (Finnish)
+              - `vi` (Vietnamese)
+              - `he` (Hebrew)
+              - `uk` (Ukrainian)
+              - `el` (Greek)
+              - `ms` (Malay)
+              - `cs` (Czech)
+              - `ro` (Romanian)
+              - `da` (Danish)
+              - `hu` (Hungarian)
+              - `ta` (Tamil)
+              - `no` (Norwegian)
+              - `th` (Thai)
+              - `ur` (Urdu)
+              - `hr` (Croatian)
+              - `bg` (Bulgarian)
+              - `lt` (Lithuanian)
+              - `la` (Latin)
+              - `mi` (Maori)
+              - `ml` (Malayalam)
+              - `cy` (Welsh)
+              - `sk` (Slovak)
+              - `te` (Telugu)
+              - `fa` (Persian)
+              - `lv` (Latvian)
+              - `bn` (Bengali)
+              - `sr` (Serbian)
+              - `az` (Azerbaijani)
+              - `sl` (Slovenian)
+              - `kn` (Kannada)
+              - `et` (Estonian)
+              - `mk` (Macedonian)
+              - `br` (Breton)
+              - `eu` (Basque)
+              - `is` (Icelandic)
+              - `hy` (Armenian)
+              - `ne` (Nepali)
+              - `mn` (Mongolian)
+              - `bs` (Bosnian)
+              - `kk` (Kazakh)
+              - `sq` (Albanian)
+              - `sw` (Swahili)
+              - `gl` (Galician)
+              - `mr` (Marathi)
+              - `pa` (Punjabi)
+              - `si` (Sinhala)
+              - `km` (Khmer)
+              - `sn` (Shona)
+              - `yo` (Yoruba)
+              - `so` (Somali)
+              - `af` (Afrikaans)
+              - `oc` (Occitan)
+              - `ka` (Georgian)
+              - `be` (Belarusian)
+              - `tg` (Tajik)
+              - `sd` (Sindhi)
+              - `gu` (Gujarati)
+              - `am` (Amharic)
+              - `yi` (Yiddish)
+              - `lo` (Lao)
+              - `uz` (Uzbek)
+              - `fo` (Faroese)
+              - `ht` (Haitian Creole)
+              - `ps` (Pashto)
+              - `tk` (Turkmen)
+              - `nn` (Nynorsk)
+              - `mt` (Maltese)
+              - `sa` (Sanskrit)
+              - `lb` (Luxembourgish)
+              - `my` (Myanmar)
+              - `bo` (Tibetan)
+              - `tl` (Tagalog)
+              - `mg` (Malagasy)
+              - `as` (Assamese)
+              - `tt` (Tatar)
+              - `haw` (Hawaiian)
+              - `ln` (Lingala)
+              - `ha` (Hausa)
+              - `ba` (Bashkir)
+              - `jw` (Javanese)
+              - `su` (Sundanese)
+              - `yue` (Cantonese)
+            </Accordion>
+
+
+        timestamp_granularities : typing.Optional[typing.List[TimestampGranularity]]
+            The timestamp granularities to populate for this transcription. Currently only `word` level timestamps are supported.
+
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        TranscriptionResponse
+
+        Examples
+        --------
+        import asyncio
+
+        from cartesia import AsyncCartesia
+
+        client = AsyncCartesia(
+            api_key="YOUR_API_KEY",
+        )
+
+
+        async def main() -> None:
+            await client.stt.transcribe(
+                model="ink-whisper",
+                language="en",
+            )
+
+
+        asyncio.run(main())
+        """
+        _response = await self._client_wrapper.httpx_client.request(
+            "stt",
+            method="POST",
+            params={
+                "encoding": encoding,
+                "sample_rate": sample_rate,
+            },
+            data={
+                "model": model,
+                "language": language,
+                "timestamp_granularities[]": timestamp_granularities,
+            },
+            files={
+                "file": file,
+            },
+            request_options=request_options,
+            omit=OMIT,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                return typing.cast(
+                    TranscriptionResponse,
+                    parse_obj_as(
+                        type_=TranscriptionResponse,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, body=_response.text)
+        raise ApiError(status_code=_response.status_code, body=_response_json)

cartesia/stt/requests/__init__.py

@@ -0,0 +1,29 @@
+# This file was auto-generated by Fern from our API Definition.
+
+from .done_message import DoneMessageParams
+from .error_message import ErrorMessageParams
+from .flush_done_message import FlushDoneMessageParams
+from .streaming_transcription_response import (
+    StreamingTranscriptionResponseParams,
+    StreamingTranscriptionResponse_DoneParams,
+    StreamingTranscriptionResponse_ErrorParams,
+    StreamingTranscriptionResponse_FlushDoneParams,
+    StreamingTranscriptionResponse_TranscriptParams,
+)
+from .transcript_message import TranscriptMessageParams
+from .transcription_response import TranscriptionResponseParams
+from .transcription_word import TranscriptionWordParams
+
+__all__ = [
+    "DoneMessageParams",
+    "ErrorMessageParams",
+    "FlushDoneMessageParams",
+    "StreamingTranscriptionResponseParams",
+    "StreamingTranscriptionResponse_DoneParams",
+    "StreamingTranscriptionResponse_ErrorParams",
+    "StreamingTranscriptionResponse_FlushDoneParams",
+    "StreamingTranscriptionResponse_TranscriptParams",
+    "TranscriptMessageParams",
+    "TranscriptionResponseParams",
+    "TranscriptionWordParams",
+]

cartesia/stt/requests/done_message.py

@@ -0,0 +1,14 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing_extensions
+
+
+class DoneMessageParams(typing_extensions.TypedDict):
+    """
+    Acknowledgment message sent in response to a `done` command, indicating that the session is complete and the WebSocket will close.
+    """
+
+    request_id: str
+    """
+    Unique identifier for this transcription session.
+    """

cartesia/stt/requests/error_message.py

@@ -0,0 +1,16 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing_extensions
+import typing_extensions
+
+
+class ErrorMessageParams(typing_extensions.TypedDict):
+    request_id: typing_extensions.NotRequired[str]
+    """
+    The request ID associated with the error, if applicable.
+    """
+
+    message: str
+    """
+    Human-readable error message describing what went wrong.
+    """

cartesia/stt/requests/flush_done_message.py

@@ -0,0 +1,14 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing_extensions
+
+
+class FlushDoneMessageParams(typing_extensions.TypedDict):
+    """
+    Acknowledgment message sent in response to a `finalize` command, indicating that all buffered audio has been flushed and processed.
+    """
+
+    request_id: str
+    """
+    Unique identifier for this transcription session.
+    """

cartesia/stt/requests/streaming_transcription_response.py

@@ -0,0 +1,41 @@
+# This file was auto-generated by Fern from our API Definition.
+
+from __future__ import annotations
+import typing_extensions
+import typing
+import typing_extensions
+from .transcription_word import TranscriptionWordParams
+
+
+class StreamingTranscriptionResponse_TranscriptParams(typing_extensions.TypedDict):
+    type: typing.Literal["transcript"]
+    request_id: str
+    text: str
+    is_final: bool
+    duration: typing_extensions.NotRequired[float]
+    language: typing_extensions.NotRequired[str]
+    words: typing_extensions.NotRequired[typing.Sequence[TranscriptionWordParams]]
+
+
+class StreamingTranscriptionResponse_FlushDoneParams(typing_extensions.TypedDict):
+    type: typing.Literal["flush_done"]
+    request_id: str
+
+
+class StreamingTranscriptionResponse_DoneParams(typing_extensions.TypedDict):
+    type: typing.Literal["done"]
+    request_id: str
+
+
+class StreamingTranscriptionResponse_ErrorParams(typing_extensions.TypedDict):
+    type: typing.Literal["error"]
+    request_id: typing_extensions.NotRequired[str]
+    message: str
+
+
+StreamingTranscriptionResponseParams = typing.Union[
+    StreamingTranscriptionResponse_TranscriptParams,
+    StreamingTranscriptionResponse_FlushDoneParams,
+    StreamingTranscriptionResponse_DoneParams,
+    StreamingTranscriptionResponse_ErrorParams,
+]

cartesia/stt/requests/transcript_message.py

@@ -0,0 +1,40 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing_extensions
+import typing_extensions
+import typing
+from .transcription_word import TranscriptionWordParams
+
+
+class TranscriptMessageParams(typing_extensions.TypedDict):
+    request_id: str
+    """
+    Unique identifier for this transcription session.
+    """
+
+    text: str
+    """
+    The transcribed text. May be partial or final depending on is_final.
+    
+    **Note**: Text may be empty in initial responses while the system accumulates sufficient audio for transcription. This is normal behavior - wait for responses with non-empty text or monitor is_final for completion status.
+    """
+
+    is_final: bool
+    """
+    Whether this is a final transcription result or an interim result.
+    """
+
+    duration: typing_extensions.NotRequired[float]
+    """
+    The duration of the audio transcribed so far, in seconds.
+    """
+
+    language: typing_extensions.NotRequired[str]
+    """
+    The specified language of the input audio.
+    """
+
+    words: typing_extensions.NotRequired[typing.Sequence[TranscriptionWordParams]]
+    """
+    Word-level timestamps showing the start and end time of each word in seconds. Always included in streaming responses.
+    """

cartesia/stt/requests/transcription_response.py

@@ -0,0 +1,28 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing_extensions
+import typing_extensions
+import typing
+from .transcription_word import TranscriptionWordParams
+
+
+class TranscriptionResponseParams(typing_extensions.TypedDict):
+    text: str
+    """
+    The transcribed text.
+    """
+
+    language: typing_extensions.NotRequired[str]
+    """
+    The specified language of the input audio.
+    """
+
+    duration: typing_extensions.NotRequired[float]
+    """
+    The duration of the input audio in seconds.
+    """
+
+    words: typing_extensions.NotRequired[typing.Sequence[TranscriptionWordParams]]
+    """
+    Word-level timestamps showing the start and end time of each word. Only included when `[word]` is passed into `timestamp_granularities[]`.
+    """

cartesia/stt/requests/transcription_word.py

@@ -0,0 +1,20 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing_extensions
+
+
+class TranscriptionWordParams(typing_extensions.TypedDict):
+    word: str
+    """
+    The transcribed word.
+    """
+
+    start: float
+    """
+    Start time of the word in seconds.
+    """
+
+    end: float
+    """
+    End time of the word in seconds.
+    """