> ## 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.

# Use the API directly

Call the Text to Speech and Speech to Text APIs from your application. You do
not need to build an agent first.

The first HTTP example creates an audio file. The second returns a transcript.
For streaming, see [Stream in real time](#stream-in-real-time).

## Before you begin

Set `SLNG_API_KEY` in your environment. If you need a key, follow
[Create your API key](/guides/get-started/quickstart#create-your-api-key).
If you already have one, see
[Store and use your key](/guides/get-started/quickstart#store-and-use-your-key).

The model requests below go to `https://eu-west.api.slng.ai` and send your key as a
bearer token.

## Synthesize speech

Text to speech takes some text and a voice and returns audio. Pick the model in
the request path and pass the text in the body. This example uses Fish Audio
S2.1 Pro, where you choose the voice with the `reference_id` parameter in the
body. The endpoint returns binary MP3 audio, so write the response straight to a
file.

<Tabs>
  <Tab title="curl" icon="terminal">
    ```bash theme={null}
    curl https://eu-west.api.slng.ai/v1/tts/slng/fish/tts:s2.1-pro \
      -H "Authorization: Bearer $SLNG_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "text": "Hello from sunny Barcelona!",
        "reference_id": "16cabdb7f8d240569aff36c9e480d783"
      }' \
      --output hello.mp3
    ```
  </Tab>

  <Tab title="JavaScript" icon="js">
    ```js theme={null}
    const response = await fetch(
      "https://eu-west.api.slng.ai/v1/tts/slng/fish/tts:s2.1-pro",
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.SLNG_API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          text: "Hello from sunny Barcelona!",
          reference_id: "16cabdb7f8d240569aff36c9e480d783",
        }),
      },
    );

    const audioData = await response.arrayBuffer();
    // Play or save audioData
    ```
  </Tab>

  <Tab title="SDK" icon="package">
    The [`voiceai-sdk`](https://www.npmjs.com/package/voiceai-sdk) client reads
    `SLNG_API_KEY` from the environment and handles the endpoint for you.

    ```bash theme={null}
    npm install voiceai-sdk
    ```

    ```ts theme={null}
    import { writeFile } from "node:fs/promises";
    import Slng from "voiceai-sdk";

    const client = new Slng();

    const response = await client.textToSpeech.create("slng/fish/tts:s2.1-pro", {
      text: "Hello from sunny Barcelona!",
      voice: "16cabdb7f8d240569aff36c9e480d783",
    });

    await writeFile("hello.mp3", Buffer.from(await response.arrayBuffer()));
    ```
  </Tab>

  <Tab title="Python" icon="python">
    ```python theme={null}
    import os
    import requests

    url = "https://eu-west.api.slng.ai/v1/tts/slng/fish/tts:s2.1-pro"
    headers = {
        "Authorization": f"Bearer {os.environ['SLNG_API_KEY']}",
        "Content-Type": "application/json",
    }
    data = {
        "text": "Hello from sunny Barcelona!",
        "reference_id": "16cabdb7f8d240569aff36c9e480d783",
    }

    response = requests.post(url, headers=headers, json=data)
    with open("hello.mp3", "wb") as f:
        f.write(response.content)
    ```
  </Tab>

  <Tab title="CLI" icon="square-terminal">
    The [`voiceai`](https://www.npmjs.com/package/voiceai-cli) CLI wraps the same
    API. Run `voiceai login` once to store your key.

    ```bash theme={null}
    npm install -g voiceai-cli
    voiceai login
    voiceai tts "Hello from sunny Barcelona!" \
      -m slng/fish/tts:s2.1-pro -v 16cabdb7f8d240569aff36c9e480d783 --out hello.mp3
    ```
  </Tab>
</Tabs>

The call above produces this audio:

Sample output: [`hello.mp3`](/audio/hello.mp3) ("Hello from sunny Barcelona!").

## Transcribe audio

Speech to text takes an audio file and returns the transcript. Send the file as
multipart form data and read the text from the first alternative. The examples
below transcribe this sample:

Sample input: [`micro-machines.wav`](/audio/micro-machines.wav). Download it to
run the examples below.

<Tabs>
  <Tab title="curl" icon="terminal">
    ```bash theme={null}
    curl https://eu-west.api.slng.ai/v1/stt/deepgram/nova:3 \
      -H "Authorization: Bearer $SLNG_API_KEY" \
      -F "audio=@micro-machines.wav"
    ```
  </Tab>

  <Tab title="JavaScript" icon="js">
    ```js theme={null}
    const formData = new FormData();
    formData.append("audio", audioFile); // File from <input type="file">

    const response = await fetch(
      "https://eu-west.api.slng.ai/v1/stt/deepgram/nova:3",
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.SLNG_API_KEY}`,
        },
        body: formData,
      },
    );

    const result = await response.json();
    console.log(result.results.channels[0].alternatives[0].transcript);
    ```
  </Tab>

  <Tab title="SDK" icon="package">
    The [`voiceai-sdk`](https://www.npmjs.com/package/voiceai-sdk) client takes a
    file stream and returns the transcript directly.

    ```ts theme={null}
    import fs from "node:fs";
    import Slng from "voiceai-sdk";

    const client = new Slng();

    const transcript = await client.speechToText.create("deepgram/nova:3", {
      audio: fs.createReadStream("micro-machines.wav"),
    });

    console.log(transcript.alternatives[0]?.transcript);
    ```
  </Tab>

  <Tab title="Python" icon="python">
    ```python theme={null}
    import os
    import requests

    url = "https://eu-west.api.slng.ai/v1/stt/deepgram/nova:3"
    headers = {"Authorization": f"Bearer {os.environ['SLNG_API_KEY']}"}

    with open("micro-machines.wav", "rb") as audio_file:
        response = requests.post(url, headers=headers, files={"audio": audio_file})

    result = response.json()
    print(result["results"]["channels"][0]["alternatives"][0]["transcript"])
    ```
  </Tab>

  <Tab title="CLI" icon="square-terminal">
    ```bash theme={null}
    voiceai stt micro-machines.wav
    ```
  </Tab>
</Tabs>

The transcript comes back under
`results.channels[0].alternatives[0].transcript`.

## Change the model or parameters

The model is part of the request path. Swap it to change the voice engine or the
language, and keep the rest of the call the same. Prefer a variant under the
`slng/` prefix where one exists: those run on SLNG infrastructure in the region
closest to you, so each call skips the hop to an outside provider.

Each model has its own endpoint and its own parameters, so the field that picks
the voice differs by provider. Fish Audio uses `reference_id`, Deepgram Aura
uses `model`. Fish Audio returns MP3 by default, Deepgram Aura returns WAV.

```bash highlight={2,6,9} theme={null}
# Deepgram Aura instead of Fish Audio S2.1 Pro
curl https://eu-west.api.slng.ai/v1/tts/deepgram/aura:2 \
  -H "Authorization: Bearer $SLNG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "aura-2-thalia-en",
    "text": "Hello from sunny Barcelona!"
  }' \
  --output hello-aura.wav
```

For speech to text, add optional fields to the form to tune the transcript:

* **`language`** sets the recognition language.
* **`diarize=true`** labels each speaker.
* **`punctuate=true`** adds punctuation.

See [WebSockets vs HTTP](/guides/models/websockets-vs-http) for request and
response formats, and the [Unified API guide](/guides/models/unified-api)
for more details.

## Stream in real time

For low-latency, turn-by-turn audio, connect over WebSocket at
`wss://eu-west.api.slng.ai` instead of posting a whole file.

* [Text to speech over WebSocket](/api-reference/text-to-speech/overview)
* [Speech to text over WebSocket](/api-reference/speech-to-text/overview)
* [WebSockets vs HTTP](/guides/models/websockets-vs-http)

## Find other models and API details

* [Which models are available](/guides/models/which-models-are-available) and
  the [model catalog](/models/catalog/all-models), including views by
  [region](/models/catalog/by-region) and
  [language](/models/catalog/by-language).
* [Text to speech API](/api-reference/text-to-speech/overview) and
  [speech to text API](/api-reference/speech-to-text/overview).
* [Authentication](/api-reference/authentication),
  [rate limits](/api-reference/rate-limits), and
  [error codes](/api-reference/error-codes).

## Next steps

* Ready to build a full voice agent instead? See
  [create an agent](/guides/get-started/create-a-project/create-agent).
* Already run an agent elsewhere? See
  [improve an existing agent](/guides/get-started/create-a-project/improve-agent).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.