Model Config

Model configuration options for the Telnyx Speech-to-Text REST API — biasing, hotwords, language hints, and per-request tuning of transcription accuracy.

For the deepgram/* models and reson8/prerecorded. Returns 400 (model_config is only allowed with deepgram models and reson8/prerecorded) if used with other models.

Pass-through to Deepgram’s pre-recorded API query parameters. Every key-value pair in model_config is forwarded directly — Telnyx does not validate individual options.

Commonly Used Options

Option	Type	Description
smart_format	boolean	Capitalization, punctuation, dates, numbers, currency
punctuate	boolean	Add punctuation
diarize	boolean	Speaker identification. Adds speakers to verbose_json segments and speaker / speaker_confidence to each word.
multichannel	boolean	Transcribe each audio channel independently. Adds channel to verbose_json segments. Changes billing — see Multichannel.
utterances	boolean	With multichannel on a multichannel file, split each channel’s segments by utterance and pause; with diarize, segments then align with speaker turns. Ignored for segmentation when smart_format or paragraphs is set (segments follow sentences instead) and on single-channel files.
numerals	boolean	Convert spoken numbers to digits
language	string	Override language. Top-level language param takes precedence.

Example

curl -X POST https://api.telnyx.com/v2/ai/audio/transcriptions \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -F "file=@call-recording.mp3" \
  -F "model=deepgram/nova-3" \
  -F "response_format=verbose_json" \
  -F 'model_config={"smart_format": true, "diarize": true, "punctuate": true}'

model_config can be sent as a JSON string in the multipart form field. The server parses it before forwarding.

Unvalidated Pass-Through

Any Deepgram query parameter can be passed. If Deepgram adds new options, they work immediately without a Telnyx API update. Conversely, invalid keys are forwarded and may cause Deepgram to return an error.

Refer to Deepgram’s API reference for the full list of supported parameters.

Diarization

Set diarize: true to label who speaks each word. Works with all deepgram/* models, including the -medical variants, and with reson8/prerecorded. Other models reject model_config, so they return no speaker information.

Diarization quality depends on the audio. It works best when each speaker has enough speech.

Use diarize, not diarize_model. Telnyx’s Deepgram deployment does not support diarize_model (for example latest or v2) and returns 400 Deepgram API error: Bad Request: Unknown diarization model.

Enabling diarize does not change billing.

Multichannel

Set multichannel: true to transcribe each channel of a multichannel file (for example, a stereo call recording with one party per channel) independently. Deepgram requests accept only mp3 and wav files.

• Each segment gets a channel index, starting at 0. A single-channel file returns no channel field.
• Segments from all channels are merged into one segments list, ordered by start.
• Silent channels produce no segments, but are still billed: billing counts every channel in the file.
• Without multichannel, a stereo file is mixed down and transcribed as one channel.

Billing: billed duration is the file duration multiplied by the number of channels. A 73.17 s stereo file with multichannel: true bills 146 s. Without multichannel, the same file bills once.

Combine with diarization

diarize and multichannel combine. Speaker IDs are per channel: each channel numbers its speakers from 0. Identify a speaker by the pair (channel, speaker), never by speaker alone.

curl -X POST https://api.telnyx.com/v2/ai/audio/transcriptions \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -F "file=@call.wav" \
  -F "model=deepgram/nova-3" \
  -F "language=en" \
  -F "response_format=verbose_json" \
  -F 'model_config={"multichannel": true, "diarize": true, "utterances": true}'

Response (trimmed):

{
  "text": "inquired shaggy in the metal forest asparagus salad ...",
  "duration": 73.17,
  "segments": [
    {
      "id": 0,
      "start": 0.08,
      "end": 1.6,
      "text": "inquired shaggy",
      "channel": 0,
      "speakers": [0],
      "words": [
        {"word": "inquired", "start": 0.08, "end": 0.72, "confidence": 0.89, "speaker": 0, "speaker_confidence": 1.0},
        {"word": "shaggy", "start": 0.72, "end": 1.6, "confidence": 0.85, "speaker": 0, "speaker_confidence": 1.0}
      ]
    },
    {
      "id": 2,
      "start": 4.64,
      "end": 6.16,
      "text": "asparagus salad",
      "channel": 1,
      "speakers": [0],
      "words": [
        {"word": "asparagus", "start": 4.64, "end": 5.36, "confidence": 0.99, "speaker": 0, "speaker_confidence": 1.0},
        {"word": "salad", "start": 5.36, "end": 6.16, "confidence": 0.99, "speaker": 0, "speaker_confidence": 1.0}
      ]
    },
    {
      "id": 4,
      "start": 10.96,
      "end": 15.28,
      "text": "to him the presence or absence of his wife's sister was a matter of indifference",
      "channel": 0,
      "speakers": [1],
      "words": [
        {"word": "to", "start": 10.96, "end": 11.2, "confidence": 1.0, "speaker": 1, "speaker_confidence": 1.0}
      ]
    },
    {
      "id": 5,
      "start": 16.82,
      "end": 19.93,
      "text": "however a little later we had a comfortable chat",
      "channel": 1,
      "speakers": [1],
      "words": [
        {"word": "however", "start": 16.82, "end": 17.54, "confidence": 1.0, "speaker": 1, "speaker_confidence": 0.76}
      ]
    }
  ]
}

Segment 0 and segment 2 both have speakers: [0], but they are different people: speaker 0 on channel 0 and speaker 0 on channel 1. See Response Format for every field.

Reson8

reson8/prerecorded accepts only these two options. Any other key returns a 400.

Option	Type	Description
diarize	boolean	Speaker identification. verbose_json returns one segment per speaker turn, with speakers on each segment and speaker on each word.
max_speakers	integer	Upper bound on the number of speakers, from 1 to 8. Used with diarize; Reson8 picks the count itself when omitted.

curl -X POST https://api.telnyx.com/v2/ai/audio/transcriptions \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -F "file=@call-recording.wav" \
  -F "model=reson8/prerecorded" \
  -F "response_format=verbose_json" \
  -F 'model_config={"diarize": true, "max_speakers": 2}'

Response (trimmed):

{
  "text": "Hi, I'm calling about the invoice I received last week. Of course, could you tell me the account number on that invoice? ...",
  "duration": 32.78,
  "segments": [
    {
      "id": 0,
      "start": 0.64,
      "end": 4.08,
      "text": "Hi, I'm calling about the invoice I received last week.",
      "speakers": [0],
      "words": [
        {"word": "Hi,", "start": 0.64, "end": 0.96, "speaker": 0},
        {"word": "I'm", "start": 1.0, "end": 1.36, "speaker": 0}
      ]
    },
    {
      "id": 1,
      "start": 4.56,
      "end": 8.16,
      "text": "Of course, could you tell me the account number on that invoice?",
      "speakers": [1],
      "words": [
        {"word": "Of", "start": 4.56, "end": 4.72, "speaker": 1},
        {"word": "course,", "start": 4.72, "end": 5.04, "speaker": 1}
      ]
    }
  ]
}

Without diarize, verbose_json returns the whole transcript as one segment with its word timestamps.