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

# Openai

> Python API reference for the openai speech-to-text plugin.

<Card title="Usage guide" icon="book" href="/plugins/stt/openai" horizontal>
  Setup, environment variables, and Python/JavaScript/Go usage examples.
</Card>

## OpenAISTT

Streaming speech-to-text via OpenAI's transcription API.

Uses the `gpt-4o-transcribe` family (or `whisper-1`) with server-side VAD turn
detection and optional input noise reduction.

### Constructor

```python theme={null}
OpenAISTT(*, api_key: 'Optional[str]' = None, model: 'OpenAISTTModel | str' = 'gpt-4o-transcribe', language: 'str' = 'en', stream: 'bool' = True, input_sample_rate: 'int' = 48000, output_sample_rate: 'int' = 24000, prompt: 'Optional[str]' = None, turn_detection: 'str' = 'server_vad', vad_threshold: 'Optional[float]' = None, vad_prefix_padding_ms: 'Optional[int]' = None, vad_silence_duration_ms: 'Optional[int]' = None, noise_reduction: 'Optional[str]' = 'near_field', response_format: 'str' = 'json', base_url: 'Optional[str]' = None, **kwargs: 'Any') -> 'None'
```

<ParamField path="api_key" type="Optional[str]">
  OpenAI API key. Falls back to `OPENAI_API_KEY`.
</ParamField>

<ParamField path="model" type="OpenAISTTModel | str" default="gpt-4o-transcribe">
  Transcription model: `gpt-4o-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-transcribe-diarize` or `whisper-1`. Default `"gpt-4o-transcribe"`.
</ParamField>

<ParamField path="language" type="str" default="en">
  ISO-639-1 language code (e.g. `"en"`). Default `"en"`.
</ParamField>

<ParamField path="stream" type="bool" default="True">
  Stream partial transcripts as the caller speaks. Default True.
</ParamField>

<ParamField path="input_sample_rate" type="int" default="48000">
  Input rate in Hz. Default 48000.
</ParamField>

<ParamField path="output_sample_rate" type="int" default="24000">
  Resampled rate sent to the model in Hz. Default 24000.
</ParamField>

<ParamField path="prompt" type="Optional[str]">
  Optional text prompt to bias vocabulary/style.
</ParamField>

<ParamField path="turn_detection" type="str" default="server_vad">
  VAD mode: `"server_vad"` or `"semantic_vad"`. Default `"server_vad"`.
</ParamField>

<ParamField path="vad_threshold" type="Optional[float]">
  Speech-detection sensitivity, 0.0–1.0. Default None.
</ParamField>

<ParamField path="vad_prefix_padding_ms" type="Optional[int]">
  Audio kept before detected speech, in ms. Default None.
</ParamField>

<ParamField path="vad_silence_duration_ms" type="Optional[int]">
  Silence before end-of-turn, in ms. Default None.
</ParamField>

<ParamField path="noise_reduction" type="Optional[str]" default="near_field">
  Input denoising profile: `"near_field"`, `"far_field"` or None to disable. Default `"near_field"`.
</ParamField>

<ParamField path="response_format" type="str" default="json">
  Transcript format (`"json"`, `"text"`, …). Default `"json"`.
</ParamField>

<ParamField path="base_url" type="Optional[str]">
  Override the OpenAI API base URL.
</ParamField>

### aclose

```python theme={null}
def aclose(self) -> 'None'
```

Release any resources held by the provider.

### emit

```python theme={null}
def emit(self, event: 'T', *args: 'Any') -> 'None'
```

Emit an event, invoking all registered handlers with the given arguments.

Handlers are called in registration order. Coroutine handlers are
scheduled on the running event loop. If the emitter is closed, the call
is a no-op.

<ParamField path="event" type="T" required>
  The event to emit.
</ParamField>

### off

```python theme={null}
def off(self, event: 'T', callback: 'Callable[..., Any]') -> 'None'
```

Remove a previously registered handler for an event.

If the handler is not registered for the event, the call is a no-op.

<ParamField path="event" type="T" required>
  The event the handler was registered for.
</ParamField>

<ParamField path="callback" type="Callable[..., Any]" required>
  The handler to remove.
</ParamField>

### on

```python theme={null}
def on(self, event: 'T', callback: 'Callable[..., Any] | None' = None) -> 'Callable[..., Any]'
```

Register a handler for an event.

Can be used directly by passing a callback, or as a decorator when
`callback` is omitted.

<ParamField path="event" type="T" required>
  The event to listen for.
</ParamField>

<ParamField path="callback" type="Callable[..., Any] | None">
  The handler to invoke when the event is emitted. If `None`, a decorator is returned that registers the decorated function.
</ParamField>

<ResponseField name="returns" type="Callable[..., Any]">
  The registered callback when `callback` is provided, otherwise a decorator that registers and returns the function it wraps.
</ResponseField>

### on\_stt\_transcript

```python theme={null}
def on_stt_transcript(self, callback: 'Callable[[STTResponse], Awaitable[None]]') -> 'None'
```

Register the coroutine invoked when a transcription event is produced.

<ParamField path="callback" type="Callable[[STTResponse], Awaitable[None]]" required>
  An async callable that receives each `STTResponse`.
</ParamField>

### process\_audio

```python theme={null}
def process_audio(self, audio_frames: 'bytes', language: 'Optional[str]' = None, **kwargs: 'Any') -> 'None'
```

Process a chunk of audio for transcription.

Implementations should consume the audio frames and emit transcription
results through the registered transcript callback.

<ParamField path="audio_frames" type="bytes" required>
  Raw audio bytes to transcribe.
</ParamField>

<ParamField path="language" type="Optional[str]">
  Optional language code to guide recognition.
</ParamField>

### stream\_transcribe

```python theme={null}
def stream_transcribe(self, audio_stream: 'AsyncIterator[bytes]', **kwargs: 'Any') -> 'AsyncIterator[STTResponse]'
```

Transcribe a continuous audio stream.

<ParamField path="audio_stream" type="AsyncIterator[bytes]" required>
  An async iterator yielding raw audio byte chunks.
</ParamField>

<ResponseField name="returns" type="AsyncIterator[STTResponse]">
  STTResponse: Transcription events produced as audio is consumed.
</ResponseField>

***

## OpenAISTTModel

```python theme={null}
OpenAISTTModel = typing.Literal['gpt-4o-transcribe', 'gpt-4o-mini-transcribe', 'gpt-4o-transcribe-diarize', 'whisper-1']
```