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

# Speech to text

> Transcribing audio on a dedicated deployment: what to send, what comes back, and what it costs.

`POST /v1/audio/transcriptions` turns a recording into text. It has the shape of OpenAI's
audio transcriptions, so an OpenAI SDK's `audio.transcriptions.create` works by changing
`base_url` alone.

## It runs on a dedicated deployment

Speech-to-text models are offered as [dedicated deployments](https://docs.compute.prentis.ai/models-and-resource-names.md):
create a deployment of a model that transcribes, then send its full name as `model`:

```
accounts/<your-account>/deployments/<your-asr-deployment>
```

A bare model name, or a deployment of a model that does not transcribe, returns
`MODEL_CAPABILITY_UNSUPPORTED`. The other way round is refused too: a speech-to-text
deployment does not answer `/v1/chat/completions`.

## Sending audio

```bash theme={null}
curl https://compute.prentis.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $PRENTIS_API_KEY" \
  -F file=@recording.wav \
  -F model=accounts/<your-account>/deployments/<your-asr-deployment> \
  -F language=en
```

```python theme={null}
import os
from openai import OpenAI

client = OpenAI(base_url="https://compute.prentis.ai/v1", api_key=os.environ["PRENTIS_API_KEY"])

with open("recording.wav", "rb") as f:
    resp = client.audio.transcriptions.create(
        model="accounts/<your-account>/deployments/<your-asr-deployment>",
        file=f,
        language="en",
    )
print(resp.text)
```

| Field | |
| - | - |
| `file` | A WAV file: PCM, 16, 24 or 32-bit, any sample rate, mono or stereo. Up to 25 MB and 10 minutes. |
| `model` | The deployment's full name, as above. |
| `language` | Optional. An ISO-639-1 code such as `en` or `zh`; leave it out and the model detects the language. |
| `prompt` | Optional. Names and terms the recording is likely to contain, which steers spelling. UTF-8 text, up to 64 KB. |
| `temperature` | Optional, 0 to 1. 0 is the usual choice for transcription. |
| `response_format` | `json` (the default) or `text`. |
| `stream` | Optional. `true` streams the text as it is recognised. |

Other formats (mp3, ogg, webm) return `MEDIA_UNSUPPORTED`: convert them to WAV first. A
recording of 16 kHz mono 16-bit PCM — what voice pipelines usually produce — is about
32 KB per second.

## What comes back

With `response_format: json`:

```json theme={null}
{
  "text": "Can you move my three o'clock meeting to Thursday morning?",
  "usage": { "type": "duration", "seconds": 4 }
}
```

`usage.seconds` is the recording's length read from the WAV header, rounded up to whole
seconds. With `response_format: text` the body is the transcript alone, as `text/plain`.

With `stream: true` the answer is `text/event-stream`: one `transcript.text.delta` event per
new piece of text, then a single `transcript.text.done` carrying the whole text and the
usage, which ends the stream. There is no `[DONE]` line — unlike chat streaming.

```
data: {"type":"transcript.text.delta","delta":"Can you move my"}

data: {"type":"transcript.text.delta","delta":" three o'clock meeting to Thursday morning?"}

data: {"type":"transcript.text.done","text":"Can you move my three o'clock meeting to Thursday morning?","usage":{"type":"duration","seconds":4}}
```

## Using it from a voice agent

Pipecat's OpenAI speech-to-text service takes a base URL and a model, which is all it needs:

```python theme={null}
import os
from pipecat.services.openai.stt import OpenAISTTService

stt = OpenAISTTService(
    api_key=os.environ["PRENTIS_API_KEY"],
    base_url="https://compute.prentis.ai/v1",
    model="accounts/<your-account>/deployments/<your-asr-deployment>",
)
```

The API key needs the `audio` operation if you restrict its operations; a key with no
operation restrictions can already call this endpoint.

## Cost

A dedicated deployment is billed for the GPU time it holds, whether or not you send
anything. Transcription calls are not billed on top of that: each one appears on the Usage
and Requests pages with its audio length, at no charge.


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