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

# Speech-to-text HTTP examples

> Code samples in curl, Python, and Node.js for basic transcription, word timestamps, and diarization.

export const AudioPlayer = ({src, title = "Audio", description, autoPlay = false, loop = false, variant = "default"}) => {
  const audioId = useId();
  const isCompact = variant === "compact";
  const audioRef = useRef(null);
  const [isPlaying, setIsPlaying] = useState(false);
  const togglePlayback = () => {
    const audio = audioRef.current;
    if (!audio) return;
    if (audio.paused) {
      void audio.play();
      setIsPlaying(true);
      return;
    }
    audio.pause();
    setIsPlaying(false);
  };
  return <div className={`audio-player ${isCompact ? "compact" : ""}`}>
      {!isCompact && <div className="meta">
          <div className="titles">
            <div className="title">{title}</div>
            {description && <div className="description">{description}</div>}
          </div>

          <a className="download" href={src} download>
            Download
          </a>
        </div>}

      {isCompact ? <>
          <button type="button" className="compact-button" onClick={togglePlayback} aria-label={isPlaying ? "Pause audio sample" : "Play audio sample"}>
            <span className="compact-icon" aria-hidden="true">
              {isPlaying ? "❚❚" : "▶"}
            </span>
          </button>
          <audio id={audioId} ref={audioRef} preload="metadata" loop={loop} autoPlay={autoPlay} aria-label={title} src={src} onEnded={() => setIsPlaying(false)}>
            Your browser does not support the audio element.
          </audio>
        </> : <audio id={audioId} className="audio-control" controls preload="metadata" loop={loop} autoPlay={autoPlay} aria-label={title} src={src}>
          Your browser does not support the audio element.
        </audio>}
    </div>;
};

These examples use the Deepgram Nova model; see the [Speech-to-Text models](/models/stt) for other models and endpoints.

## Placeholders

The snippets below use these placeholders. Replace them before running the code.

| Placeholder    | Replace with                                                          |
| -------------- | --------------------------------------------------------------------- |
| `SLNG_API_KEY` | An SLNG key from [app.slng.ai/api-keys](https://app.slng.ai/api-keys) |

## Basic File Transcription

Upload an audio file (MP3, WAV, FLAC, OGG, M4A, or WebM) and get back the transcribed text. Here is a sample file you can use:

<AudioPlayer src="/audio/micro-machines.wav" title="Micro Machines sample" description="Download this file to try the example below." />

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.slng.ai/v1/stt/slng/deepgram/nova:3-en \
    -H "Authorization: Bearer SLNG_API_KEY" \
    -F "audio=@micro-machines.wav"
  ```

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

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

  const result = await response.json();
  console.log("Transcription:", result.results.channels[0].alternatives[0].transcript);
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.slng.ai/v1/stt/slng/deepgram/nova:3-en"
  headers = {"Authorization": "Bearer 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("Transcription:", result["results"]["channels"][0]["alternatives"][0]["transcript"])
  ```
</CodeGroup>

You should get a response like this:

```json theme={null}
{
  "metadata": {
    "request_id": "e5fed572-6eac-4b70-81f3-21ba1641dd12",
    "duration": 29.888374,
    "channels": 1,
    "model_info": {
      "1abfe86b-e047-4eed-858a-35e5625b41ee": {
        "name": "2-general-nova",
        "version": "2024-01-06.5664",
        "arch": "nova-2"
      }
    }
  },
  "results": {
    "channels": [
      {
        "alternatives": [
          {
            "transcript": "is the micro machine man presenting the most midget miniature motocator of micro machine...",
            "confidence": 0.9823751,
            "words": [
              { "word": "is", "start": 0.16, "end": 0.32, "confidence": 0.998 },
              { "word": "the", "start": 0.32, "end": 0.40, "confidence": 0.613 },
              { "word": "micro", "start": 0.40, "end": 0.64, "confidence": 0.727 },
              ...
            ]
          }
        ]
      }
    ]
  }
}
```

***

## Going further

You can pass additional form fields to customize the transcription:

* **Language**: If you know the language, pass `language=en` (or `es`, `fr`, etc.). Not all models auto-detect, so setting this explicitly can improve accuracy.
* **Diarization**: Pass `diarize=true` to identify different speakers in a multi-speaker recording. The response will include a `speaker` field on each word. PLease check the models documentation for specific diarization config.
* **Punctuation**: Pass `punctuate=true` to add punctuation to the transcript automatically.

For the full parameter list per model, see the [Speech-to-Text API reference](/api-reference/stt/deepgram-nova-3/nova-3-ws).

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Live STT demo" icon="play" href="https://slng-stt-demo.onrender.com/">
    Try real-time speech recognition in your browser, no setup needed
  </Card>

  <Card title="STT WebSocket examples" icon="bolt" href="/examples/stt-websocket">
    Real-time transcription as users speak
  </Card>

  <Card title="Speech-to-Text models" icon="ear" href="/models/stt">
    Browse all STT models and endpoints
  </Card>

  <Card title="STT API reference" icon="code-xml" href="/api-reference/stt/deepgram-nova-3/nova-3-ws">
    Endpoint-specific parameters
  </Card>
</CardGroup>