Deepgram Pre-Recorded API

openapi: 3.2.0
info:
  title: Deepgram Speech-to-Text Pre Recorded API
  description: The Deepgram Speech-to-Text API provides accurate, fast transcription of audio content using advanced AI models. It supports pre-recorded audio files, delivering transcripts with features such as punctuation, diarization, language detection, smart formatting, summarization, sentiment analysis, topic detection, and intent recognition. Deepgram's Nova model family powers the transcription engine, offering high accuracy for conversational and professional audio across multiple languages and audio formats.
  version: '1.0'
  contact:
    name: Deepgram Support
    url: https://developers.deepgram.com
  termsOfService: https://deepgram.com/tos
servers:
- url: https://api.deepgram.com
  description: Deepgram Production Server
- url: https://api.eu.deepgram.com
  description: Deepgram EU Server
security:
- bearerAuth: []
tags:
- name: Pre-Recorded
  description: Transcribe pre-recorded audio files or audio from URLs.
paths:
  /v1/listen:
    post:
      operationId: transcribePreRecordedAudio
      summary: Deepgram Transcribe pre-recorded audio
      description: Transcribes and optionally analyzes pre-recorded audio. Accepts audio as a URL reference in the request body or as raw binary audio data. Supports a wide range of audio formats and provides options for punctuation, diarization, smart formatting, language detection, summarization, sentiment analysis, topic detection, and intent recognition through query parameters.
      tags:
      - Pre-Recorded
      parameters:
      - $ref: '#/components/parameters/model'
      - $ref: '#/components/parameters/language'
      - $ref: '#/components/parameters/punctuate'
      - $ref: '#/components/parameters/diarize'
      - $ref: '#/components/parameters/diarize_version'
      - $ref: '#/components/parameters/smart_format'
      - $ref: '#/components/parameters/utterances'
      - $ref: '#/components/parameters/utt_split'
      - $ref: '#/components/parameters/keywords'
      - $ref: '#/components/parameters/search'
      - $ref: '#/components/parameters/replace'
      - $ref: '#/components/parameters/redact'
      - $ref: '#/components/parameters/paragraphs'
      - $ref: '#/components/parameters/detect_language'
      - $ref: '#/components/parameters/filler_words'
      - $ref: '#/components/parameters/multichannel'
      - $ref: '#/components/parameters/alternatives'
      - $ref: '#/components/parameters/numerals'
      - $ref: '#/components/parameters/tag'
      - $ref: '#/components/parameters/callback'
      - $ref: '#/components/parameters/callback_method'
      - $ref: '#/components/parameters/sentiment'
      - $ref: '#/components/parameters/summarize'
      - $ref: '#/components/parameters/topics'
      - $ref: '#/components/parameters/intents'
      - $ref: '#/components/parameters/extra'
      requestBody:
        description: Audio content to transcribe. Can be a JSON object with a URL reference or raw binary audio data with the appropriate Content-Type header.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AudioUrlRequest'
          audio/*:
            schema:
              type: string
              format: binary
              description: Raw binary audio data in any supported audio format.
      responses:
        '200':
          description: Transcription completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranscriptionResponse'
        '400':
          description: Bad request due to invalid parameters or audio format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized due to missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    sentiment:
      name: sentiment
      in: query
      description: Indicates whether to perform sentiment analysis on the content.
      schema:
        type: boolean
        default: false
    callback:
      name: callback
      in: query
      description: URL to which Deepgram will make a callback request when processing is complete.
      schema:
        type: string
        format: uri
    filler_words:
      name: filler_words
      in: query
      description: Indicates whether to include filler words such as um and uh in the transcript.
      schema:
        type: boolean
        default: false
    smart_format:
      name: smart_format
      in: query
      description: Indicates whether to apply smart formatting which synchronizes punctuation, diarization, and intelligent text normalization.
      schema:
        type: boolean
        default: false
    redact:
      name: redact
      in: query
      description: Indicates whether to redact sensitive information from the transcript. Accepts boolean or specific entity types such as pci, numbers, ssn.
      schema:
        type: array
        items:
          type: string
    utt_split:
      name: utt_split
      in: query
      description: Length of time in seconds used to split utterances.
      schema:
        type: number
        format: float
    utterances:
      name: utterances
      in: query
      description: Indicates whether to segment speech into utterances.
      schema:
        type: boolean
        default: false
    paragraphs:
      name: paragraphs
      in: query
      description: Indicates whether to split the transcript into paragraphs.
      schema:
        type: boolean
        default: false
    search:
      name: search
      in: query
      description: Terms to search for in the submitted audio.
      schema:
        type: array
        items:
          type: string
    language:
      name: language
      in: query
      description: BCP-47 language tag for the primary spoken language in the audio.
      schema:
        type: string
        example: en
    diarize:
      name: diarize
      in: query
      description: Indicates whether to recognize speaker changes in the transcript.
      schema:
        type: boolean
        default: false
    intents:
      name: intents
      in: query
      description: Indicates whether to detect intents in the content.
      schema:
        type: boolean
        default: false
    tag:
      name: tag
      in: query
      description: Tag to associate with the request for tracking purposes.
      schema:
        type: array
        items:
          type: string
    numerals:
      name: numerals
      in: query
      description: Indicates whether to convert numbers from written format to numerical format.
      schema:
        type: boolean
        default: false
    model:
      name: model
      in: query
      description: AI model used to process the audio. Options include nova-3, nova-2, nova, enhanced, and base.
      schema:
        type: string
        default: nova-3
    callback_method:
      name: callback_method
      in: query
      description: HTTP method for the callback request.
      schema:
        type: string
        enum:
        - POST
        - PUT
        default: POST
    detect_language:
      name: detect_language
      in: query
      description: Indicates whether to detect the language of the audio.
      schema:
        type: boolean
        default: false
    diarize_version:
      name: diarize_version
      in: query
      description: Version of the diarization feature to use.
      schema:
        type: string
    summarize:
      name: summarize
      in: query
      description: Indicates whether to generate a summary of the content. Can be a boolean or a specific summary format.
      schema:
        type: string
    alternatives:
      name: alternatives
      in: query
      description: Maximum number of transcript alternatives to return.
      schema:
        type: integer
        minimum: 1
    extra:
      name: extra
      in: query
      description: Arbitrary key-value pairs to associate with the request.
      schema:
        type: string
    multichannel:
      name: multichannel
      in: query
      description: Indicates whether to transcribe each audio channel independently.
      schema:
        type: boolean
        default: false
    keywords:
      name: keywords
      in: query
      description: Keywords to boost in the transcription results.
      schema:
        type: array
        items:
          type: string
    punctuate:
      name: punctuate
      in: query
      description: Indicates whether to add punctuation and capitalization to the transcript.
      schema:
        type: boolean
        default: false
    topics:
      name: topics
      in: query
      description: Indicates whether to detect topics in the content.
      schema:
        type: boolean
        default: false
    replace:
      name: replace
      in: query
      description: Terms or phrases to search for in the submitted audio and replace.
      schema:
        type: array
        items:
          type: string
  schemas:
    Results:
      type: object
      properties:
        channels:
          type: array
          items:
            $ref: '#/components/schemas/Channel'
          description: Transcription results organized by audio channel.
        utterances:
          type: array
          items:
            $ref: '#/components/schemas/Utterance'
          description: Transcription results organized by utterance when utterances parameter is enabled.
        summary:
          $ref: '#/components/schemas/Summary'
        sentiments:
          $ref: '#/components/schemas/SentimentResults'
        topics:
          $ref: '#/components/schemas/TopicResults'
        intents:
          $ref: '#/components/schemas/IntentResults'
    TopicResults:
      type: object
      properties:
        segments:
          type: array
          items:
            $ref: '#/components/schemas/TopicSegment'
          description: Topic detection results for content segments.
    Channel:
      type: object
      properties:
        alternatives:
          type: array
          items:
            $ref: '#/components/schemas/Alternative'
          description: Alternative transcriptions for this channel, ordered by confidence.
        detected_language:
          type: string
          description: Detected language of the audio in this channel.
        language_confidence:
          type: number
          format: float
          description: Confidence score for the detected language.
    ModelInfo:
      type: object
      properties:
        name:
          type: string
          description: Name of the model.
        version:
          type: string
          description: Version of the model.
        arch:
          type: string
          description: Architecture of the model.
    IntentSegment:
      type: object
      properties:
        text:
          type: string
          description: Text of the segment.
        start_word:
          type: integer
          description: Index of the first word in this segment.
        end_word:
          type: integer
          description: Index of the last word in this segment.
        intents:
          type: array
          items:
            $ref: '#/components/schemas/Intent'
          description: Intents detected in this segment.
    SentimentResults:
      type: object
      properties:
        segments:
          type: array
          items:
            $ref: '#/components/schemas/SentimentSegment'
          description: Sentiment analysis results for content segments.
        average:
          $ref: '#/components/schemas/SentimentAverage'
    Paragraph:
      type: object
      properties:
        sentences:
          type: array
          items:
            $ref: '#/components/schemas/Sentence'
          description: Sentences within this paragraph.
        start:
          type: number
          format: float
          description: Start time of the paragraph in seconds.
        end:
          type: number
          format: float
          description: End time of the paragraph in seconds.
        num_words:
          type: integer
          description: Number of words in this paragraph.
        speaker:
          type: integer
          description: Speaker identifier for this paragraph.
    Error:
      type: object
      properties:
        err_code:
          type: string
          description: Error code identifying the type of error.
        err_msg:
          type: string
          description: Human-readable error message.
        request_id:
          type: string
          description: Unique identifier for the request that produced the error.
    ParagraphGroup:
      type: object
      properties:
        transcript:
          type: string
          description: Full transcript organized into paragraphs.
        paragraphs:
          type: array
          items:
            $ref: '#/components/schemas/Paragraph'
          description: Individual paragraph objects.
    TopicSegment:
      type: object
      properties:
        text:
          type: string
          description: Text of the segment.
        start_word:
          type: integer
          description: Index of the first word in this segment.
        end_word:
          type: integer
          description: Index of the last word in this segment.
        topics:
          type: array
          items:
            $ref: '#/components/schemas/Topic'
          description: Topics detected in this segment.
    Topic:
      type: object
      properties:
        topic:
          type: string
          description: Detected topic label.
        confidence_score:
          type: number
          format: float
          description: Confidence score for the topic detection.
    Sentence:
      type: object
      properties:
        text:
          type: string
          description: Sentence text.
        start:
          type: number
          format: float
          description: Start time of the sentence in seconds.
        end:
          type: number
          format: float
          description: End time of the sentence in seconds.
    TranscriptionResponse:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/Metadata'
        results:
          $ref: '#/components/schemas/Results'
    SentimentAverage:
      type: object
      properties:
        sentiment:
          type: string
          enum:
          - positive
          - negative
          - neutral
          description: Overall average sentiment.
        sentiment_score:
          type: number
          format: float
          description: Average sentiment score.
    AudioUrlRequest:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          format: uri
          description: URL of the audio file to transcribe.
    Metadata:
      type: object
      properties:
        transaction_key:
          type: string
          description: Unique identifier for the transaction.
        request_id:
          type: string
          description: Unique identifier for the API request.
        sha256:
          type: string
          description: SHA-256 hash of the submitted audio.
        created:
          type: string
          format: date-time
          description: Timestamp when the request was created.
        duration:
          type: number
          format: float
          description: Duration of the submitted audio in seconds.
        channels:
          type: integer
          description: Number of audio channels detected.
        models:
          type: array
          items:
            type: string
          description: Model identifiers used for transcription.
        model_info:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ModelInfo'
          description: Detailed information about models used.
    Alternative:
      type: object
      properties:
        transcript:
          type: string
          description: Full transcript text for this alternative.
        confidence:
          type: number
          format: float
          description: Confidence score for this alternative.
          minimum: 0
          maximum: 1
        words:
          type: array
          items:
            $ref: '#/components/schemas/Word'
          description: Individual words with timing and confidence information.
        paragraphs:
          $ref: '#/components/schemas/ParagraphGroup'
    Summary:
      type: object
      properties:
        short:
          type: string
          description: Short summary of the content.
    Intent:
      type: object
      properties:
        intent:
          type: string
          description: Detected intent label.
        confidence_score:
          type: number
          format: float
          description: Confidence score for the intent recognition.
    Utterance:
      type: object
      properties:
        start:
          type: number
          format: float
          description: Start time of the utterance in seconds.
        end:
          type: number
          format: float
          description: End time of the utterance in seconds.
        confidence:
          type: number
          format: float
          description: Confidence score for this utterance.
        channel:
          type: integer
          description: Audio channel index for this utterance.
        transcript:
          type: string
          description: Transcript text for this utterance.
        words:
          type: array
          items:
            $ref: '#/components/schemas/Word'
          description: Individual words within this utterance.
        speaker:
          type: integer
          description: Speaker identifier for this utterance.
        id:
          type: string
          description: Unique identifier for this utterance.
    SentimentSegment:
      type: object
      properties:
        text:
          type: string
          description: Text of the segment.
        start_word:
          type: integer
          description: Index of the first word in this segment.
        end_word:
          type: integer
          description: Index of the last word in this segment.
        sentiment:
          type: string
          enum:
          - positive
          - negative
          - neutral
          description: Overall sentiment of the segment.
        sentiment_score:
          type: number
          format: float
          description: Confidence score for the sentiment classification.
    IntentResults:
      type: object
      properties:
        segments:
          type: array
          items:
            $ref: '#/components/schemas/IntentSegment'
          description: Intent recognition results for content segments.
    Word:
      type: object
      properties:
        word:
          type: string
          description: The transcribed word.
        start:
          type: number
          format: float
          description: Start time of the word in seconds.
        end:
          type: number
          format: float
          description: End time of the word in seconds.
        confidence:
          type: number
          format: float
          description: Confidence score for this word.
          minimum: 0
          maximum: 1
        speaker:
          type: integer
          description: Speaker identifier when diarization is enabled.
        punctuated_word:
          type: string
          description: The word with punctuation applied when punctuate is enabled.
        sentiment:
          type: string
          enum:
          - positive
          - negative
          - neutral
          description: Sentiment of the word when sentiment analysis is enabled.
        sentiment_score:
          type: number
          format: float
          description: Sentiment confidence score for this word.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Deepgram API key passed as a bearer token in the Authorization header.
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Deepgram API key passed with Token prefix, e.g. Token YOUR_API_KEY.
externalDocs:
  description: Deepgram Speech-to-Text Documentation
  url: https://developers.deepgram.com/docs/stt/getting-started