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, Realtime, and 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, add, list, and delete phrases as the vocabulary evolves, and to delete the model 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.

For example, creating a model with a few phrases:

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, 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, Realtime, and Turns APIs:

?custom_model_id=<id>

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

Tuning Biasing

The Prerecorded, Realtime, and Turns APIs accept an optional control:

• bias_strength controls how strongly the selected phrases influence transcription. Its default is 0.45; larger values apply stronger biasing.

The default is suitable for most requests. Increase it only when the expected terminology is not being recovered, since stronger biasing can introduce irrelevant terms.

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.

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 instead; they describe the shape of a token rather than a fixed phrase. Note that patterns and phrase biasing are mutually exclusive - patterns cannot be combined with phrases or a custom model.