# Custom Models

A custom model is a named collection of phrases that biases transcription toward domain-specific vocabulary, such as product names, technical terms, or internal jargon.

Custom models are available on the [Prerecorded](/speech-to-text/prerecorded/), [Realtime](/speech-to-text/realtime/), and [Turns](/speech-to-text/turns/) APIs.

## Creating a Model

There are two ways to create a custom model:

- **Through the API**, by specifying the phrases yourself. See the API reference to [create a model](/api/custom-model/create/), [add](/api/custom-model/phrases/add/), [list](/api/custom-model/phrases/list/), and [delete phrases](/api/custom-model/phrases/delete/) as the vocabulary evolves, and to [delete the model](/api/custom-model/delete/) once you no longer need it.
- **Through the console**, by providing a prompt, files, and some context about your use case. A model is then created for you based on that input. See the [console](https://console.reson8.dev).

For example, creating a model with a few phrases:

```bash
curl -X POST "https://api.reson8.dev/v1/custom-model" \
  -H "Authorization: ApiKey <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cardiology",
    "description": "Cardiology terms and abbreviations",
    "phrases": ["myocardial infarction", "atrial fibrillation", "echocardiogram"]
  }'
```

Models created through the console also show up in the API, so they can be inspected and managed there like any other model.

When possible, we recommend the API: it gives exact control over the phrase list and lets you manage it programmatically as your vocabulary evolves. There is no limit on the number of custom models you can create.

## Per-Request Phrases

For a small number of phrases, you don't need a custom model at all: pass them directly with the request via the `phrases` query parameter, available on all three APIs. This is limited to 250 phrases per request - use a custom model when the vocabulary is larger or reused across requests.

## Using a Model

A custom model can be applied in two ways:

- **Configured on an API client** in the [console](https://console.reson8.dev), so every request made with that client uses the model by default.
- **Passed per request**, via the `custom_model_id` query parameter on the [Prerecorded](/speech-to-text/prerecorded/), [Realtime](/speech-to-text/realtime/), and [Turns](/speech-to-text/turns/) APIs:

```
?custom_model_id=<id>
```

When both are set, the query parameter takes priority over the model configured on the API client.

## Choosing Phrases

Good phrases are the terms the base model gets wrong: specialised vocabulary, uncommon names, brand and product names. Everyday words are already recognised well and only dilute the model. A model can currently hold at most 50,000 phrases; we expect to raise this limit over time.

:::caution[Keep phrases focused]
Biasing improves accuracy on audio that contains the phrases, but a large set of irrelevant ones can **degrade** transcription.
:::

For short structured tokens like order codes and licence plates, use [Patterns](/speech-to-text/features/patterns/) instead; they describe the shape of a token rather than a fixed phrase.