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).

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

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.

Example:

"en-US"

model_config

object

Additional model-specific configuration parameters. Only allowed with the deepgram/* models. Can include Deepgram-specific options such as smart_format, punctuate, diarize, utterance, 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.

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