openapi: 3.1.0
info:
  contact:
    email: support@telnyx.com
  description: Telnyx provides global communications and connectivity APIs for developers — including SIP trunking, programmable voice, SMS, MMS, WhatsApp Business Messaging, Call Control, Fax, Wireless (IoT & eSIM), Phone Numbers (DID provisioning & porting), Emergency Services, and Network APIs for private interconnects and edge connectivity. Build, scale, and manage voice, messaging, and data networks with Telnyx's carrier-grade global infrastructure and API-first platform.
  title: Telnyx Access Tokens Speech To Text over WebSockets API
  version: 2.0.0
  x-endpoint-cost: light
servers:
- description: Version 2.0.0 of the Telnyx API
  url: https://api.telnyx.com/v2
security:
- bearerAuth: []
tags:
- description: Speech to text command operations
  name: Speech To Text over WebSockets
paths:
  /speech-to-text/transcription:
    get:
      description: 'Open a WebSocket connection to stream audio and receive transcriptions in real-time. Authentication is provided via the standard `Authorization: Bearer <API_KEY>` header.


        Supported engines: `Azure`, `Deepgram`, `Google`, `Telnyx`, `xAI`, `Speechmatics`.


        **Connection flow:**

        1. Open WebSocket with query parameters specifying engine, input format, and language.

        2. Send binary audio frames (mp3/wav format).

        3. Receive JSON transcript frames with `transcript`, `is_final`, and `confidence` fields.

        4. Close connection when done.'
      operationId: TranscriptionOverWs
      parameters:
      - $ref: '#/components/parameters/transcription_engine'
      - $ref: '#/components/parameters/input_format'
      - $ref: '#/components/parameters/language'
      - $ref: '#/components/parameters/interim_results'
      - $ref: '#/components/parameters/model'
      - $ref: '#/components/parameters/endpointing'
      - $ref: '#/components/parameters/redact'
      - $ref: '#/components/parameters/keyterm'
      - $ref: '#/components/parameters/keywords'
      requestBody:
        content:
          application/octet-stream:
            schema:
              $ref: '#/components/schemas/SttClientEvent'
        description: Client sends binary audio frames (mp3 or wav format) over the WebSocket. See `SttClientEvent` schema.
      responses:
        '101':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SttServerEvent'
          description: 'WebSocket connection established. Communication proceeds via binary audio frames (client) and JSON transcript frames (server).


            **Client → Server:** Binary audio data (mp3/wav).

            **Server → Client:** See `TranscriptFrame` and `SttErrorFrame` schemas.'
        '200':
          description: WebSocket upgrade successful — this response is not returned directly. See 101 for frame documentation.
        '400':
          description: Invalid parameters — engine not supported or missing required fields.
        '401':
          description: Authentication failed — missing or invalid Authorization header.
        '422':
          $ref: '#/components/responses/speech-to-text_UnprocessableEntityResponse'
      summary: Speech to text over WebSocket
      tags:
      - Speech To Text over WebSockets
      x-latency-category: interactive
components:
  schemas:
    SttClientEvent:
      description: Binary audio data in mp3 or wav format.
      format: binary
      type: string
    speech-to-text_Errors:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/speech-to-text_Error'
          type: array
    google_models:
      enum:
      - latest_long
      - latest_short
      - command_and_search
      - phone_call
      - video
      - default
      - medical_conversation
      - medical_dictation
      type: string
    speechmatics_models:
      enum:
      - speechmatics/standard
      type: string
    SttServerEvent:
      description: Union of all server-to-client WebSocket events for STT streaming.
      discriminator:
        mapping:
          error: '#/components/schemas/SttErrorFrame'
          transcript: '#/components/schemas/TranscriptFrame'
        propertyName: type
      oneOf:
      - $ref: '#/components/schemas/TranscriptFrame'
      - $ref: '#/components/schemas/SttErrorFrame'
    SttErrorFrame:
      description: Server-to-client frame indicating an error during transcription. The connection may be closed shortly after.
      properties:
        error:
          description: Error message describing what went wrong.
          type: string
        type:
          const: error
          description: Frame type identifier.
          type: string
      required:
      - type
      - error
      type: object
    azure_models:
      enum:
      - fast
      type: string
    xai_models:
      enum:
      - xai/grok-stt
      type: string
    TranscriptFrame:
      description: Server-to-client frame containing a transcription result.
      properties:
        confidence:
          description: Confidence score of the transcription, ranging from 0 to 1.
          type: number
        is_final:
          description: Whether this is a final transcription result. When `false`, this is an interim result that may be refined.
          type: boolean
        transcript:
          description: The transcribed text from the audio.
          type: string
        type:
          const: transcript
          description: Frame type identifier.
          type: string
      required:
      - type
      - transcript
      type: object
    speech-to-text_Error:
      properties:
        code:
          format: integer
          type: string
        detail:
          type: string
        meta:
          type: object
        source:
          properties:
            parameter:
              description: Indicates which query parameter caused the error.
              type: string
            pointer:
              description: JSON pointer (RFC6901) to the offending entity.
              format: json-pointer
              type: string
          type: object
        title:
          type: string
      required:
      - code
      - title
    telnyx_models:
      enum:
      - openai/whisper-tiny
      - openai/whisper-large-v3-turbo
      type: string
    deepgram_models:
      enum:
      - deepgram/nova-2
      - deepgram/nova-3
      type: string
  parameters:
    endpointing:
      description: Silence duration (in milliseconds) that triggers end-of-speech detection. When set, the engine uses this value to determine when a speaker has stopped talking. Supported by `xAI`, `Deepgram`, `Google`, and `Speechmatics`. Other engines may not support this parameter.
      example: 500
      in: query
      name: endpointing
      required: false
      schema:
        type: integer
    transcription_engine:
      description: The transcription engine to use for processing the audio stream.
      example: Telnyx
      in: query
      name: transcription_engine
      required: true
      schema:
        enum:
        - Azure
        - Deepgram
        - Google
        - Telnyx
        - xAI
        - Speechmatics
        type: string
    keyterm:
      description: A key term to boost in the transcription. The engine will be more likely to recognize this term. Can be specified multiple times for multiple terms.
      example: Telnyx
      in: query
      name: keyterm
      required: false
      schema:
        type: string
    model:
      description: The specific model to use within the selected transcription engine.
      in: query
      name: model
      schema:
        oneOf:
        - $ref: '#/components/schemas/azure_models'
        - $ref: '#/components/schemas/deepgram_models'
        - $ref: '#/components/schemas/google_models'
        - $ref: '#/components/schemas/telnyx_models'
        - $ref: '#/components/schemas/xai_models'
        - $ref: '#/components/schemas/speechmatics_models'
    interim_results:
      description: Whether to receive interim transcription results.
      example: true
      in: query
      name: interim_results
      required: false
      schema:
        type: boolean
    input_format:
      description: The format of input audio stream.
      example: mp3
      in: query
      name: input_format
      required: true
      schema:
        enum:
        - mp3
        - wav
        type: string
    keywords:
      description: Comma-separated list of keywords to boost in the transcription. The engine will prioritize recognition of these words.
      example: Telnyx,SIP,WebRTC
      in: query
      name: keywords
      required: false
      schema:
        type: string
    redact:
      description: Enable redaction of sensitive information (e.g., PCI data, SSN) from transcription results. Supported values depend on the transcription engine.
      example: pci
      in: query
      name: redact
      required: false
      schema:
        type: string
    language:
      description: The language spoken in the audio stream.
      example: en-US
      in: query
      name: language
      required: false
      schema:
        type: string
  responses:
    speech-to-text_UnprocessableEntityResponse:
      content:
        application/json:
          examples:
            missing_required_parameter:
              summary: Missing required parameter
              value:
                errors:
                - code: '10004'
                  detail: The 'transcription_engine' parameter is required and cannot be blank.
                  source:
                    pointer: /transcription_engine
                  title: Missing required parameter
          schema:
            $ref: '#/components/schemas/speech-to-text_Errors'
      description: Unprocessable entity. The request was well-formed but could not be processed due to semantic errors. This includes validation errors, invalid parameter values and business logic violations.
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http
    branded-calling_bearerAuth:
      description: API key passed as a Bearer token in the Authorization header
      scheme: bearer
      type: http
    oauthClientAuth:
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
      flows:
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
          tokenUrl: https://api.telnyx.com/v2/oauth/token
        clientCredentials:
          scopes:
            admin: Administrative access to Telnyx resources
          tokenUrl: https://api.telnyx.com/v2/oauth/token
      type: oauth2
    outbound-voice-profiles_bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http
    pronunciation-dicts_bearerAuth:
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
      scheme: bearer
      type: http
    stored-payment-transactions_bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http