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

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
      security:
        - BearerAuth: []
      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"
      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
      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.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.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.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.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"

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        API key authentication using Bearer token format.
        Include your API key in the Authorization header as: `Bearer YOUR_API_KEY`

  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message describing what went wrong
      required:
        - error