Audio

Transcribe speech to text

Changed on

Transcribe speech to text. This endpoint is consistent with the OpenAI Transcription API and may be used with the OpenAI JS or Python SDK.

post/ai/audio/transcriptions

Request

  • Base URL: https://api.telnyx.com/v2
  • URL: https://api.telnyx.com/v2/ai/audio/transcriptions
  • Auth: HTTP bearer

Request body multipart/form-data

filestring binary

The audio file object to transcribe, in one of these formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm. File uploads are limited to 100 MB. Cannot be used together with file_url. Note: the deepgram/* models only support mp3 and wav formats.

file_urlstring

Link to audio file in one of these formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm. Support for hosted files is limited to 100MB. Cannot be used together with file. Note: the deepgram/* models only support mp3 and wav formats.

model'distil-whisper/distil-large-v2' | 'openai/whisper-large-v3-turbo' | 'deepgram/nova-2' | 'deepgram/nova-2-medical' | 'deepgram/nova-3' | 'deepgram/nova-3-medical' | 'nvidia/parakeet-v3' | 'omi-health/omi-med-stt-v1' | 'reson8/prerecorded' required

ID of the model to use. distil-whisper/distil-large-v2 is lower latency but English-only. openai/whisper-large-v3-turbo is multi-lingual but slightly higher latency. The deepgram/* models only accept mp3/wav files: deepgram/nova-3 covers ~49 languages plus multi and deepgram/nova-2 covers ~33, while the -medical variants are tuned for clinical vocabulary and accept English only (en and its regional variants, e.g. en-US, en-GB). nvidia/parakeet-v3 is multilingual with automatic language detection; omi-health/omi-med-stt-v1 is a medical model, English only. reson8/prerecorded covers 10 languages, returns word timestamps, and labels speakers via model_config.

response_format'json' | 'verbose_json'

The format of the transcript output. Use verbose_json to take advantage of timestamps.

timestamp_granularities[]'segment'

The timestamp granularities to populate for this transcription. response_format must be set verbose_json to use timestamp granularities. Currently segment is supported.

languagestring

The language of the audio to be transcribed. deepgram/nova-3 supports ~49 languages plus multi, and deepgram/nova-2 supports ~33 plus multi; the -medical variants are English only (en and its regional variants, e.g. en-US, en-GB). Deepgram models validate on the base language and forward the full tag, so regional variants such as de-CH and pt-BR are accepted where the base language is supported; an unsupported language returns a 400. For openai/whisper-large-v3-turbo, supports multiple languages. distil-whisper/distil-large-v2 does not support language parameter. nvidia/parakeet-v3 detects the language automatically; omi-health/omi-med-stt-v1 is English only. reson8/prerecorded accepts nl, en, fr, fy, de, it, pl, pt, es and sv (regional variants are transcribed as the base language) and detects the language when it is omitted.

model_configobject

Additional model-specific configuration parameters. Only allowed with the deepgram/* models and reson8/prerecorded. Sent as a JSON string in multipart requests; for the deepgram/* models it is passed through to Deepgram as query parameters, while reson8/prerecorded accepts only diarize (speaker labels) and max_speakers (1 to 8). Any other model with model_config returns 400. Can include Deepgram-specific options such as smart_format, punctuate, diarize (speaker labels), multichannel (transcribe each channel independently; billed duration is file duration multiplied by the number of channels), utterances, numerals, and language. If language is provided both as a top-level parameter and in model_config, the top-level parameter takes precedence.

Example request

{
  "file_url": "https://example.com/file.mp3",
  "model": "distil-whisper/distil-large-v2",
  "response_format": "json",
  "timestamp_granularities[]": "segment",
  "language": "en-US",
  "model_config": {
    "smart_format": true,
    "punctuate": true
  }
}

Response

Successful Response

textstring required

The transcribed text for the audio file.

durationnumber

The duration of the audio file in seconds. Returned by distil-whisper/distil-large-v2 and the deepgram/* models when response_format is verbose_json. Not returned by openai/whisper-large-v3-turbo.

Changes