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

# Overview

> How the Realtime Transcription API streams audio over WebSocket and returns live transcripts and translations, how it works, who can use it, and its limits.

Enterprise The Realtime Transcription API is available to Enterprise plan customers on request. It is not open to every workspace. Tiro must enable the API for your workspace before you can call it.

## What does the Realtime Transcription API do?

The Realtime Transcription API takes the audio your app sends and returns transcripts as you speak. If you set a translation language when you create the session, you also receive translations.

Results arrive only as WebSocket messages. Tiro does not create notes from this API and does not keep the audio it receives. No API returns the transcript or translation text later, so store the results you need on your side.

## How does it work?

You create a session over REST, then send audio and receive results over WebSocket. Keep the API key on your server, and pass the client only the `streamToken` issued for each session.

```mermaid theme={"system"}
sequenceDiagram
    participant S as Your server
    participant C as Your client
    participant R as Tiro REST API
    participant W as Tiro WebSocket

    S->>R: POST /v1/external/realtime-transcriptions (API Key)
    R-->>S: 201 {id, wsUrl, streamToken}
    S->>C: Pass wsUrl and streamToken
    C->>W: Connect to wsUrl (Authorization: Bearer streamToken)
    W-->>C: session.started
    loop While recording
        C->>W: PCM audio (binary frames)
        W-->>C: transcript, translation
    end
    C->>W: session.end
    W-->>C: Remaining transcript, translation (isFinal: true)
    W-->>C: session.ended, then close 1000
```

| Step | What happens | Details |
| - | - | - |
| 1. Create a session | Your server creates a session with an API key and receives `wsUrl` and `streamToken` | [API reference](https://docs.tiro.ooo/api-reference/realtime-transcription/create-realtime-transcription.md) |
| 2. Connect | The client puts `streamToken` in the `Authorization` header and connects to `wsUrl` | [Connection](https://docs.tiro.ooo/en/developers/realtime-transcription/protocol.md#handshake) |
| 3. Send audio and receive results | Send 16 kHz mono PCM and receive `transcript` and `translation` messages | [Messages](https://docs.tiro.ooo/en/developers/realtime-transcription/protocol.md#messages) |
| 4. End | Send `session.end`. Tiro sends the remaining results and closes the session | [Ending](https://docs.tiro.ooo/en/developers/realtime-transcription/protocol.md#ending) |

If the connection drops while the session is still open, reconnect with the same token to continue. The rules are in [Reconnecting](https://docs.tiro.ooo/en/developers/realtime-transcription/protocol.md#reconnect).

## Who can use it?

You can create a session only when all three of these are true.

| Requirement | If not met |
| - | - |
| You have an Enterprise plan contract, and Tiro has enabled the Realtime Transcription API for the workspace. To get access, contact us with the button below | `403` `realtime_api_not_enabled` |
| You use an API key bound to the workspace. This means a workspace API key, or an account API key bound to the workspace. With an account API key, the key owner must be a member of that workspace | `403` `workspace_bound_key_required` or `workspace_access_denied` |
| A key with scopes has the scope it needs. Creating and ending sessions needs `realtime_transcription:write`, and getting and listing them needs `realtime_transcription:read`. `write` includes `read` | `403` `insufficient_scope` |

Organization API keys and OAuth access tokens cannot call this API. See [Authentication](https://docs.tiro.ooo/en/developers/fundamentals/authentication.md) for details on scopes.

## What are the limits?

| Item | Value | When exceeded |
| - | - | - |
| Concurrent sessions | 10 `OPEN` sessions per workspace, counted across all API keys and users | Creating a session fails with `409` `concurrent_transcription_limit` |
| No audio | 15 minutes, counted from session creation or the last audio frame | The session ends with `IDLE_TIMEOUT` |
| Maximum session length | 3 hours, counted from the first connection, including time spent disconnected | The session ends with `MAX_DURATION` |
| Audio format | 16,000 Hz, mono, signed 16-bit little-endian PCM | Tiro closes the connection on an odd-length frame |
| Audio frame size | Up to 6,400 bytes (200 ms). 3,200 bytes (100 ms) recommended | Tiro closes the connection |
| Audio lead | You can send audio up to 60 seconds ahead of real time | Tiro closes the connection with close `4029`. Wait, then reconnect |
| REST calls | 600 per 60 seconds per API key | You get `429` with `Retry-After` |

> [!WARNING]
>
> When you finish, send `session.end` or call `POST /v1/external/realtime-transcriptions/{id}/end`. If you only close the WebSocket connection, the session stays `OPEN`. It holds one concurrent session slot until it ends automatically after 15 minutes without audio, and cleanup can take up to about 3 more minutes.

## Which languages are supported?

Transcription and translation both support the 17 locales in [Supported locales](https://docs.tiro.ooo/en/developers/fundamentals/supported-locales.md). If you omit `transcriptionLocale` or send `AUTO` when you create the session, Tiro detects the spoken language. `translationLocale` takes one locale and does not support auto detection.

Translations do not pair 1:1 with source sentences. Show translation pieces joined in the order they arrive. The rules are in [`translation` message](https://docs.tiro.ooo/en/developers/realtime-transcription/protocol#translation).

## What does this API not provide?

This version does not provide the following.

* Speaker labels, or word and sentence timestamps
* Note creation and webhooks
* Audio storage and server-side resend. The client must buffer audio while disconnected and send it again
* Direct browser connections. The browser WebSocket API cannot send the `Authorization` header, so connect from a server or a native app

## How is usage recorded?

Tiro records the audio length and connection time of each session. Check the received audio length in `audioDurationMs` on the session response and the `session.ended` message. This usage does not count toward note recording usage or the workspace usage limit. Pricing is set in your Enterprise contract.

## Next steps

> [card] [Quickstart](https://docs.tiro.ooo/en/developers/realtime-transcription/quickstart.md)
>
> Create a session, send an audio file, and receive the results.

> [card] [WebSocket protocol](https://docs.tiro.ooo/en/developers/realtime-transcription/protocol.md)
>
> Check message fields, reconnection, errors, and close codes.

Enterprise Plan

This feature is available on the Enterprise plan.  Our sales team will help design the security setup your organization needs.

[Contact sales](https://tiro.ax/en/contact?utm_source=docs\&utm_medium=plan_callout\&utm_campaign=plan_upsell_enterprise\&utm_content=developers-realtime-transcription-overview)


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