> ## 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] [Streaming use case?](https://docs.gradium.ai/guides/speech-to-text.md)
>
> For live audio (microphone, telephony) or to react to VAD and flush
> events in real time, use the SDK streaming guide instead.

## Quickstart

```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",
    params={"json_config": json.dumps({"language": "en"})},
    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 \
  --url-query 'json_config={"language":"en"}' \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: audio/wav" \
  --data-binary @input.wav
```

## 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](https://docs.gradium.ai/api-reference/endpoint/stt-post.md).

## Passing `json_config`

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

```bash cURL theme={null}
curl -L -X POST https://api.gradium.ai/api/post/speech/asr \
  --url-query 'json_config={"language":"en","delay_in_frames":16}' \
  -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))
```

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

## Next steps

> [card] [STT POST API reference](https://docs.gradium.ai/api-reference/endpoint/stt-post.md)
>
> Full request/response schema, query parameters, content types.

> [card] [Streaming with the SDK](https://docs.gradium.ai/guides/speech-to-text.md)
>
> Low-latency, microphone-friendly transcription with VAD and flush.


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