Transcribe speech to text

POST

audio

transcriptions

JavaScript

import fs from 'fs';
import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const response = await client.ai.audio.transcribe({ model: 'distil-whisper/distil-large-v2' });

console.log(response.text);

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
response = client.ai.audio.transcribe(
    model="distil-whisper/distil-large-v2",
)
print(response.text)

package main

import (
	"context"
	"fmt"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	response, err := client.AI.Audio.Transcribe(context.TODO(), telnyx.AIAudioTranscribeParams{
		Model: telnyx.AIAudioTranscribeParamsModelDistilWhisperDistilLargeV2,
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", response.Text)
}

package com.telnyx.sdk.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.ai.audio.AudioTranscribeParams;
import com.telnyx.sdk.models.ai.audio.AudioTranscribeResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        AudioTranscribeParams params = AudioTranscribeParams.builder()
            .model(AudioTranscribeParams.Model.DISTIL_WHISPER_DISTIL_LARGE_V2)
            .build();
        AudioTranscribeResponse response = client.ai().audio().transcribe(params);
    }
}

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Telnyx\Client;
use Telnyx\Core\FileParam;
use Telnyx\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

try {
  $response = $client->ai->audio->transcribe(
    model: 'distil-whisper/distil-large-v2',
    file: FileParam::fromString('Example data', filename: uniqid('file-upload-', true)),
    fileURL: 'https://example.com/file.mp3',
    language: 'en-US',
    modelConfig: ['smart_format' => 'bar', 'punctuate' => 'bar'],
    responseFormat: 'json',
    timestampGranularities: 'segment',
  );

  var_dump($response);
} catch (APIException $e) {
  echo $e->getMessage();
}

curl --request POST \
  --url https://api.telnyx.com/v2/ai/audio/transcriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form model=distil-whisper/distil-large-v2 \
  --form file=@example-file \
  --form file_url=https://example.com/file.mp3 \
  --form response_format=json \
  --form 'timestamp_granularities[]=segment' \
  --form language=en-US \
  --form 'model_config={
  "smart_format": true,
  "punctuate": true
}'

{
  "text": "string",
  "duration": 0,
  "segments": [
    {
      "id": 0,
      "start": 0,
      "end": 0,
      "text": "string"
    }
  ],
  "words": [
    {
      "word": "string",
      "start": 0,
      "end": 0,
      "confidence": 0,
      "speaker": 0
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "body",
        "name"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

multipart/form-data

model

enum<string>

default:distil-whisper/distil-large-v2

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.

Available options:

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

Example:

"distil-whisper/distil-large-v2"

file

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_url

string

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.

Example:

"https://example.com/file.mp3"

response_format

enum<string>

default:json

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

Available options:

json,

verbose_json

Example:

"json"

timestamp_granularities[]

enum<string>

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

Available options:

segment

Example:

"segment"

language

string

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.

Example:

"en-US"

model_config

object

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:

{ "smart_format": true, "punctuate": true }

Response

Successful Response

Response fields vary by model. distil-whisper/distil-large-v2 returns text, duration, and segments in verbose_json mode. openai/whisper-large-v3-turbo returns text only. The deepgram/* models return text and, depending on model_config, may include words with per-word timestamps and speaker labels. The Parakeet models (nvidia/parakeet-v3, omi-health/omi-med-stt-v1) return text only. reson8/prerecorded returns text and, in verbose_json mode, duration and segments with words; with diarize, one segment per speaker turn with speaker labels.

text

string

required

The transcribed text for the audio file.

duration

number

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.

segments

object[]

Segments of the transcribed text and their corresponding details. Returned by distil-whisper/distil-large-v2 and the deepgram/* models when response_format is verbose_json; Deepgram segments also carry nested words and speakers. Not returned by openai/whisper-large-v3-turbo.

Show child attributes

words

object[]

Word-level timestamps and optional speaker labels. Only returned by the deepgram/* models when word-level output is enabled via model_config.

Show child attributes

JavaScript

import fs from 'fs';
import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const response = await client.ai.audio.transcribe({ model: 'distil-whisper/distil-large-v2' });

console.log(response.text);

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
response = client.ai.audio.transcribe(
    model="distil-whisper/distil-large-v2",
)
print(response.text)

package main

import (
	"context"
	"fmt"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	response, err := client.AI.Audio.Transcribe(context.TODO(), telnyx.AIAudioTranscribeParams{
		Model: telnyx.AIAudioTranscribeParamsModelDistilWhisperDistilLargeV2,
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", response.Text)
}

package com.telnyx.sdk.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.ai.audio.AudioTranscribeParams;
import com.telnyx.sdk.models.ai.audio.AudioTranscribeResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        AudioTranscribeParams params = AudioTranscribeParams.builder()
            .model(AudioTranscribeParams.Model.DISTIL_WHISPER_DISTIL_LARGE_V2)
            .build();
        AudioTranscribeResponse response = client.ai().audio().transcribe(params);
    }
}

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Telnyx\Client;
use Telnyx\Core\FileParam;
use Telnyx\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

try {
  $response = $client->ai->audio->transcribe(
    model: 'distil-whisper/distil-large-v2',
    file: FileParam::fromString('Example data', filename: uniqid('file-upload-', true)),
    fileURL: 'https://example.com/file.mp3',
    language: 'en-US',
    modelConfig: ['smart_format' => 'bar', 'punctuate' => 'bar'],
    responseFormat: 'json',
    timestampGranularities: 'segment',
  );

  var_dump($response);
} catch (APIException $e) {
  echo $e->getMessage();
}

curl --request POST \
  --url https://api.telnyx.com/v2/ai/audio/transcriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form model=distil-whisper/distil-large-v2 \
  --form file=@example-file \
  --form file_url=https://example.com/file.mp3 \
  --form response_format=json \
  --form 'timestamp_granularities[]=segment' \
  --form language=en-US \
  --form 'model_config={
  "smart_format": true,
  "punctuate": true
}'

{
  "text": "string",
  "duration": 0,
  "segments": [
    {
      "id": 0,
      "start": 0,
      "end": 0,
      "text": "string"
    }
  ],
  "words": [
    {
      "word": "string",
      "start": 0,
      "end": 0,
      "confidence": 0,
      "speaker": 0
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "body",
        "name"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

WebSocket

REST API

In-Call

For AI Agents

Transcribe speech to text

Authorizations

Body

Response