openapi: 3.0.1
info:
  title: GroqCloud Audio API
  description: Specification of the Groq cloud API
  termsOfService: https://groq.com/terms-of-use/
  contact:
    name: Groq Support
    email: support@groq.com
  version: '2.1'
servers:
- url: https://api.groq.com
security:
- api_key: []
tags:
- name: Audio
paths:
  /openai/v1/audio/speech:
    post:
      operationId: createSpeech
      tags:
      - Audio
      summary: Generates audio from the input text.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSpeechRequest'
      responses:
        '200':
          description: OK
          headers:
            Transfer-Encoding:
              schema:
                type: string
              description: chunked
          content:
            audio/wav:
              schema:
                type: string
                format: binary
      x-groq-metadata:
        returns: Returns an audio file in `wav` format.
        examples:
        - title: Default
          request:
            curl: "curl https://api.groq.com/openai/v1/audio/speech \\\n  -H \"Authorization: Bearer $GROQ_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"playai-tts\",\n    \"input\": \"I love building and shipping new features for our users!\",\n    \"voice\": \"Fritz-PlayAI\",\n    \"response_format\": \"wav\"\n  }'\n"
            py: "import os\nfrom groq import Groq\n\nclient = Groq(api_key=os.environ.get(\"GROQ_API_KEY\"))\n\nspeech_file_path = \"speech.wav\"\nmodel = \"playai-tts\"\nvoice = \"Fritz-PlayAI\"\ntext = \"I love building and shipping new features for our users!\"\nresponse_format = \"wav\"\n\nresponse = client.audio.speech.create(\n    model=model,\n    voice=voice,\n    input=text,\n    response_format=response_format\n)\n\nresponse.write_to_file(speech_file_path)\n"
            js: "import fs from \"fs\";\nimport path from \"path\";\nimport Groq from 'groq-sdk';\n\nconst groq = new Groq({\n  apiKey: process.env.GROQ_API_KEY\n});\n\nconst speechFilePath = \"speech.wav\";\nconst model = \"playai-tts\";\nconst voice = \"Fritz-PlayAI\";\nconst text = \"I love building and shipping new features for our users!\";\nconst responseFormat = \"wav\";\n\nasync function main() {\n  const response = await groq.audio.speech.create({\n    model: model,\n    voice: voice,\n    input: text,\n    response_format: responseFormat\n  });\n\n  const buffer = Buffer.from(await response.arrayBuffer());\n  await fs.promises.writeFile(speechFilePath, buffer);\n}\n\nmain();\n"
  /openai/v1/audio/transcriptions:
    post:
      operationId: createTranscription
      tags:
      - Audio
      summary: Transcribes audio into the input language.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateTranscriptionRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTranscriptionResponseJson'
      x-groq-metadata:
        returns: Returns an audio transcription object.
        examples:
        - title: Default
          request:
            curl: "curl https://api.groq.com/openai/v1/audio/transcriptions \\\n  -H \"Authorization: Bearer $GROQ_API_KEY\" \\\n  -H \"Content-Type: multipart/form-data\" \\\n  -F file=\"@./sample_audio.m4a\" \\\n  -F model=\"whisper-large-v3\"\n"
            py: "import os\nfrom groq import Groq\n\nclient = Groq()\nfilename = os.path.dirname(__file__) + \"/sample_audio.m4a\"\n\nwith open(filename, \"rb\") as file:\n    transcription = client.audio.transcriptions.create(\n      file=(filename, file.read()),\n      model=\"whisper-large-v3\",\n      prompt=\"Specify context or spelling\",  # Optional\n      response_format=\"json\",  # Optional\n      language=\"en\",  # Optional\n      temperature=0.0  # Optional\n    )\n    print(transcription.text)\n"
            js: "import fs from \"fs\";\nimport Groq from \"groq-sdk\";\n\nconst groq = new Groq();\nasync function main() {\n  const transcription = await groq.audio.transcriptions.create({\n    file: fs.createReadStream(\"sample_audio.m4a\"),\n    model: \"whisper-large-v3\",\n    prompt: \"Specify context or spelling\", // Optional\n    response_format: \"json\", // Optional\n    language: \"en\", // Optional\n    temperature: 0.0, // Optional\n  });\n  console.log(transcription.text);\n}\nmain();\n"
          response: "{\n  \"text\": \"Your transcribed text appears here...\",\n  \"x_groq\": {\n    \"id\": \"req_unique_id\"\n  }\n}\n"
  /openai/v1/audio/translations:
    post:
      operationId: createTranslation
      tags:
      - Audio
      summary: Translates audio into English.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateTranslationRequest'
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTranslationResponseJson'
      x-groq-metadata:
        returns: Returns an audio translation object.
        examples:
        - title: Default
          request:
            curl: "curl https://api.groq.com/openai/v1/audio/translations \\\n  -H \"Authorization: Bearer $GROQ_API_KEY\" \\\n  -H \"Content-Type: multipart/form-data\" \\\n  -F file=\"@./sample_audio.m4a\" \\\n  -F model=\"whisper-large-v3\"\n"
            py: "# Default\nimport os\nfrom groq import Groq\n\nclient = Groq()\nfilename = os.path.dirname(__file__) + \"/sample_audio.m4a\"\n\nwith open(filename, \"rb\") as file:\n    translation = client.audio.translations.create(\n      file=(filename, file.read()),\n      model=\"whisper-large-v3\",\n      prompt=\"Specify context or spelling\",  # Optional\n      response_format=\"json\",  # Optional\n      temperature=0.0  # Optional\n    )\n    print(translation.text)\n"
            js: "// Default\nimport fs from \"fs\";\nimport Groq from \"groq-sdk\";\n\nconst groq = new Groq();\nasync function main() {\n  const translation = await groq.audio.translations.create({\n    file: fs.createReadStream(\"sample_audio.m4a\"),\n    model: \"whisper-large-v3\",\n    prompt: \"Specify context or spelling\", // Optional\n    response_format: \"json\", // Optional\n    temperature: 0.0, // Optional\n  });\n  console.log(translation.text);\n}\nmain();\n"
          response: "{\n  \"text\": \"Your translated text appears here...\",\n  \"x_groq\": {\n    \"id\": \"req_unique_id\"\n  }\n}\n"
components:
  schemas:
    CreateTranscriptionResponseJson:
      type: object
      description: Represents a transcription response returned by model, based on the provided input.
      properties:
        text:
          type: string
          description: The transcribed text.
      required:
      - text
    CreateSpeechRequest:
      type: object
      additionalProperties: false
      properties:
        model:
          description: 'One of the [available TTS models](/docs/text-to-speech).

            '
          anyOf:
          - type: string
          - type: string
            enum:
            - playai-tts
            - playai-tts-arabic
          example: playai-tts
        input:
          example: The quick brown fox jumped over the lazy dog
          type: string
          description: The text to generate audio for.
        voice:
          description: The voice to use when generating the audio. List of voices can be found [here](/docs/text-to-speech).
          type: string
          example: Fritz-PlayAI
        response_format:
          description: The format of the generated audio. Supported formats are `flac, mp3, mulaw, ogg, wav`.
          default: mp3
          type: string
          enum:
          - flac
          - mp3
          - mulaw
          - ogg
          - wav
        sample_rate:
          type: integer
          description: The sample rate for generated audio
          default: 48000
          example: 48000
          enum:
          - 8000
          - 16000
          - 22050
          - 24000
          - 32000
          - 44100
          - 48000
        speed:
          description: The speed of the generated audio.
          example: 1
          type: number
          default: 1
          minimum: 0.5
          maximum: 5
      required:
      - model
      - input
      - voice
    CreateTranslationResponseJson:
      type: object
      properties:
        text:
          type: string
      required:
      - text
    CreateTranslationRequest:
      type: object
      additionalProperties: false
      properties:
        file:
          description: 'The audio file object (not file name) translate, in one of these formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm.

            '
          type: string
          format: binary
        url:
          description: 'The audio URL to translate/transcribe (supports Base64URL). Either file or url must be provided.

            When using the Batch API only url is supported.

            '
          type: string
        model:
          description: 'ID of the model to use. `whisper-large-v3` and `whisper-large-v3-turbo` are currently available.

            '
          example: whisper-large-v3-turbo
          anyOf:
          - type: string
          - type: string
            enum:
            - whisper-large-v3
            - whisper-large-v3-turbo
        prompt:
          description: 'An optional text to guide the model''s style or continue a previous audio segment. The [prompt](/docs/guides/speech-to-text/prompting) should be in English.

            '
          type: string
        response_format:
          description: 'The format of the transcript output, in one of these options: `json`, `text`, or `verbose_json`.

            '
          type: string
          enum:
          - json
          - text
          - verbose_json
          default: json
        temperature:
          description: 'The sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. If set to 0, the model will use [log probability](https://en.wikipedia.org/wiki/Log_probability) to automatically increase the temperature until certain thresholds are hit.

            '
          type: number
          default: 0
      oneOf:
      - required:
        - file
      - required:
        - url
      required:
      - model
    CreateTranscriptionRequest:
      type: object
      additionalProperties: false
      properties:
        file:
          description: 'The audio file object (not file name) to transcribe, in one of these formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm.

            Either a file or a URL must be provided. Note that the file field is not supported in Batch API requests.

            '
          type: string
          format: binary
        url:
          description: 'The audio URL to translate/transcribe (supports Base64URL).

            Either a file or a URL must be provided. For Batch API requests, the URL field is required since the file field is not supported.

            '
          type: string
        model:
          description: 'ID of the model to use. `whisper-large-v3` and `whisper-large-v3-turbo` are currently available.

            '
          example: whisper-large-v3-turbo
          anyOf:
          - type: string
          - type: string
            enum:
            - whisper-large-v3
            - whisper-large-v3-turbo
        language:
          description: 'The language of the input audio. Supplying the input language in [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format will improve accuracy and latency.

            '
          anyOf:
          - type: string
          - type: string
            enum:
            - en
            - zh
            - de
            - es
            - ru
            - ko
            - fr
            - ja
            - pt
            - tr
            - pl
            - ca
            - nl
            - ar
            - sv
            - it
            - id
            - hi
            - fi
            - vi
            - he
            - uk
            - el
            - ms
            - cs
            - ro
            - da
            - hu
            - ta
            - 'no'
            - th
            - ur
            - hr
            - bg
            - lt
            - la
            - mi
            - ml
            - cy
            - sk
            - te
            - fa
            - lv
            - bn
            - sr
            - az
            - sl
            - kn
            - et
            - mk
            - br
            - eu
            - is
            - hy
            - ne
            - mn
            - bs
            - kk
            - sq
            - sw
            - gl
            - mr
            - pa
            - si
            - km
            - sn
            - yo
            - so
            - af
            - oc
            - ka
            - be
            - tg
            - sd
            - gu
            - am
            - yi
            - lo
            - uz
            - fo
            - ht
            - ps
            - tk
            - nn
            - mt
            - sa
            - lb
            - my
            - bo
            - tl
            - mg
            - as
            - tt
            - haw
            - ln
            - ha
            - ba
            - jv
            - su
            - yue
        prompt:
          description: 'An optional text to guide the model''s style or continue a previous audio segment. The [prompt](/docs/speech-text) should match the audio language.

            '
          type: string
        response_format:
          description: 'The format of the transcript output, in one of these options: `json`, `text`, or `verbose_json`.

            '
          type: string
          enum:
          - json
          - text
          - verbose_json
          default: json
        temperature:
          description: 'The sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. If set to 0, the model will use [log probability](https://en.wikipedia.org/wiki/Log_probability) to automatically increase the temperature until certain thresholds are hit.

            '
          type: number
          default: 0
        timestamp_granularities:
          description: 'The timestamp granularities to populate for this transcription. `response_format` must be set `verbose_json` to use timestamp granularities. Either or both of these options are supported: `word`, or `segment`. Note: There is no additional latency for segment timestamps, but generating word timestamps incurs additional latency.

            '
          type: array
          items:
            type: string
            enum:
            - word
            - segment
          default:
          - segment
      oneOf:
      - required:
        - file
      - required:
        - url
      required:
      - model
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
      bearerFormat: apiKey
x-groq-metadata:
  groups:
  - id: chat
    type: endpoints
    title: Chat
    description: ''
    sections:
    - type: endpoint
      key: createChatCompletion
      path: create
  - id: responses
    type: endpoints
    title: Responses (beta)
    description: ''
    sections:
    - type: endpoint
      key: createResponse
      path: create
  - id: audio
    type: endpoints
    title: Audio
    description: ''
    sections:
    - type: endpoint
      key: createTranscription
      path: transcription
    - type: endpoint
      key: createTranslation
      path: translation
    - type: endpoint
      key: createSpeech
      path: speech
  - id: models
    type: endpoints
    title: Models
    description: ''
    sections:
    - type: endpoint
      key: listModels
      path: list
    - type: endpoint
      key: retrieveModel
      path: retrieve
  - id: batches
    type: endpoints
    title: Batches
    description: ''
    sections:
    - type: endpoint
      key: createBatch
      path: create
    - type: endpoint
      key: retrieveBatch
      path: retrieve
    - type: endpoint
      key: listBatches
      path: list
    - type: endpoint
      key: cancelBatch
      path: cancel
  - id: files
    type: endpoints
    title: Files
    description: ''
    sections:
    - type: endpoint
      key: uploadFile
      path: upload
    - type: endpoint
      key: listFiles
      path: list
    - type: endpoint
      key: deleteFile
      path: delete
    - type: endpoint
      key: retrieveFile
      path: retrieve
    - type: endpoint
      key: downloadFile
      path: download
  - id: fine-tuning
    type: endpoints
    title: Fine Tuning
    description: ''
    sections:
    - type: endpoint
      key: listFineTunings
      path: list
    - type: endpoint
      key: createFineTuning
      path: create
    - type: endpoint
      key: getFineTuning
      path: get
    - type: endpoint
      key: deleteFineTuning
      path: delete