Soniox

https://soniox.com/docs
Admin
Soniox provides powerful, production-ready APIs for transcribing, translating, and understanding...
Tokens:819,555
Snippets:5,997
Trust Score:8.3
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Clone and install dependencies

Source: https://soniox.com/docs/integrations/twilio

Clone the example repository and install its Python dependencies.

```bash
git clone https://github.com/soniox/soniox-twilio-realtime-transcription.git
cd soniox-twilio-realtime-transcription
pip install -r requirements.txt
```

--------------------------------

### Run Python examples

Source: https://soniox.com/docs/stt/get-started

Runs the Python examples (non-SDK): sets up a virtual environment, installs dependencies, then executes the real-time and async transcription scripts with the provided audio file or URL.

```bash
cd python

# Set up environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Real-time examples
python soniox_realtime.py --audio_path ../assets/coffee_shop.mp3

# Async examples
python soniox_async.py --audio_url "https://soniox.com/media/examples/coffee_shop.mp3"
python soniox_async.py --audio_path ../assets/coffee_shop.mp3
```

--------------------------------

### Run Node.js SDK examples

Source: https://soniox.com/docs/stt/get-started

Runs the Node.js SDK examples: installs dependencies with npm, then executes the real-time and async transcription scripts with the provided audio file or URL.

```bash
cd nodejs_sdk

# Install dependencies
npm install

# Real-time examples
node soniox_sdk_realtime.js --audio_path ../assets/coffee_shop.mp3

# Async examples
node soniox_sdk_async.js --audio_url "https://soniox.com/media/examples/coffee_shop.mp3"
node soniox_sdk_async.js --audio_path ../assets/coffee_shop.mp3
```

--------------------------------

### Run Python SDK examples

Source: https://soniox.com/docs/stt/get-started

Runs the Python SDK examples: sets up a virtual environment, installs dependencies, then executes the real-time and async transcription scripts with the provided audio file or URL.

```bash
cd python_sdk

# Set up environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Real-time examples
python soniox_sdk_realtime.py --audio_path ../assets/coffee_shop.mp3

# Async examples
python soniox_sdk_async.py --audio_url "https://soniox.com/media/examples/coffee_shop.mp3"
python soniox_sdk_async.py --audio_path ../assets/coffee_shop.mp3
```

--------------------------------

### Quickstart: useTts with config resolver and voice

Source: https://soniox.com/docs/sdk/react-SDK/tts/realtime-speech-generation

Minimal setup for the Soniox React SDK: pass a config resolver (fetchTtsKey) and a voice to useTts. speak() starts generation, state reflects the lifecycle, and audio plays via the onAudio/onTerminated callbacks.

```tsx
import { useTts } from "@soniox/react";
import { useRef } from "react";

async function fetchTtsKey() {
  const res = await fetch("/tts-tmp-key");
  const { api_key } = await res.json();
  return { api_key };
}

export function TtsButton() {
  const audioChunksRef = useRef<Uint8Array[]>([]);

  const { speak, state, isSpeaking, error } = useTts({
    config: fetchTtsKey,
    voice: "Adrian",
    model: "tts-rt-v2",
    language: "en",
    audio_format: "wav",
    onAudio: (chunk) => {
      audioChunksRef.current.push(chunk);
    },
    onTerminated: () => {
      const blob = new Blob(audioChunksRef.current, { type: "audio/wav" });
      new Audio(URL.createObjectURL(blob)).play();
      audioChunksRef.current = [];
    },
    onError: (err) => console.error(err),
  });

  return (
    <div>
      <button onClick={() => speak("Hello from Soniox React SDK!")} disabled={isSpeaking}>
        Speak
      </button>
      <p>State: {state}</p>
      {error && <p style={{ color: "red" }}>{error.message}</p>}
    </div>
  );
}
```

--------------------------------

### Run Node.js examples

Source: https://soniox.com/docs/stt/get-started

Runs the Node.js examples (non-SDK): installs dependencies with npm, then executes the real-time and async transcription scripts with the provided audio file or URL.

```bash
cd nodejs

# Install dependencies
npm install

# Real-time examples
node soniox_realtime.js --audio_path ../assets/coffee_shop.mp3

# Async examples
node soniox_async.js --audio_url "https://soniox.com/media/examples/coffee_shop.mp3"
node soniox_async.js --audio_path ../assets/coffee_shop.mp3
```

--------------------------------

### Quickstart: generate speech to file

Source: https://soniox.com/docs/sdk/python-SDK/tts/rest-speech-generation

Quickstart example that writes generated speech to a WAV file using the `generate_to_file` method. Requires an `AsyncSonioxClient` and uses the `tts-rt-v2` model with the Adrian voice.

```python
import asyncio
from soniox import AsyncSonioxClient

async def main() -> None:
    client = AsyncSonioxClient()
    try:
        written = await client.tts.generate_to_file(
            "tts_async_output.wav",
            text="Hello from the Soniox Python SDK async TTS example.",
            model="tts-rt-v2",
            language="en",
            voice="Adrian",
            audio_format="wav",
        )
        print(f"Wrote {written} bytes")
    finally:
        await client.aclose()

asyncio.run(main())
```

--------------------------------

### Run Node.js SDK TTS examples

Source: https://soniox.com/docs/tts/get-started

Installs dependencies and runs the Node.js SDK real-time (WebSocket) and REST TTS examples.

```bash
cd nodejs_sdk

# Install dependencies
npm install

# Real-time TTS example (WebSocket)
node soniox_sdk_realtime.js --line "Hello from Soniox realtime Text-to-Speech."

# REST TTS example
node soniox_sdk_rest.js --text "Hello from Soniox REST Text-to-Speech."
```

--------------------------------

### Install Soniox Python SDK with pip

Source: https://soniox.com/docs/sdk/python-SDK

Install the Soniox Python SDK using pip. This is the first step in the quickstart.

```bash
pip install soniox
```

--------------------------------

### Run Node.js TTS examples

Source: https://soniox.com/docs/tts/get-started

Installs dependencies and runs the Node.js real-time (WebSocket) and REST TTS examples from the examples repo.

```bash
cd nodejs

# Install dependencies
npm install

# Real-time TTS example (WebSocket)
node soniox_realtime.js --line "Hello from Soniox websocket Text-to-Speech."

# REST TTS example
node soniox_rest.js --text "Hello from Soniox REST Text-to-Speech."
```

--------------------------------

### Run Python SDK translation examples

Source: https://soniox.com/docs/translation/get-started

Runs the Python SDK real-time translation examples. Sets up a virtual environment, installs dependencies, and executes one-way and two-way translation commands.

```bash
cd python_sdk

# Set up environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# One-way translation of a live audio stream
python soniox_sdk_realtime.py --audio_path ../assets/coffee_shop.mp3 --translation one_way

# Two-way translation of a live audio stream
python soniox_sdk_realtime.py --audio_path ../assets/two_way_translation.mp3 --translation two_way
```

--------------------------------

### Run Node.js SDK translation examples

Source: https://soniox.com/docs/translation/get-started

Runs the Node.js SDK real-time translation examples. Installs dependencies and executes one-way and two-way translation commands.

```bash
cd nodejs_sdk

# Install dependencies
npm install

# One-way translation of a live audio stream
node soniox_sdk_realtime.js --audio_path ../assets/coffee_shop.mp3 --translation one_way

# Two-way translation of a live audio stream
node soniox_sdk_realtime.js --audio_path ../assets/two_way_translation.mp3 --translation two_way
```

--------------------------------

### Run Python translation examples

Source: https://soniox.com/docs/translation/get-started

Runs the Python real-time translation examples. Sets up a virtual environment, installs dependencies, and executes one-way and two-way translation commands.

```bash
cd python

# Set up environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# One-way translation of a live audio stream
python soniox_realtime.py --audio_path ../assets/coffee_shop.mp3 --translation one_way

# Two-way translation of a live audio stream
python soniox_realtime.py --audio_path ../assets/two_way_translation.mp3 --translation two_way
```

--------------------------------

### Python SDK real-time TTS example (soniox_sdk_realtime.py)

Source: https://soniox.com/docs/tts/rt/real-time-generation

Complete Python example for real-time text-to-speech using the Soniox SDK. It builds a RealtimeTTSConfig, sends text chunks in a background thread, and receives audio chunks. Requires completing the 'Get started' steps. The example is available on GitHub as soniox_sdk_realtime.py.

```python
import argparse
import os
import threading
import time
from pathlib import Path
from uuid import uuid4

from soniox import SonioxClient
from soniox.errors import SonioxRealtimeError
from soniox.types import RealtimeTTSConfig
from soniox.utils import output_file_for_audio_format

VALID_SAMPLE_RATES = [8000, 16000, 24000, 44100, 48000]
VALID_BITRATES = [32000, 64000, 96000, 128000, 192000, 256000, 320000]
VALID_AUDIO_FORMATS = [
    "pcm_f32le",
    "pcm_s16le",
    "pcm_mulaw",
    "pcm_alaw",
    "wav",
    "aac",
    "mp3",
    "opus",
    "flac",
]

DEFAULT_LINES = [
    "Welcome to Soniox real-time Text-to-Speech. ",
    "As text is streamed in, audio streams back in parallel with high accuracy, ",
    "so your application can start playing speech ",
    "within milliseconds of the first word.",
]


def get_config(
    model: str,
    language: str,
    voice: str,
    audio_format: str,
    sample_rate: int | None,
    bitrate: int | None,
    stream_id: str | None,
) -> RealtimeTTSConfig:
    config = RealtimeTTSConfig(
        # Stream id for this realtime TTS session.
        # If omitted, a random id is generated.
        stream_id=stream_id or f"tts-{uuid4()}",
        #
        # Select the model to use.
        # See: soniox.com/docs/tts/models
        model=model,
        #
        # Set the language of the input text.
        # See: soniox.com/docs/tts/concepts/supported-languages
        language=language,
        #
        # Select the voice to use.
        # See: soniox.com/docs/tts/concepts/voices
        voice=voice,
        #
        # Set output audio format and optional encoding parameters.
        # See: soniox.com/docs/api-reference/tts/websocket-api
        audio_format=audio_format,
        sample_rate=sample_rate,
        bitrate=bitrate,
    )

    return config


def run_session(
    client: SonioxClient,
    lines: list[str],
    model: str,
    language: str,
    voice: str,
    audio_format: str,
    sample_rate: int | None,
    bitrate: int | None,
    stream_id: str | None,
    output_path: str | None,
) -> None:
    # Build a realtime Text-to-Speech session configuration.
    config = get_config(
        model=model,
        language=language,
        voice=voice,
        audio_format=audio_format,
        sample_rate=sample_rate,
        bitrate=bitrate,
        stream_id=stream_id,
    )
    sanitized_lines = [line.strip() for line in lines if line.strip()]
    if not sanitized_lines:
        raise ValueError("Text is empty after parsing.")

    destination = (
        Path(output_path)
        if output_path
        else output_file_for_audio_format(audio_format, "tts_realtime")
    )
    print("Connecting to Soniox...")
    audio_chunks: list[bytes] = []
    try:
        with client.realtime.tts.connect(config=config) as session:
            print("Session started.")
            send_errors: list[Exception] = []

            def send_worker() -> None:
                try:
                    for line in sanitized_lines:
                        session.send_text_chunk(line, text_end=False)
                        time.sleep(0.1)
                    session.finish()
                except Exception as exc:
                    send_errors.append(exc)

            threading.Thread(target=send_worker, daemon=True).start()
            # Receive streamed audio chunks from the websocket.
            for audio_chunk in session.receive_audio_chunks():
                audio_chunks.append(audio_chunk)
            if send_errors:
                raise RuntimeError(f"Failed to send realtime text: {send_errors[0]}")
            print("Session finished.")
    finally:
        audio = b"".join(audio_chunks)
        if audio:
            destination.write_bytes(audio)
            print(f"Wrote {len(audio)} bytes to {destination.resolve()}")
        else:
            print("No audio file was written.")
```

--------------------------------

### Get voice example

Source: https://soniox.com/docs/sdk/node-SDK/reference/classes

Example usage of get() to retrieve a voice by UUID and log its name and models if found.

```typescript
const voice = await client.tts.voices.get('550e8400-e29b-41d4-a716-446655440000');
if (voice) {
  console.log(voice.name, voice.models);
}
```

--------------------------------

### Real-time TTS WebSocket example (soniox_sdk_realtime.py)

Source: https://soniox.com/docs/api-reference/tts/websocket-api

Complete Python example for real-time text-to-speech using the Soniox WebSocket API. It defines a RealtimeTTSConfig, sends text chunks in a background thread, receives audio chunks, and writes the output to a file. Requires completing the Get started steps and having a SonioxClient instance.

```python
import argparse
import os
import threading
import time
from pathlib import Path
from uuid import uuid4

from soniox import SonioxClient
from soniox.errors import SonioxRealtimeError
from soniox.types import RealtimeTTSConfig
from soniox.utils import output_file_for_audio_format

VALID_SAMPLE_RATES = [8000, 16000, 24000, 44100, 48000]
VALID_BITRATES = [32000, 64000, 96000, 128000, 192000, 256000, 320000]
VALID_AUDIO_FORMATS = [
    "pcm_f32le",
    "pcm_s16le",
    "pcm_mulaw",
    "pcm_alaw",
    "wav",
    "aac",
    "mp3",
    "opus",
    "flac",
]

DEFAULT_LINES = [
    "Welcome to Soniox real-time Text-to-Speech. ",
    "As text is streamed in, audio streams back in parallel with high accuracy, ",
    "so your application can start playing speech ",
    "within milliseconds of the first word.",
]


def get_config(
    model: str,
    language: str,
    voice: str,
    audio_format: str,
    sample_rate: int | None,
    bitrate: int | None,
    stream_id: str | None,
) -> RealtimeTTSConfig:
    config = RealtimeTTSConfig(
        # Stream id for this realtime TTS session.
        # If omitted, a random id is generated.
        stream_id=stream_id or f"tts-{uuid4()}",
        #
        # Select the model to use.
        # See: soniox.com/docs/tts/models
        model=model,
        #
        # Set the language of the input text.
        # See: soniox.com/docs/tts/concepts/supported-languages
        language=language,
        #
        # Select the voice to use.
        # See: soniox.com/docs/tts/concepts/voices
        voice=voice,
        #
        # Set output audio format and optional encoding parameters.
        # See: soniox.com/docs/api-reference/tts/websocket-api
        audio_format=audio_format,
        sample_rate=sample_rate,
        bitrate=bitrate,
    )

    return config


def run_session(
    client: SonioxClient,
    lines: list[str],
    model: str,
    language: str,
    voice: str,
    audio_format: str,
    sample_rate: int | None,
    bitrate: int | None,
    stream_id: str | None,
    output_path: str | None,
) -> None:
    # Build a realtime Text-to-Speech session configuration.
    config = get_config(
        model=model,
        language=language,
        voice=voice,
        audio_format=audio_format,
        sample_rate=sample_rate,
        bitrate=bitrate,
        stream_id=stream_id,
    )
    sanitized_lines = [line.strip() for line in lines if line.strip()]
    if not sanitized_lines:
        raise ValueError("Text is empty after parsing.")

    destination = (
        Path(output_path)
        if output_path
        else output_file_for_audio_format(audio_format, "tts_realtime")
    )
    print("Connecting to Soniox...")
    audio_chunks: list[bytes] = []
    try:
        with client.realtime.tts.connect(config=config) as session:
            print("Session started.")
            send_errors: list[Exception] = []

            def send_worker() -> None:
                try:
                    for line in sanitized_lines:
                        session.send_text_chunk(line, text_end=False)
                        time.sleep(0.1)
                    session.finish()
                except Exception as exc:
                    send_errors.append(exc)

            threading.Thread(target=send_worker, daemon=True).start()
            # Receive streamed audio chunks from the websocket.
            for audio_chunk in session.receive_audio_chunks():
                audio_chunks.append(audio_chunk)
            if send_errors:
                raise RuntimeError(f"Failed to send realtime text: {send_errors[0]}")
            print("Session finished.")
    finally:
        audio = b"".join(audio_chunks)
        if audio:
            destination.write_bytes(audio)
            print(f"Wrote {len(audio)} bytes to {destination.resolve()}")
        else:
            print("No audio file was written.")


def main() -> None:
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "--line",
        action="append",
        default=None,
        help="Line to send to realtime TTS (repeat --line for multiple lines).",
    )
    parser.add_argument("--model", default="tts-rt-v2")
    parser.add_argument("--language", default="en")
    parser.add_argument("--voice", default="Adrian")
    parser.add_argument("--audio_format", default="wav")
    parser.add_argument("--sample_rate", type=int)
    parser.add_argument("--bitrate", type=int)
    parser.add_argument("--stream_id", help="Optional stream id.")
    parser.add_argument(
        "--output_path",
        help="Optional output file path. If omitted, a timestamped path is generated.",
    )
    args = parser.parse_args()

```

--------------------------------

### Python SDK real-time STT translation example (soniox_sdk_realtime.py)

Source: https://soniox.com/docs/translation/stt-translation/rt-translation

Runnable Python example for real-time STT with translation. Configures model, language hints, language identification, speaker diarization, structured context, endpoint detection, audio format, and translation modes (one-way or two-way). Requires completing the Get started steps.

```python
import os
import argparse
from typing import Optional

from soniox import SonioxClient
from soniox.types import (
    RealtimeSTTConfig,
    StructuredContext,
    TranslationConfig,
    StructuredContextGeneralItem,
    StructuredContextTranslationTerm,
)
from soniox.utils import render_tokens, start_audio_thread, throttle_audio


def get_config(audio_format: str, translation: Optional[str]) -> RealtimeSTTConfig:
    config = RealtimeSTTConfig(
        # Select the model to use.
        # See: soniox.com/docs/stt/models
        model="stt-rt-v5",
        #
        # Set language hints when possible to significantly improve accuracy.
        # See: soniox.com/docs/stt/concepts/language-hints
        language_hints=["en", "es"],
        #
        # Enable language identification. Each token will include a "language" field.
        # See: soniox.com/docs/stt/concepts/language-identification
        enable_language_identification=True,
        #
        # Enable speaker diarization. Each token will include a "speaker" field.
        # See: soniox.com/docs/stt/concepts/speaker-diarization
        enable_speaker_diarization=True,
        #
        # Set context to help the model understand your domain, recognize important terms,
        # and apply custom vocabulary and translation preferences.
        # See: soniox.com/docs/stt/concepts/context
        context=StructuredContext(
            general=[
                StructuredContextGeneralItem(key="domain", value="Healthcare"),
                StructuredContextGeneralItem(
                    key="topic", value="Diabetes management consultation"
                ),
                StructuredContextGeneralItem(key="doctor", value="Dr. Martha Smith"),
                StructuredContextGeneralItem(key="patient", value="Mr. David Miller"),
                StructuredContextGeneralItem(
                    key="organization", value="St John's Hospital"
                ),
            ],
            text="Mr. David Miller visited his healthcare provider last month for a routine follow-up related to diabetes care. The clinician reviewed his recent test results, noted improved glucose levels, and adjusted his medication schedule accordingly. They also discussed meal planning strategies and scheduled the next check-up for early spring.",
            terms=[
                "Celebrex",
                "Zyrtec",
                "Xanax",
                "Prilosec",
                "Amoxicillin Clavulanate Potassium",
            ],
            translation_terms=[
                StructuredContextTranslationTerm(
                    source="Mr. Smith", target="Sr. Smith"
                ),
                StructuredContextTranslationTerm(
                    source="St John's", target="St John's"
                ),
                StructuredContextTranslationTerm(source="stroke", target="ictus"),
            ],
        ),
        #
        # Use endpointing to detect when the speaker stops.
        # It finalizes all non-final tokens right away, minimizing latency.
        # See: soniox.com/docs/stt/rt/endpoint-detection
        enable_endpoint_detection=True,
    )

    # Audio format.
    # See: soniox.com/docs/stt/rt/real-time-transcription#audio-formats
    if audio_format == "auto":
        # Set to "auto" to let Soniox detect the audio format automatically.
        config.audio_format = "auto"
    elif audio_format == "pcm_s16le":
        # Example of a raw audio format; Soniox supports many others as well.
        config.audio_format = "pcm_s16le"
        config.sample_rate = 16000
        config.num_channels = 1
    else:
        raise ValueError(f"Unsupported audio_format: {audio_format}")

    # Translation options.
    # See: soniox.com/docs/translation/stt-translation#translation-modes
    if translation == "none":
        pass
    elif translation == "one_way":
        # Translates all languages into the target language.
        config.translation = TranslationConfig(
            type="one_way",
            target_language="es",
        )
    elif translation == "two_way":
        # Translates from language_a to language_b and back from language_b to language_a.
        config.translation = TranslationConfig(
            type="two_way",
            language_a="en",
            language_b="es",
        )
    else:
        raise ValueError(f"Unsupported translation: {translation}")

    return config


def run_session(
    client: SonioxClient,
    audio_path: str,
    audio_format: str,
    translation: str,
) -> None:
    config = get_config(audio_format, translation)

    print("Connecting to Soniox...")
    with client.realtime.stt.connect(config=config) as session:
        final_tokens = []

        start_audio_thread(session, throttle_audio(audio_path, delay_seconds=0.1))
        print("Session started.")
```

--------------------------------

### GET /v1/usage/summary with example response

Source: https://soniox.com/docs/guides/usage-summary

Retrieve usage summary for a date range. The response includes a total entry and per-model entries, each with daily arrays aligned by index. Only successfully started requests are counted; rejected requests are excluded.

```http
GET /v1/usage/summary?start_time=2026-04-01T00:00:00Z&end_time=2026-04-03T00:00:00Z
Authorization: Bearer <SONIOX_API_KEY>
```

```json
{
  "total": {
    "model": null,
    "days": ["2026-04-01", "2026-04-02"],
    "total_cost_usd": "0.2567250000",
    "total_input_cost_usd": "0.0415500000",
    "total_output_cost_usd": "0.2151750000",
    "total_duration_cost_usd": "0.0000000000",
    "cost_usd": ["0.1711500000", "0.0855750000"],
    "input_cost_usd": ["0.0277000000", "0.0138500000"],
    "output_cost_usd": ["0.1434500000", "0.0717250000"],
    "duration_cost_usd": ["0.0000000000", "0.0000000000"],
    "total_num_requests": 285,
    "total_input_text_tokens": 4800,
    "total_input_audio_tokens": 15000,
    "total_input_audio_duration_ms": 1800000,
    "total_output_text_tokens": 10800,
    "total_output_audio_tokens": 8250,
    "total_output_audio_duration_ms": 990000,
    "total_duration_ms": 0,
    "num_requests": [190, 95],
    "input_text_tokens": [3200, 1600],
    "input_audio_tokens": [10000, 5000],
    "input_audio_duration_ms": [1200000, 600000],
    "output_text_tokens": [7200, 3600],
    "output_audio_tokens": [5500, 2750],
    "output_audio_duration_ms": [660000, 330000],
    "duration_ms": [0, 0]
  },
  "models": [
    {
      "model": "stt-async-v5",
      "days": ["2026-04-01", "2026-04-02"],
      "total_cost_usd": "0.0613500000",
      "total_input_cost_usd": "0.0235500000",
      "total_output_cost_usd": "0.0378000000",
      "total_duration_cost_usd": "0.0000000000",
      "cost_usd": ["0.0409000000", "0.0204500000"],
      "input_cost_usd": ["0.0157000000", "0.0078500000"],
      "output_cost_usd": ["0.0252000000", "0.0126000000"],
      "duration_cost_usd": ["0.0000000000", "0.0000000000"],
      "total_num_requests": 60,
      "total_input_text_tokens": 300,
      "total_input_audio_tokens": 15000,
      "total_input_audio_duration_ms": 1800000,
      "total_output_text_tokens": 10800,
      "total_output_audio_tokens": 0,
      "total_output_audio_duration_ms": 0,
      "total_duration_ms": 0,
      "num_requests": [40, 20],
      "input_text_tokens": [200, 100],
      "input_audio_tokens": [10000, 5000],
      "input_audio_duration_ms": [1200000, 600000],
      "output_text_tokens": [7200, 3600],
      "output_audio_tokens": [0, 0],
      "output_audio_duration_ms": [0, 0],
      "duration_ms": [0, 0]
    },
    {
      "model": "tts-rt-v2",
      "days": ["2026-04-01", "2026-04-02"],
      "total_cost_usd": "0.1953750000",
      "total_input_cost_usd": "0.0180000000",
      "total_output_cost_usd": "0.1773750000",
      "total_duration_cost_usd": "0.0000000000",
      "cost_usd": ["0.1302500000", "0.0651250000"],
      "input_cost_usd": ["0.0120000000", "0.0060000000"],
      "output_cost_usd": ["0.1182500000", "0.0591250000"],
      "duration_cost_usd": ["0.0000000000", "0.0000000000"],
      "total_num_requests": 225,
      "total_input_text_tokens": 4500,
      "total_input_audio_tokens": 0,
      "total_input_audio_duration_ms": 0,
      "total_output_text_tokens": 0,
      "total_output_audio_tokens": 8250,
      "total_output_audio_duration_ms": 990000,
      "total_duration_ms": 0,
      "num_requests": [150, 75],
      "input_text_tokens": [3000, 1500],
      "input_audio_tokens": [0, 0],
      "input_audio_duration_ms": [0, 0],
      "output_text_tokens": [0, 0],
      "output_audio_tokens": [5500, 2750],
      "output_audio_duration_ms": [660000, 330000],
      "duration_ms": [0, 0]
    }
  ]
}
```

--------------------------------

### Run Python SDK TTS examples

Source: https://soniox.com/docs/tts/get-started

Sets up the Python SDK environment and runs the real-time (WebSocket) and REST TTS examples.

```bash
cd python_sdk

# Set up environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Real-time TTS example (WebSocket)
python soniox_sdk_realtime.py --line "Hello from Soniox realtime Text-to-Speech."

# REST TTS example
python soniox_sdk_rest.py --text "Hello from Soniox REST Text-to-Speech."
```

--------------------------------

### GET /v1/models response example

Source: https://soniox.com/docs/llms-full.txt

Example response for the GET /v1/models endpoint. Shows the model object with id "stt-rt-v4", its supported languages, and attributes such as one_way_translation and endpoint_latency_adjustment_max_level.

```json
{
  "models": [
    {
      "aliased_model_id": null,
      "context_version": 2,
      "id": "stt-rt-v4",
      "languages": [
        {
          "code": "af",
          "name": "Afrikaans"
        },
        {
          "code": "sq",
          "name": "Albanian"
        },
        {
          "code": "ar",
          "name": "Arabic"
        },
        {
          "code": "az",
          "name": "Azerbaijani"
        },
        {
          "code": "eu",
          "name": "Basque"
        },
        {
          "code": "be",
          "name": "Belarusian"
        },
        {
          "code": "bn",
          "name": "Bengali"
        },
        {
          "code": "bs",
          "name": "Bosnian"
        },
        {
          "code": "bg",
          "name": "Bulgarian"
        },
        {
          "code": "ca",
          "name": "Catalan"
        },
        {
          "code": "zh",
          "name": "Chinese"
        },
        {
          "code": "hr",
          "name": "Croatian"
        },
        {
          "code": "cs",
          "name": "Czech"
        },
        {
          "code": "da",
          "name": "Danish"
        },
        {
          "code": "nl",
          "name": "Dutch"
        },
        {
          "code": "en",
          "name": "English"
        },
        {
          "code": "et",
          "name": "Estonian"
        },
        {
          "code": "fi",
          "name": "Finnish"
        },
        {
          "code": "fr",
          "name": "French"
        },
        {
          "code": "gl",
          "name": "Galician"
        },
        {
          "code": "de",
          "name": "German"
        },
        {
          "code": "el",
          "name": "Greek"
        },
        {
          "code": "gu",
          "name": "Gujarati"
        },
        {
          "code": "he",
          "name": "Hebrew"
        },
        {
          "code": "hi",
          "name": "Hindi"
        },
        {
          "code": "hu",
          "name": "Hungarian"
        },
        {
          "code": "id",
          "name": "Indonesian"
        },
        {
          "code": "it",
          "name": "Italian"
        },
        {
          "code": "ja",
          "name": "Japanese"
        },
        {
          "code": "kn",
          "name": "Kannada"
        },
        {
          "code": "kk",
          "name": "Kazakh"
        },
        {
          "code": "ko",
          "name": "Korean"
        },
        {
          "code": "lv",
          "name": "Latvian"
        },
        {
          "code": "lt",
          "name": "Lithuanian"
        },
        {
          "code": "mk",
          "name": "Macedonian"
        },
        {
          "code": "ms",
          "name": "Malay"
        },
        {
          "code": "ml",
          "name": "Malayalam"
        },
        {
          "code": "mr",
          "name": "Marathi"
        },
        {
          "code": "no",
          "name": "Norwegian"
        },
        {
          "code": "fa",
          "name": "Persian"
        },
        {
          "code": "pl",
          "name": "Polish"
        },
        {
          "code": "pt",
          "name": "Portuguese"
        },
        {
          "code": "pa",
          "name": "Punjabi"
        },
        {
          "code": "ro",
          "name": "Romanian"
        },
        {
          "code": "ru",
          "name": "Russian"
        },
        {
          "code": "sr",
          "name": "Serbian"
        },
        {
          "code": "sk",
          "name": "Slovak"
        },
        {
          "code": "sl",
          "name": "Slovenian"
        },
        {
          "code": "es",
          "name": "Spanish"
        },
        {
          "code": "sw",
          "name": "Swahili"
        },
        {
          "code": "sv",
          "name": "Swedish"
        },
        {
          "code": "tl",
          "name": "Tagalog"
        },
        {
          "code": "ta",
          "name": "Tamil"
        },
        {
          "code": "te",
          "name": "Telugu"
        },
        {
          "code": "th",
          "name": "Thai"
        },
        {
          "code": "tr",
          "name": "Turkish"
        },
        {
          "code": "uk",
          "name": "Ukrainian"
        },
        {
          "code": "ur",
          "name": "Urdu"
        },
        {
          "code": "vi",
          "name": "Vietnamese"
        },
        {
          "code": "cy",
          "name": "Welsh"
        }
      ],
      "name": "Speech-to-Text Real-time v4",
      "one_way_translation": "all_languages",
      "endpoint_latency_adjustment_max_level": 0
    }
  ]
}
```

--------------------------------

### Quickstart: one-way translation with audio_url

Source: https://soniox.com/docs/sdk/node-SDK/stt/async-translation

Creates an async translation job using a public audio URL and waits for completion. Logs the translated text.

```javascript
const job = await client.stt.translate({
  audio_url: 'https://soniox.com/media/examples/coffee_shop.mp3',
  to: 'es',
  wait: true,
});

console.log(job.translation?.translation_text);
```

--------------------------------

### Install @soniox/client with bun

Source: https://soniox.com/docs/sdk/web-SDK

Install the Soniox Web SDK using bun.

```bash
bun add @soniox/client
```

--------------------------------

### Python SDK async transcription configuration

Source: https://soniox.com/docs/llms-full.txt

Python SDK example for configuring an async transcription request with model selection, language hints, language identification, speaker diarization, structured context, and a client reference ID. Requires completing the Get started steps.

```python
import os
import argparse
from typing import Optional

from soniox import SonioxClient
from soniox.types import (
    CreateTranscriptionConfig,
    StructuredContext,
    TranslationConfig,
    StructuredContextGeneralItem,
    StructuredContextTranslationTerm,
)
from soniox.utils import render_tokens


def get_config(translation: Optional[str]) -> CreateTranscriptionConfig:
    config = CreateTranscriptionConfig(
        # Select the model to use.
        # See: soniox.com/docs/stt/models
        model="stt-async-v5",
        #
        # Set language hints when possible to significantly improve accuracy.
        # See: soniox.com/docs/stt/concepts/language-hints
        language_hints=["en", "es"],
        #
        # Enable language identification. Each token will include a "language" field.
        # See: soniox.com/docs/stt/concepts/language-identification
        enable_language_identification=True,
        #
        # Enable speaker diarization. Each token will include a "speaker" field.
        # See: soniox.com/docs/stt/concepts/speaker-diarization
        enable_speaker_diarization=True,
        #
        # Set context to help the model understand your domain, recognize important terms,
        # and apply custom vocabulary and translation preferences.
        # See: soniox.com/docs/stt/concepts/context
        context=StructuredContext(
            general=[
                StructuredContextGeneralItem(key="domain", value="Healthcare"),
                StructuredContextGeneralItem(
                    key="topic", value="Diabetes management consultation"
                ),
                StructuredContextGeneralItem(key="doctor", value="Dr. Martha Smith"),
                StructuredContextGeneralItem(key="patient", value="Mr. David Miller"),
                StructuredContextGeneralItem(
                    key="organization", value="St John's Hospital"
                ),
            ],
            text="Mr. David Miller visited his healthcare provider last month for a routine follow-up related to diabetes care. The clinician reviewed his recent test results, noted improved glucose levels, and adjusted his medication schedule accordingly. They also discussed meal planning strategies and scheduled the next check-up for early spring.",
            terms=[
                "Celebrex",
                "Zyrtec",
                "Xanax",
                "Prilosec",
                "Amoxicillin Clavulanate Potassium",
            ],
            translation_terms=[
                StructuredContextTranslationTerm(
                    source="Mr. Smith", target="Sr. Smith"
                ),
                StructuredContextTranslationTerm(
                    source="St John's", target="St John's"
                ),
                StructuredContextTranslationTerm(source="stroke", target="ictus"),
            ],
        ),
        #
        # Optional identifier to track this request (client-defined).
        # See: https://soniox.com/docs/stt/api-reference/transcriptions/create_transcription#request
        client_reference_id="MyReferenceId",
    )
```

--------------------------------

### Install @soniox/react and @soniox/client with bun

Source: https://soniox.com/docs/sdk/react-native-SDK

Install the required packages using bun.

```bash
bun add @soniox/react @soniox/client
```

--------------------------------

### Run Python TTS examples

Source: https://soniox.com/docs/tts/get-started

Sets up the Python environment and runs the real-time (WebSocket) and REST TTS examples from the examples repo.

```bash
cd python

# Set up environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Real-time TTS example (WebSocket)
python soniox_realtime.py --line "Hello from Soniox websocket Text-to-Speech."

# REST TTS example
python soniox_rest.py --text "Hello from Soniox REST Text-to-Speech."
```

--------------------------------

### GET /v1/models 200 response example

Source: https://soniox.com/docs/api-reference/stt/get_models

Example 200 response body for the GET /v1/models endpoint. Shows the models array with a single model object containing aliased_model_id, context_version, id, and a languages array of supported language code/name pairs.

```json
{
  "models": [
    {
      "aliased_model_id": null,
      "context_version": 2,
      "id": "stt-rt-v4",
      "languages": [
        {
          "code": "af",
          "name": "Afrikaans"
        },
        {
          "code": "sq",
          "name": "Albanian"
        },
        {
          "code": "ar",
          "name": "Arabic"
        },
        {
          "code": "az",
          "name": "Azerbaijani"
        },
        {
          "code": "eu",
          "name": "Basque"
        },
        {
          "code": "be",
          "name": "Belarusian"
        },
        {
          "code": "bn",
          "name": "Bengali"
        },
        {
          "code": "bs",
          "name": "Bosnian"
        },
        {
          "code": "bg",
          "name": "Bulgarian"
        },
        {
          "code": "ca",
          "name": "Catalan"
        },
        {
          "code": "zh",
          "name": "Chinese"
        },
        {
          "code": "hr",
          "name": "Croatian"
        },
        {
          "code": "cs",
          "name": "Czech"
        },
        {
          "code": "da",
          "name": "Danish"
        },
        {
          "code": "nl",
          "name": "Dutch"
        },
        {
          "code": "en",
          "name": "English"
        },
        {
          "code": "et",
          "name": "Estonian"
        },
        {
          "code": "fi",
          "name": "Finnish"
        },
        {
          "code": "fr",
          "name": "French"
        },
        {
          "code": "gl",
          "name": "Galician"
        },
        {
          "code": "de",
          "name": "German"
        },
        {
          "code": "el",
          "name": "Greek"
        },
        {
          "code": "gu",
          "name": "Gujarati"
        },
        {
          "code": "he",
          "name": "Hebrew"
        },
        {
          "code": "hi",
          "name": "Hindi"
        },
        {
          "code": "hu",
          "name": "Hungarian"
        },
        {
          "code": "id",
          "name": "Indonesian"
        },
        {
          "code": "it",
          "name": "Italian"
        },
        {
          "code": "ja",
          "name": "Japanese"
        },
        {
          "code": "kn",
          "name": "Kannada"
        },
        {
          "code": "kk",
          "name": "Kazakh"
        },
        {
          "code": "ko",
          "name": "Korean"
        },
        {
          "code": "lv",
          "name": "Latvian"
        },
        {
          "code": "lt",
          "name": "Lithuanian"
        },
        {
          "code": "mk",
          "name": "Macedonian"
        },
        {
          "code": "ms",
          "name": "Malay"
        },
        {
          "code": "ml",
          "name": "Malayalam"
        },
        {
          "code": "mr",
          "name": "Marathi"
        },
        {
          "code": "no",
          "name": "Norwegian"
        },
        {
          "code": "fa",
          "name": "Persian"
        },
        {
          "code": "pl",
          "name": "Polish"
        },
        {
          "code": "pt",
          "name": "Portuguese"
        },
        {
          "code": "pa",
          "name": "Punjabi"
        },
        {
          "code": "ro",
          "name": "Romanian"
        },
        {
          "code": "ru",
          "name": "Russian"
        },
        {
          "code": "sr",
          "name": "Serbian"
        },
        {
          "code": "sk",
          "name": "Slovak"
        },
        {
          "code": "sl",
          "name": "Slovenian"
        },
        {
          "code": "es",
          "name": "Spanish"
        },
        {
          "code": "sw",
          "name": "Swahili"
        },
        {
          "code": "sv",
          "name": "Swedish"
        },
        {
          "code": "tl",
          "name": "Tagalog"
        },
        {
          "code": "ta",
          "name": "Tamil"
        },
        {
          "code": "te",
          "name": "Telugu"
        },
        {
          "code": "th",
          "name": "Thai"
        },
        {
          "code": "tr",
          "name": "Turkish"
        },
        {
          "code": "uk",
          "name": "Ukrainian"
        },
        {
          "code": "ur",
          "name": "Urdu"
        }
      ]
    }
  ]
}
```
Tokens:
Raw