Telnyx Audio API
The Audio API from Telnyx — 1 operation(s) for audio.
The Audio API from Telnyx — 1 operation(s) for audio.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/telnyx:telnyx-audio-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Telnyx Audio API
version: 2.0.0
contact:
email: support@telnyx.com
x-endpoint-cost: light
x-refined-note:
- x-latency-category differs across the merged source definitions and was not carried
description: 'Operations tagged Audio across 3 of this provider''s published API definitions: telnyx-openapi.json, telnyx-openapi.yml, telnyx-openapi_2.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.telnyx.com/v2
description: Version 2.0.0 of the Telnyx API
security:
- bearerAuth: []
tags:
- name: Audio
paths:
/ai/audio/transcriptions:
post:
tags:
- Audio
summary: Transcribe speech to text
description: Transcribe speech to text. This endpoint is consistent with the OpenAI Transcription API and may be used with the OpenAI JS or Python SDK.
operationId: audio_public_audio_transcriptions_post
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/AudioTranscriptionRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AudioTranscriptionResponse'
example:
text: string
duration: 0
segments:
- id: 0
start: 0
end: 0
text: string
words:
- word: string
start: 0
end: 0
confidence: 0
speaker: 0
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
servers:
- url: https://api.telnyx.com/v2
description: Version 2.0.0 of the Telnyx API
components:
schemas:
AudioTranscriptionResponseWord:
type: object
description: Word-level timing detail. Only present when using a `deepgram/*` model with `model_config` options that enable word timestamps.
properties:
word:
type: string
description: The transcribed word.
start:
type: number
description: Start time of the word in seconds.
end:
type: number
description: End time of the word in seconds.
confidence:
type: number
description: Confidence score for the word (0.0 to 1.0).
speaker:
type: integer
description: Speaker index. Only present when diarization is enabled via `model_config`.
speaker_confidence:
type: number
description: Confidence score for the speaker assignment (0.0 to 1.0). Only present when diarization is enabled via `model_config`.
punctuated_word:
type: string
description: The transcribed word with punctuation and capitalisation applied. Only present when `punctuate` or `smart_format` is enabled via `model_config`.
required:
- word
- start
- end
ValidationError:
title: ValidationError
required:
- loc
- msg
- type
type: object
properties:
loc:
title: Location
type: array
items:
anyOf:
- type: string
- type: integer
msg:
title: Message
type: string
type:
title: Error Type
type: string
AudioTranscriptionResponseSegments:
type: object
properties:
id:
type: number
description: Unique identifier of the segment.
start:
type: number
description: Start time of the segment in seconds.
end:
type: number
description: End time of the segment in seconds.
text:
type: string
description: Text content of the segment.
words:
type: array
description: Word-level timing detail for this segment. Returned by the `deepgram/*` models when word-level output is enabled via `model_config`.
items:
$ref: '#/components/schemas/AudioTranscriptionResponseWord'
speakers:
type: array
description: Speaker indices heard in this segment. Returned by the `deepgram/*` models when `diarize` is enabled via `model_config`.
items:
type: integer
required:
- id
- start
- end
- text
AudioTranscriptionResponse:
type: object
description: 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.
properties:
text:
type: string
description: The transcribed text for the audio file.
duration:
type: number
description: 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:
type: array
description: 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`.
items:
$ref: '#/components/schemas/AudioTranscriptionResponseSegments'
words:
type: array
description: Word-level timestamps and optional speaker labels. Only returned by the `deepgram/*` models when word-level output is enabled via `model_config`.
items:
$ref: '#/components/schemas/AudioTranscriptionResponseWord'
required:
- text
AudioTranscriptionRequest:
type: object
properties:
file:
description: '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.'
type: string
format: binary
file_url:
description: '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.'
type: string
example: https://example.com/file.mp3
model:
description: '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.'
example: distil-whisper/distil-large-v2
default: distil-whisper/distil-large-v2
type: string
enum:
- 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
response_format:
description: The format of the transcript output. Use `verbose_json` to take advantage of timestamps.
example: json
type: string
default: json
enum:
- json
- verbose_json
timestamp_granularities[]:
description: The timestamp granularities to populate for this transcription. `response_format` must be set verbose_json to use timestamp granularities. Currently `segment` is supported.
example: segment
type: string
enum:
- segment
language:
type: string
description: 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.
example: en-US
model_config:
type: object
description: 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.
additionalProperties: true
example:
smart_format: true
punctuate: true
required:
- model
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
example:
detail:
- loc:
- body
- name
msg: Field required
type: missing
AudioTranscriptionResponseWord_2:
description: Word-level timing detail. Only present when using `deepgram/nova-3` with `model_config` options that enable word timestamps.
properties:
confidence:
description: Confidence score for the word (0.0 to 1.0).
type: number
end:
description: End time of the word in seconds.
type: number
speaker:
description: Speaker index. Only present when diarization is enabled via `model_config`.
type: integer
start:
description: Start time of the word in seconds.
type: number
word:
description: The transcribed word.
type: string
required:
- word
- start
- end
type: object
AudioTranscriptionResponseSegments_2:
properties:
end:
description: End time of the segment in seconds.
type: number
id:
description: Unique identifier of the segment.
type: number
start:
description: Start time of the segment in seconds.
type: number
text:
description: Text content of the segment.
type: string
required:
- id
- start
- end
- text
type: object
AudioTranscriptionResponse_2:
description: 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. `deepgram/nova-3` returns `text` and, depending on `model_config`, may include `words` with per-word timestamps and speaker labels.
properties:
duration:
description: The duration of the audio file in seconds. Returned by `distil-whisper/distil-large-v2` and `deepgram/nova-3` when `response_format` is `verbose_json`. Not returned by `openai/whisper-large-v3-turbo`.
type: number
segments:
description: Segments of the transcribed text and their corresponding details. Returned by `distil-whisper/distil-large-v2` when `response_format` is `verbose_json`. Not returned by `openai/whisper-large-v3-turbo`.
items:
$ref: '#/components/schemas/AudioTranscriptionResponseSegments_2'
type: array
text:
description: The transcribed text for the audio file.
type: string
words:
description: Word-level timestamps and optional speaker labels. Only returned by `deepgram/nova-3` when word-level output is enabled via `model_config`.
items:
$ref: '#/components/schemas/AudioTranscriptionResponseWord_2'
type: array
required:
- text
type: object
AudioTranscriptionRequest_2:
properties:
file:
description: '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: `deepgram/nova-3` only supports mp3 and wav formats.'
format: binary
type: string
file_url:
description: '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: `deepgram/nova-3` only supports mp3 and wav formats.'
example: https://example.com/file.mp3
type: string
language:
description: 'The language of the audio to be transcribed. For `deepgram/nova-3`, only English variants are supported: `en`, `en-US`, `en-GB`, `en-AU`, `en-NZ`, `en-IN`. For `openai/whisper-large-v3-turbo`, supports multiple languages. `distil-whisper/distil-large-v2` does not support language parameter.'
example: en-US
type: string
model:
default: distil-whisper/distil-large-v2
description: 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. `deepgram/nova-3` supports English variants (en, en-US, en-GB, en-AU, en-NZ, en-IN) and only accepts mp3/wav files.
enum:
- distil-whisper/distil-large-v2
- openai/whisper-large-v3-turbo
- deepgram/nova-3
example: distil-whisper/distil-large-v2
type: string
model_config:
additionalProperties: true
description: Additional model-specific configuration parameters. Only allowed with `deepgram/nova-3` model. 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:
punctuate: true
smart_format: true
type: object
response_format:
default: json
description: The format of the transcript output. Use `verbose_json` to take advantage of timestamps.
enum:
- json
- verbose_json
example: json
type: string
timestamp_granularities[]:
description: The timestamp granularities to populate for this transcription. `response_format` must be set verbose_json to use timestamp granularities. Currently `segment` is supported.
enum:
- segment
example: segment
type: string
required:
- model
type: object
HTTPValidationError_2:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
title: Detail
type: array
title: HTTPValidationError
type: object
AudioTranscriptionResponseWord_3:
type: object
description: Word-level timing detail. Only present when using a `deepgram/*` model with `model_config` options that enable word timestamps, or `reson8/prerecorded`.
properties:
word:
type: string
description: The transcribed word.
start:
type: number
description: Start time of the word in seconds.
end:
type: number
description: End time of the word in seconds.
confidence:
type: number
description: Confidence score for the word (0.0 to 1.0).
speaker:
type: integer
description: Speaker index. Only present when diarization is enabled via `model_config`.
speaker_confidence:
type: number
description: Confidence score for the speaker assignment (0.0 to 1.0). Only present when diarization is enabled via `model_config`.
punctuated_word:
type: string
description: The transcribed word with punctuation and capitalisation applied. Only present when `punctuate` or `smart_format` is enabled via `model_config`.
required:
- word
- start
- end
AudioTranscriptionResponseSegments_3:
type: object
properties:
id:
type: number
description: Unique identifier of the segment.
start:
type: number
description: Start time of the segment in seconds.
end:
type: number
description: End time of the segment in seconds.
text:
type: string
description: Text content of the segment.
words:
type: array
description: Word-level timing detail for this segment. Returned by the `deepgram/*` models when word-level output is enabled via `model_config`, and by `reson8/prerecorded`.
items:
$ref: '#/components/schemas/AudioTranscriptionResponseWord_3'
speakers:
type: array
description: Speaker indices heard in this segment. Returned by the `deepgram/*` models and `reson8/prerecorded` when `diarize` is enabled via `model_config`. With `multichannel`, speakers are numbered per channel from 0, so identify a speaker by (`channel`, speaker).
items:
type: integer
channel:
type: integer
description: Zero-indexed audio channel of this segment. Returned by the `deepgram/*` models when `multichannel` is enabled via `model_config` and the file has more than one channel. Segments from all channels are merged in one list ordered by start time.
required:
- id
- start
- end
- text
AudioTranscriptionResponse_3:
type: object
description: 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.
properties:
text:
type: string
description: The transcribed text for the audio file.
duration:
type: number
description: 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:
type: array
description: 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`.
items:
$ref: '#/components/schemas/AudioTranscriptionResponseSegments_3'
words:
type: array
description: Word-level timestamps and optional speaker labels. Only returned by the `deepgram/*` models when word-level output is enabled via `model_config`.
items:
$ref: '#/components/schemas/AudioTranscriptionResponseWord_3'
required:
- text
AudioTranscriptionRequest_3:
type: object
properties:
file:
description: '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.'
type: string
format: binary
file_url:
description: '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.'
type: string
example: https://example.com/file.mp3
model:
description: '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`.'
example: distil-whisper/distil-large-v2
default: distil-whisper/distil-large-v2
type: string
enum:
- 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
response_format:
description: The format of the transcript output. Use `verbose_json` to take advantage of timestamps.
example: json
type: string
default: json
enum:
- json
- verbose_json
timestamp_granularities[]:
description: The timestamp granularities to populate for this transcription. `response_format` must be set verbose_json to use timestamp granularities. Currently `segment` is supported.
example: segment
type: string
enum:
- segment
language:
type: string
description: 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:
type: object
description: 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.
additionalProperties: true
example:
smart_format: true
punctuate: true
required:
- model
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: API key
description: 'Telnyx API key supplied as `Authorization: Bearer <token>`. In production, auth may be validated by the API gateway and forwarded via Telnyx auth headers.'
Payment:
type: apiKey
in: header
name: Authorization
description: 'Machine Payment Protocol credential used on paid retries, sent as `Authorization: Payment ...`. Obtained by paying a challenge returned in the `WWW-Authenticate` header of a 402 response. This is not a Telnyx API key; initial challenge requests use standard bearer authentication instead.'
agent-memory_bearerAuth:
type: http
scheme: bearer
description: Telnyx API key
bearerAuth:
type: http
scheme: bearer
branded-calling_bearerAuth:
type: http
scheme: bearer
description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
collections_bearerAuth:
type: http
scheme: bearer
description: Telnyx API key. Collections and results are automatically scoped to the authenticated user's organization.
number-reputation_bearerAuth:
type: http
scheme: bearer
description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
oauthClientAuth:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://api.telnyx.com/v2/oauth/token
scopes:
admin: Administrative access to Telnyx resources
authorizationCode:
authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
tokenUrl: https://api.telnyx.com/v2/oauth/token
refreshUrl: https://api.telnyx.com/v2/oauth/token
scopes:
admin: Administrative access to Telnyx resources
description: OAuth 2.0 authentication for Telnyx API and MCP integrations
outbound-voice-profiles_bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
pronunciation-dicts_bearerAuth:
type: http
scheme: bearer
description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
rcs-registration_bearerAuth:
type: http
scheme: bearer
bearerFormat: API key
stored-payment-transactions_bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
transcriptions-search_bearerAuth:
type: http
scheme: bearer
description: Telnyx API key. Results are automatically scoped to the authenticated user's organization.
web-search_bearerAuth:
type: http
scheme: bearer
description: Telnyx API key
pay-connectors_bearerAuth:
type: http
scheme: bearer
description: Telnyx API key, not the processor bearer token.
telnyxApiKey:
type: http
scheme: bearer
description: Management-only Telnyx account credential.
x-refined-from:
- telnyx-openapi.json
- telnyx-openapi.yml
- telnyx-openapi_2.json
x-service-info:
categories:
- communication
- developer-tools
docs:
apiReference: https://developers.telnyx.com
homepage: https://telnyx.com
llms: https://telnyx.com/llms.txt