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

# Speech-to-Text (REST)

> One-shot transcription of complete audio files via HTTP POST

Use the REST endpoint when you have a complete audio file in hand and
want a single HTTP request, no WebSocket to manage. The server reads
the full body, transcribes it, and streams newline-delimited JSON
(NDJSON) messages back as the body.

<Card title="Streaming use case?" icon="waveform-lines" href="/guides/speech-to-text">
  For live audio (microphone, telephony) or to react to VAD and flush
  events in real time, use the SDK streaming guide instead.
</Card>

## Quickstart

<CodeGroup>
  ```python Python theme={null}
  import json
  import requests

  with open("input.wav", "rb") as f:
      audio = f.read()

  with requests.post(
      "https://api.gradium.ai/api/post/speech/asr",
      data=audio,
      headers={
          "x-api-key": "your_api_key",
          "Content-Type": "audio/wav",
      },
      stream=True,
  ) as resp:
      resp.raise_for_status()
      transcript = []
      for line in resp.iter_lines(decode_unicode=True):
          if not line:
              continue
          msg = json.loads(line)
          if msg["type"] == "text":
              transcript.append(msg["text"])
  print(" ".join(transcript))
  ```

  ```bash cURL theme={null}
  curl -L -X POST https://api.gradium.ai/api/post/speech/asr \
    -H "x-api-key: your_api_key" \
    -H "Content-Type: audio/wav" \
    --data-binary @input.wav
  ```
</CodeGroup>

## Response format

The response is `Content-Type: application/x-ndjson`. Each line is a
JSON object with a `type` field, `text` and `end_text` are the ones
you'll typically care about; `error` may appear if the pipeline fails
mid-stream. The body closes when transcription is complete.

For the full message schema, request body, query parameters, and error
shapes, see the [STT POST Endpoint reference](/api-reference/endpoint/stt-post).

## Passing `json_config`

Advanced options (`temp`, `language`, `padding_bonus`, `delay_in_frames`,
and a `keywords` dictionary for [boosting names and jargon](/guides/transcription-settings#keyword-boosting))
are passed as a JSON-encoded string in the `json_config` query
parameter. The example below sends a `language` hint and changes the
adaptive delay:

<CodeGroup>
  ```bash cURL theme={null}
  # json_config = {"language":"en","delay_in_frames":16}
  curl -L -X POST \
    'https://api.gradium.ai/api/post/speech/asr?json_config=%7B%22language%22%3A%22en%22%2C%22delay_in_frames%22%3A16%7D' \
    -H "x-api-key: your_api_key" \
    -H "Content-Type: audio/wav" \
    --data-binary @input.wav
  ```

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

  with open("input.wav", "rb") as f:
      audio = f.read()

  config = {"language": "en", "delay_in_frames": 16}

  with requests.post(
      "https://api.gradium.ai/api/post/speech/asr",
      params={"json_config": json.dumps(config)},  # requests URL-encodes for you
      data=audio,
      headers={
          "x-api-key": "your_api_key",
          "Content-Type": "audio/wav",
      },
      stream=True,
  ) as resp:
      resp.raise_for_status()
      for line in resp.iter_lines(decode_unicode=True):
          if line:
              print(json.loads(line))
  ```
</CodeGroup>

The supported keys, allowed values, and validation rules are documented
in [Transcription Settings](/guides/transcription-settings).

## Next steps

<CardGroup cols={2}>
  <Card title="STT POST API reference" icon="code" href="/api-reference/endpoint/stt-post">
    Full request/response schema, query parameters, content types.
  </Card>

  <Card title="Streaming with the SDK" icon="waveform-lines" href="/guides/speech-to-text">
    Low-latency, microphone-friendly transcription with VAD and flush.
  </Card>
</CardGroup>