openapi: 3.1.0
info:
  title: Brainiall Specialist AI APIs
  version: 1.0.1
  summary: Production-ready AI APIs for regulated workloads
  description: 5 specialty SKUs (Background Removal, Audio Enhancement, Speaker Diarization, PDF-to-Markdown, Agent Memory)
    plus Speech AI / NLP Suite / Image Processing. OpenAI-compatible Bearer auth.
  termsOfService: https://app.brainiall.com/terms
  contact:
    name: Brainiall Support
    url: https://app.brainiall.com/contact
    email: support@brainiall.com
  license:
    name: Brainiall Terms of Service
    url: https://app.brainiall.com/terms
servers:
- url: https://api.brainiall.com
  description: Production
tags:
- name: S1 Background Removal
  description: Drop-in replacement for Azure Image Analysis 4.0
- name: S2 Audio Enhancement
  description: Denoise, voice isolation, cleanup, master in one API
- name: S3 Speaker Diarization
  description: pyannote 3.1 standalone diarization
- name: S4 PDF to Markdown
  description: Marker engine, equation/table-aware
- name: S5 Agent Memory
  description: Multi-tenant semantic memory (Mem0 alternative)
- name: Speech AI
  description: Pronunciation / STT / TTS / Whisper STT Pro
- name: NLP Suite
  description: Toxicity / Sentiment / Entities / PII / Language
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: brnl-<product>-<hex>
      description: Get a free API key at https://app.brainiall.com
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
    BackgroundRemovalRequest:
      type: object
      required:
      - image
      properties:
        image:
          type: string
          format: byte
          description: Base64-encoded PNG/JPEG/WebP
        tier:
          type: string
          enum:
          - fast
          - hd
          default: fast
        output_format:
          type: string
          enum:
          - png
          - webp
          default: png
    ImageResponse:
      type: object
      required:
      - image
      properties:
        image:
          type: string
          format: byte
    AudioRequest:
      type: object
      required:
      - audio
      properties:
        audio:
          type: string
          format: byte
        output_format:
          type: string
          enum:
          - wav
          - mp3
          - ogg
          default: wav
        options:
          type: object
          additionalProperties: true
    AudioResponse:
      type: object
      required:
      - audio
      properties:
        audio:
          type: string
          format: byte
        duration_s:
          type: number
    DiarizeRequest:
      type: object
      required:
      - audio
      properties:
        audio:
          type: string
          format: byte
        min_speakers:
          type: integer
          minimum: 1
          default: 1
        max_speakers:
          type: integer
          minimum: 1
          default: 10
    DiarizeTurn:
      type: object
      required:
      - speaker
      - start
      - end
      properties:
        speaker:
          type: string
          example: SPEAKER_00
        start:
          type: number
          format: float
        end:
          type: number
          format: float
        duration:
          type: number
          format: float
    DiarizeResponse:
      type: object
      properties:
        duration_s:
          type: number
        model:
          type: string
          example: pyannote/speaker-diarization-3.1
        tier:
          type: string
        num_speakers_detected:
          type: integer
        num_turns:
          type: integer
        turns:
          type: array
          items:
            $ref: '#/components/schemas/DiarizeTurn'
        processing_time_s:
          type: number
    PdfRequest:
      type: object
      required:
      - pdf
      properties:
        pdf:
          type: string
          format: byte
        tier:
          type: string
          enum:
          - fast
          default: fast
    MemoryAddRequest:
      type: object
      required:
      - text
      properties:
        text:
          type: string
          minLength: 1
          maxLength: 8192
        metadata:
          type: object
          additionalProperties: true
    MemoryAddResponse:
      type: object
      properties:
        id:
          type: integer
        namespace:
          type: string
        text:
          type: string
    MemorySearchHit:
      type: object
      properties:
        id:
          type: integer
        text:
          type: string
        score:
          type: number
          format: float
          description: Cosine similarity (0-1, higher is more similar)
        created_at:
          type: number
          format: float
          description: Unix timestamp when added
        metadata:
          type: object
          additionalProperties: true
    MemorySearchResponse:
      type: object
      properties:
        namespace:
          type: string
        query:
          type: string
        results:
          type: array
          items:
            $ref: '#/components/schemas/MemorySearchHit'
        tier:
          type: string
          example: fast
        model:
          type: string
          example: BAAI/bge-small-en-v1.5
security:
- BearerAuth: []
paths:
  /v1/image/remove-background/base64:
    post:
      tags:
      - S1 Background Removal
      summary: Remove background from image
      description: 'Two tiers: Fast (rembg U2-Net, ~0.4s) or HD (BiRefNet, mIoU 0.95, ~2s).'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BackgroundRemovalRequest'
      responses:
        '200':
          description: Image processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageResponse'
        '400':
          description: Invalid input
        '401':
          description: Unauthorized
        '429':
          description: Rate limit exceeded
  /v1/audio/enhance/denoise:
    post:
      tags:
      - S2 Audio Enhancement
      summary: Denoise audio (DeepFilterNet 3)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AudioRequest'
      responses:
        '200':
          description: Cleaned audio
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudioResponse'
  /v1/audio/enhance/voice-isolation:
    post:
      tags:
      - S2 Audio Enhancement
      summary: Isolate vocals (Demucs htdemucs)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AudioRequest'
      responses:
        '200':
          description: Isolated vocals
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudioResponse'
  /v1/audio/enhance/cleanup:
    post:
      tags:
      - S2 Audio Enhancement
      summary: Remove filler words (Whisper)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AudioRequest'
      responses:
        '200':
          description: Cleaned audio
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudioResponse'
  /v1/audio/enhance/master:
    post:
      tags:
      - S2 Audio Enhancement
      summary: Master to -14 LUFS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AudioRequest'
      responses:
        '200':
          description: Mastered audio
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudioResponse'
  /v1/audio/diarize/base64:
    post:
      tags:
      - S3 Speaker Diarization
      summary: Diarize speakers in audio
      description: pyannote 3.1 speaker diarization. 12% DER on AMI.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiarizeRequest'
      responses:
        '200':
          description: Diarization result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiarizeResponse'
  /v1/document/pdf-to-markdown/base64:
    post:
      tags:
      - S4 PDF to Markdown
      summary: Convert PDF to Markdown
      description: 'Marker engine, preserves headings, tables, equations. Returns raw markdown body (Content-Type: text/markdown).'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PdfRequest'
      responses:
        '200':
          description: Markdown text
          content:
            text/markdown:
              schema:
                type: string
  /v1/memory/{namespace}/add:
    post:
      tags:
      - S5 Agent Memory
      summary: Add fact to namespace
      parameters:
      - name: namespace
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z0-9_-]{1,64}$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemoryAddRequest'
      responses:
        '200':
          description: Added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemoryAddResponse'
  /v1/memory/{namespace}/search:
    get:
      tags:
      - S5 Agent Memory
      summary: Semantic search in namespace
      parameters:
      - name: namespace
        in: path
        required: true
        schema:
          type: string
      - name: q
        in: query
        required: true
        schema:
          type: string
      - name: k
        in: query
        schema:
          type: integer
          default: 5
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: Top-k hits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemorySearchResponse'
  /v1/pronunciation/assess/base64:
    post:
      tags:
      - Speech AI
      summary: Score pronunciation accuracy
      responses:
        '200':
          description: Pronunciation scores
  /v1/stt/transcribe/base64:
    post:
      tags:
      - Speech AI
      summary: Speech to text (Conformer-CTC)
      responses:
        '200':
          description: Transcription with word timestamps
  /v1/tts/synthesize/base64:
    post:
      tags:
      - Speech AI
      summary: Text to speech (Kokoro)
      responses:
        '200':
          description: Synthesized audio
  /v1/whisper/transcribe/base64:
    post:
      tags:
      - Speech AI
      summary: Whisper Large V3 Turbo (99 languages)
      responses:
        '200':
          description: Transcription + word timestamps + optional speaker labels
  /v1/nlp/toxicity:
    post:
      tags:
      - NLP Suite
      summary: Toxicity detection
      responses:
        '200':
          description: Toxicity score
  /v1/nlp/sentiment:
    post:
      tags:
      - NLP Suite
      summary: Sentiment analysis
      responses:
        '200':
          description: Sentiment label + score
  /v1/nlp/entities:
    post:
      tags:
      - NLP Suite
      summary: Named entity recognition
      responses:
        '200':
          description: Entity list
  /v1/nlp/pii:
    post:
      tags:
      - NLP Suite
      summary: PII detection (BERT + regex)
      responses:
        '200':
          description: Detected PII spans
  /v1/nlp/language:
    post:
      tags:
      - NLP Suite
      summary: Language detection
      responses:
        '200':
          description: Language code + confidence