openapi: 3.1.0
info:
  title: Flow Voice API
  description: Speech-to-text API with advanced context awareness and language detection
  version: '1.0.0'

servers:
  - url: 'https://platform-api.wisprflow.ai/api/v1/dash'
    description: Production server

paths:
  /api:
    post:
      summary: Convert speech to text
      description: Transcribe audio with support for multiple languages and context awareness
      operationId: transcribeAudio
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - audio
                - properties
              properties:
                audio:
                  type: string
                  description: base64 encoded, 16kHz wav audio. Max size is 25MB / 6 minutes of audio
                  example: 'UklGRiQA....'
                properties:
                  type: object
                  description: Additional configuration properties for the transcription
                  properties:
                    language:
                      type: string
                      description: 2-digit ISO language code
                      example: 'en'
                      default: 'en'
                    app_type:
                      type: string
                      enum: [ai, email, other]
                      description: Flow formats appropriately depending on if the user is prompting AI, writing an email, or other tasks.
                      default: 'other'
                    dictionary:
                      type: array
                      items:
                        type: string
                      description: List of dictionary words to help with transcription accuracy
                      default: []
                    after_text:
                      type: string
                      description: The text immediately after the cursor. Flow uses it to decide spacing / punctuation.
                      default: ''
                    before_text:
                      type: string
                      description: The text immediately before the cursor. Flow uses it to decide spacing / punctuation.
                      default: ''
                    selected_text:
                      type: string
                      description: The text the user has highlighted. Flow uses it to decide spacing / punctuation.
                      default: ''
      responses:
        '200':
          description: Successful transcription
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Unique identifier for the transcription
                    example: '550e8400-e29b-41d4-a716-446655440000'
                  text:
                    type: string
                    description: The transcribed text with formatting
                    example: 'Testing testing 1, 2, 3'
                  detected_language:
                    type: string
                    description: Detected language code
                    example: 'en'
                  total_time:
                    type: integer
                    description: Total processing time in milliseconds
                    example: 432
                  generated_tokens:
                    type: integer
                    description: Number of tokens used
                    example: 9
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: 'No audio data provided!'
        '401':
          description: Unauthorized
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: 'Audio file size exceeds 25MB limit'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: 'Error running inference'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: <API Key>