> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slng.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP vs. WebSocket protocols

> Compare HTTP and WebSocket protocols on SLNG. Latency, flow, complexity, and when to use each for text-to-speech and speech-to-text workloads.

Every TTS and STT model is reachable over both HTTP and WebSocket. The URL stays the same; only the protocol changes.

The snippets on this page use `SLNG_API_KEY` as a placeholder. Replace it with an SLNG key from [app.slng.ai/api-keys](https://app.slng.ai/api-keys) before running the code.

## At a Glance

|                | HTTP                               | WebSocket                          |
| -------------- | ---------------------------------- | ---------------------------------- |
| **Flow**       | Request → wait → complete response | Open connection → stream both ways |
| **Latency**    | 200–500 ms                         | Sub-100 ms                         |
| **Best for**   | Batch jobs, file conversion        | Voice agents, live transcription   |
| **Complexity** | One `curl` call                    | Connection lifecycle to manage     |

## How Each Protocol Works

<Tabs>
  <Tab title="HTTP">
    You send a request and get back the full result once processing finishes.

    ```mermaid theme={null}
    sequenceDiagram
        participant Client
        participant SLNG
        Client->>SLNG: POST /v1/tts/slng/deepgram/aura:2-en<br/>{ "text": "Hello" }
        Note over SLNG: Generates full audio
        SLNG-->>Client: 200 OK – complete WAV file
    ```

    **Use HTTP when you:**

    * Generate audio files for download or storage
    * Transcribe pre-recorded audio files
    * Want the simplest possible integration
    * Don't need real-time streaming

    ```bash theme={null}
    curl https://api.slng.ai/v1/tts/slng/deepgram/aura:2-en \
      -H "Authorization: Bearer SLNG_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "model": "aura-2-thalia-en", "text": "Hello from HTTP!" }' \
      --output hello.wav
    ```

    See complete examples: [TTS over HTTP](/examples/tts-http) · [STT over HTTP](/examples/stt-http)
  </Tab>

  <Tab title="WebSocket">
    You open a persistent connection and stream data in both directions.

    ```mermaid theme={null}
    sequenceDiagram
        participant Client
        participant SLNG
        Client->>SLNG: Connect wss://api.slng.ai/v1/tts/slng/deepgram/aura:2-en
        SLNG-->>Client: Connection open
        Client->>SLNG: { type: "text", text: "Hello" }
        SLNG-->>Client: audio chunk 1
        SLNG-->>Client: audio chunk 2
        SLNG-->>Client: audio chunk 3
        Client->>SLNG: { type: "text", text: "More text" }
        SLNG-->>Client: audio chunk 4
        Note over Client,SLNG: Connection stays open – send more text anytime
    ```

    **Use WebSocket when you:**

    * Build voice agents (STT + LLM + TTS in a loop)
    * Need real-time transcription from a microphone
    * Want the lowest possible latency
    * Stream audio continuously

    ```javascript theme={null}
    const ws = new WebSocket("wss://api.slng.ai/v1/tts/slng/deepgram/aura:2-en");

    ws.onopen = () => {
      ws.send(JSON.stringify({ type: "text", text: "Hello from WebSocket!" }));
    };

    ws.onmessage = (event) => {
      if (event.data instanceof ArrayBuffer) {
        playAudio(event.data); // Stream audio as it arrives
      }
    };
    ```

    See complete examples: [TTS over WebSocket](/examples/tts-websocket) · [STT over WebSocket](/examples/stt-websocket)
  </Tab>
</Tabs>

## WebSocket Best Practices

WebSocket connections are stateful. You need to handle the lifecycle:

* **Reconnect with backoff.** If the connection drops, retry with exponential delay (1s, 2s, 4s... up to 30s).
* **Handle binary and text frames.** Audio arrives as binary `ArrayBuffer`; control messages come as JSON text.
* **Send a close frame** when you're done so the server releases resources.

## Which Protocol for Which Use Case?

| Use case                          | Protocol  | Why                             |
| --------------------------------- | --------- | ------------------------------- |
| Convert a script to an audio file | HTTP      | One request, one file. Simple   |
| Transcribe a batch of recordings  | HTTP      | Upload each file, get results   |
| Voice agent (phone or web)        | WebSocket | Real-time STT→LLM→TTS loop      |
| Live captioning / transcription   | WebSocket | Stream mic audio, get text back |
| Generate a voiceover for a video  | HTTP      | No real-time requirement        |

## Next Steps

<CardGroup cols={2}>
  <Card title="TTS over HTTP" icon="file-audio" href="/examples/tts-http">
    Generate audio files from text with simple HTTP requests.
  </Card>

  <Card title="TTS over WebSocket" icon="bolt" href="/examples/tts-websocket">
    Stream audio in real-time with interruption support.
  </Card>

  <Card title="STT over HTTP" icon="file-lines" href="/examples/stt-http">
    Transcribe pre-recorded audio files.
  </Card>

  <Card title="STT over WebSocket" icon="microphone" href="/examples/stt-websocket">
    Transcribe live audio from a microphone.
  </Card>
</CardGroup>