> ## Documentation Index
> Fetch the complete documentation index at: https://smallestai-ff1e543d.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Pulse (Pre-Recorded)

> Convert speech to text using file upload with the Pulse STT POST API

The STT POST API allows you to convert speech to text using two different input methods:

1. **Raw Audio Bytes** (`application/octet-stream`) - Send raw audio data with all parameters as query parameters
2. **Audio URL** (`application/json`) - Provide only a URL to an audio file in the JSON body, with all other parameters as query parameters

Both methods use our Pulse STT model with automatic language detection across 30+ languages.

## Authentication

This endpoint requires authentication using a Bearer token in the Authorization header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Input Methods

Choose the input method that best fits your use case:

| Method        | Content Type               | Use Case                                   | Parameters       |
| ------------- | -------------------------- | ------------------------------------------ | ---------------- |
| **Raw Bytes** | `application/octet-stream` | Streaming audio data, real-time processing | Query parameters |
| **Audio URL** | `application/json`         | Remote audio files, webhook processing     | Query parameters |

## Code Examples

### Method 1: Raw Audio Bytes (application/octet-stream)

<CodeGroup>
  ```bash cURL - Raw Bytes theme={null}
  curl --request POST \
    --url "https://api.smallest.ai/waves/v1/pulse/get_text?language=en&word_timestamps=true&diarize=true&age_detection=true&gender_detection=true&emotion_detection=true" \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: audio/wav' \
    --data-binary '@/path/to/your/audio.wav'
  ```

  ```python Python - Raw Bytes theme={null}
  import requests

  url = "https://api.smallest.ai/waves/v1/pulse/get_text"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "audio/wav"
  }
  params = {
      "language": "en",
      "word_timestamps": "true",
      "diarize": "true",
      "age_detection": "true",
      "gender_detection": "true",
      "emotion_detection": "true"
  }

  with open("path/to/your/audio.wav", "rb") as audio_file:
      audio_data = audio_file.read()

  response = requests.post(url, headers=headers, params=params, data=audio_data)
  result = response.json()
  print(f"Transcription: {result['transcription']}")
  ```

  ```javascript JavaScript - Raw Bytes theme={null}
  const audioFile = await fetch("/path/to/audio.wav");
  const audioBuffer = await audioFile.arrayBuffer();

  const params = new URLSearchParams({
    language: "en",
    word_timestamps: "true",
    diarize: "true",
    age_detection: "true",
    gender_detection: "true",
    emotion_detection: "true",
  });

  const response = await fetch(
    `https://api.smallest.ai/waves/v1/pulse/get_text?${params}`,
    {
      method: "POST",
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "audio/wav",
      },
      body: audioBuffer,
    }
  );

  const result = await response.json();
  console.log("Transcription:", result.transcription);
  ```
</CodeGroup>

### Method 2: Audio URL (application/json)

<CodeGroup>
  ```bash cURL - Audio URL theme={null}
  curl --request POST \
    --url "https://api.smallest.ai/waves/v1/pulse/get_text?language=en&word_timestamps=true&diarize=true&age_detection=true&gender_detection=true&emotion_detection=true" \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "url": "https://example.com/audio.mp3"
    }'
  ```

  ```python Python - Audio URL theme={null}
  import requests
  import json

  url = "https://api.smallest.ai/waves/v1/pulse/get_text"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  params = {
      "language": "en",
      "word_timestamps": "true",
      "diarize": "true",
      "age_detection": "true",
      "gender_detection": "true",
      "emotion_detection": "true"
  }
  payload = {
      "url": "https://example.com/audio.mp3"
  }

  response = requests.post(url, headers=headers, params=params, data=json.dumps(payload))
  result = response.json()
  print(f"Transcription: {result['transcription']}")
  ```

  ```javascript JavaScript - Audio URL theme={null}
  const params = new URLSearchParams({
    language: "en",
    word_timestamps: "true",
    diarize: "true",
    age_detection: "true",
    gender_detection: "true",
    emotion_detection: "true",
  });

  const payload = {
    url: "https://example.com/audio.mp3",
  };

  const response = await fetch(
    `https://api.smallest.ai/waves/v1/pulse/get_text?${params}`,
    {
      method: "POST",
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify(payload),
    }
  );

  const result = await response.json();
  console.log("Transcription:", result.transcription);
  ```
</CodeGroup>

## Supported Languages

The Pulse STT model supports **automatic language detection** and transcription across **30+ languages**.

For the full list of supported languages, please check [**STT Supported Languages**](/v4.0.0/content/getting-started/models#model-overview-stt).

<Info>
  Specify the **language** of the input audio using its [ISO
  639-1](https://en.wikipedia.org/wiki/ISO_639-1) code. Use **`multi`** to
  enable automatic language detection from the supported list. The default is
  **`en`** (English).
</Info>


## OpenAPI

````yaml POST /waves/v1/pulse/get_text
openapi: 3.0.1
info:
  title: Pulse ASR API
  description: |
    API for speech-to-text conversion using the Pulse ASR model.
    Upload audio files and receive transcribed text using the Pulse model.
  version: 1.0.0
servers:
  - url: https://api.smallest.ai
    description: Waves API server
security: []
paths:
  /waves/v1/pulse/get_text:
    post:
      tags:
        - Speech to Text
      summary: Convert speech to text
      description: >-
        Convert speech to text using the Pulse ASR model. Supports two input
        methods - raw audio bytes (application/octet-stream) with query
        parameters, or audio URL (application/json) with URL in body.
      operationId: speechToText
      parameters:
        - name: language
          in: query
          required: false
          schema:
            type: string
            enum:
              - it
              - es
              - en
              - pt
              - hi
              - de
              - fr
              - uk
              - ru
              - kn
              - ml
              - pl
              - mr
              - gu
              - cs
              - sk
              - te
              - or
              - nl
              - bn
              - lv
              - et
              - ro
              - pa
              - fi
              - sv
              - bg
              - ta
              - hu
              - da
              - lt
              - mt
              - multi
            default: en
          description: >-
            Language of the audio file. Use `multi` for automatic language
            detection
        - name: webhook_url
          in: query
          required: false
          schema:
            type: string
            format: uri
            description: URL to the webhook to receive the transcription results
            example: https://example.com/webhook
        - name: webhook_extra
          in: query
          required: false
          schema:
            type: string
            description: >-
              Extra parameters to pass to the transcription. These will be added
              to the request body as a JSON object. Add comma separated
              key-value pairs to the query string. eg
              "custom_key:custom_value,custom_key2:custom_value2"
            example: custom_key:custom_value,custom_key2:custom_value2
        - name: word_timestamps
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: >-
            Whether to include word and utterance level timestamps in the
            response
        - name: diarize
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Whether to perform speaker diarization
        - name: age_detection
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
            default: 'false'
          description: Whether to predict age group of the speaker
        - name: gender_detection
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
            default: 'false'
          description: Whether to predict the gender of the speaker
        - name: emotion_detection
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
            default: 'false'
          description: Whether to predict speaker emotions
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
              description: >-
                Raw audio bytes. Content-Type header should specify the audio
                format (e.g., audio/wav, audio/mp3). All parameters are passed
                as query parameters.
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                  description: >-
                    URL to the audio file to transcribe. Must be publicly
                    accessible
                  example: https://example.com/audio.mp3
              required:
                - url
            example:
              url: https://example.com/audio.mp3
      responses:
        '200':
          description: Speech transcribed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Status of the transcription request
                    example: success
                  transcription:
                    type: string
                    description: The transcribed text from the audio file
                    example: Hello world.
                  audio_length:
                    type: number
                    description: Duration of the audio file in seconds
                    example: 1.7
                  words:
                    type: array
                    description: Word-level timestamps in seconds.
                    items:
                      type: object
                      properties:
                        start:
                          type: number
                          example: 0
                        end:
                          type: number
                          example: 0.5
                        speaker:
                          type: string
                          description: Speaker if diarization is enabled
                          example: speaker_0
                        word:
                          type: string
                          example: Hello
                  utterances:
                    type: array
                    description: List of utterances with start and end times
                    items:
                      type: object
                      properties:
                        text:
                          type: string
                          example: Hello world.
                        start:
                          type: number
                          example: 0
                        end:
                          type: number
                          example: 0.9
                        speaker:
                          type: string
                          description: Speaker if diarization is enabled
                          example: speaker_0
                  age:
                    type: string
                    description: >-
                      Predicted age group of the speaker (e.g., infant,
                      teenager, adult, old)
                    example: adult
                    enum:
                      - infant
                      - teenager
                      - adult
                      - old
                  gender:
                    type: string
                    description: Predicted gender of the speaker if requested
                    example: male
                    enum:
                      - male
                      - female
                  emotions:
                    type: object
                    description: Predicted emotions of the speaker if requested
                    properties:
                      happiness:
                        type: number
                        format: float
                        example: 0.8
                      sadness:
                        type: number
                        format: float
                        example: 0.15
                      disgust:
                        type: number
                        format: float
                        example: 0.02
                      fear:
                        type: number
                        format: float
                        example: 0.03
                      anger:
                        type: number
                        format: float
                        example: 0.05
                  metadata:
                    type: object
                    description: Metadata about the transcription
                    properties:
                      filename:
                        type: string
                        description: Name of the audio file
                        example: audio.mp3
                      duration:
                        type: number
                        description: Duration of the audio file in minutes
                        example: 1.7
                      fileSize:
                        type: number
                        description: Size of the audio file in bytes
                        example: 1000000
              example:
                status: success
                transcription: Hello world.
                words:
                  - start: 0
                    end: 0.5
                    speaker: speaker_0
                    word: Hello
                  - start: 0.6
                    end: 0.9
                    speaker: speaker_0
                    word: world.
                utterances:
                  - text: Hello world.
                    start: 0
                    end: 0.9
                    speaker: speaker_0
                age: adult
                gender: male
                emotions:
                  happiness: 0.8
                  sadness: 0.15
                  disgust: 0.02
                  fear: 0.03
                  anger: 0.05
                metadata:
                  filename: audio.mp3
                  duration: 1.7
                  fileSize: 1000000
        '400':
          description: Bad request - Invalid parameters or file format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: 'Invalid file format. Supported formats: audio/*'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Unauthorized - Invalid API key
        '413':
          description: Payload too large - File size exceeds limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: File size exceeds maximum limit of 25MB
        '429':
          description: Too many requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Rate limit exceeded. Please try again later.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
      security:
        - BearerAuth: []
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message describing what went wrong
      required:
        - error
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer authentication header of the form `Bearer <api_key>`, where
        <api_key> is your api key.

````