openapi: 3.1.0
info:
  title: Flow Voice API
  description: Speech-to-text API with advanced context awareness and language detection
  version: '2.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
                - language
                - context
              properties:
                audio:
                  type: string
                  description: Base64-encoded, 16kHz wav audio in PCM16 format (16-bit signed integer). Max size is 25MB / 6 minutes of audio
                  example: 'UklGRiQA....'
                language:
                  type: array
                  items:
                    type: string
                  description: The list of languages the user might speak, set to one to skip language detection, set to empty to look through entire language list
                  example: ['en', 'fr']
                  default: []
                context:
                  type: object
                  description: Additional information about the context surrounding the dictation
                  properties:
                    app:
                      type: object
                      properties:
                        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_context:
                      type: array
                      items:
                        type: string
                      description: List of uncommon names or phrases relevant to the topic to help with transcription accuracy
                      default: []
                    user_identifier:
                      type: string
                      description: ...
                    user_first_name:
                      type: string
                      description: ...
                    user_last_name:
                      type: string
                      description: ...
                    textbox_contents:
                      type: object
                      description: Additional information about the context surrounding the dictation
                      properties:
                        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: ''
                        after_text:
                          type: string
                          description: The text immediately after the cursor. Flow uses it to decide spacing / punctuation.
                          default: ''
                    screenshot:
                      type: string
                      description: Base64-encoded screenshot of the screen or the foregrounded app, used in cases where the user is speaking about something on the screen
                    content_text:
                      type: string
                      description: Text context of the foreground app that is relevant to the dictation
                    content_html:
                      type: string
                      description: HTML context of the foreground app that is relevant to the dictation
                    conversation:
                      type: object
                      description: Chat history that the dictation is happenin in, useful when user is dictating in a messaging app or chatbot
                      properties:
                        id:
                          type: string
                          description: A unique conversation ID
                        participants:
                          type: array
                          items:
                            type: string
                          description: List of names of participants in the conversation so Flow can get the names right
                        messages:
                          type: array
                          items:
                            type: object
                            properties:
                              role:
                                type: string
                                enum: [user, human, assistant]
                              content:
                                type: string
                                description: Text content of the message in the conversation

      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>