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

# Custom vocabulary

> Give speech recognition the names, brands and terms your callers say (keyterms), for voice agents, POST /stt/transcribe and WS /ws/stt

Some words are rare enough that recognition gets them almost right: a surname heard as a common word, a product name split in two. Custom vocabulary (`keyterms`) is a list of the words you expect. When what Lokutor hears is close to one of them, it writes your spelling.

It works on voice agents (web and phone calls), on `POST /stt/transcribe` and on live `WS /ws/stt` streams.

## Voice agents

In the [dashboard](https://app.lokutor.com), open the agent → **Identity** → **Custom words**, and list the terms one per line or separated by commas: your business name, the people callers ask for, products, streets. They apply to every call to that agent from the next call on.

## `POST /stt/transcribe`

Add `keyterms` to the request, as a list of strings or one comma-separated string. With a file upload, send a `keyterms` form field with the comma-separated form.

```json theme={null}
{
  "audio": "<base64 WAV>",
  "format": "wav",
  "language": "es",
  "keyterms": ["Etxeberria", "Invisalign", "Clínica Sol"]
}
```

```bash theme={null}
curl -X POST https://api.lokutor.com/stt/transcribe \
  -H "Authorization: Bearer $LOKUTOR_API_KEY" \
  -F "audio=@recording.wav" \
  -F "language=es" \
  -F "keyterms=Etxeberria, Invisalign, Clínica Sol"
```

## `WS /ws/stt`

Put `keyterms` in the first JSON message. They apply to every partial and final transcript of that stream:

```json theme={null}
{"language": "es", "keyterms": ["Etxeberria", "Invisalign"]}
```

With the SDKs, pass `keyterms` to `STTClient.transcribe` and to `SpeechToTextClient` ([Speech-to-Text](/sdk/stt)).

## Limits and behaviour

* Up to **100** terms of up to **40** characters each. Repeats (ignoring case) and empty entries are dropped. More than that answers `400` `validation.invalid_request_format` on the API.
* A term is matched against what was heard across up to three words, so a name heard in pieces is put back together ("su bizarreta" becomes "Zubizarreta") and written in your spelling and casing. Terms of several words ("Clínica Sol") work the same way.
* At least one of the words heard must be uncommon in the language, so everyday speech is left as it was said: a keyterm cannot turn "el locutor de radio" into your product name.
* All nine recognised languages. Without `language` the language is detected and the keyterms apply to it; sending the language is still best for one-word replies.
* No extra charge.


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