dialogbrain-com Voice Clones API

openapi: 3.2.0
info:
  title: DialogBrain v2 API Gateway Voice Clones API
  description: Clean refactored API gateway with minimal vertical slice
  version: 0.1.0
tags:
- name: voice-clones
paths:
  /api/voice-clones/enroll:
    post:
      tags:
      - voice-clones
      summary: Enroll
      description: 'Enroll a voice clone. See module docstring for the request-flow order.


        Multipart fields:

        audio (file, WAV only in v1, ≤ 20 MB)

        provider (''alibaba'' | ''cartesia'')

        label 1–80 chars, free text

        consent_accepted "true" — defense-in-depth; UI checkbox already gates

        language_hint ''en''|''ru''|''zh''|… (optional, passed to vendor)


        Required header:

        Idempotency-Key UUIDv4 per attempt-batch; replay returns the

        original row with no vendor call.'
      operationId: enroll_api_voice_clones_enroll_post
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Idempotency-Key
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_enroll_api_voice_clones_enroll_post'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Enroll Api Voice Clones Enroll Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/voice-clones:
    get:
      tags:
      - voice-clones
      summary: List Voices
      description: 'List active clones for the caller''s workspace. Filterable by provider.


        `created_by_email` is resolved via LEFT JOIN to `users` (canonical

        table name — `app_users` does not exist in this codebase). The users

        table has no `deleted_at` column; deactivated users (is_active=false)

        still surface their email in the audit list by design.'
      operationId: list_voices_api_voice_clones_get
      parameters:
      - name: provider
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
                title: Response List Voices Api Voice Clones Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/voice-clones/{clone_id}:
    patch:
      tags:
      - voice-clones
      summary: Patch Clone
      description: 'Update label/language_hint. Cross-workspace requests return 404

        (not 403 — does not confirm existence). Bumps updated_at.'
      operationId: patch_clone_api_voice_clones__clone_id__patch
      parameters:
      - name: clone_id
        in: path
        required: true
        schema:
          type: integer
          title: Clone Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Patch Clone Api Voice Clones  Clone Id  Patch
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - voice-clones
      summary: Delete Clone
      description: 'Soft-archive by default; ?hard=true wipes the row + storage blobs.


        Soft path is reversible (status=''archived'' is set; row stays for audit).

        Hard path is the GDPR right-to-erasure flow — vendor delete + S3 wipe

        + row drop. Cross-workspace requests return 404.'
      operationId: delete_clone_api_voice_clones__clone_id__delete
      parameters:
      - name: clone_id
        in: path
        required: true
        schema:
          type: integer
          title: Clone Id
      - name: hard
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Hard
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/voice-clones/{clone_id}/preview:
    get:
      tags:
      - voice-clones
      summary: Preview Clone
      description: 'Cached preview WAV. First call routes through tts_registry preview

        with the cloned vendor_voice_id, stores the result at

        voice-clones-previews/{vendor_voice_id}.wav, and serves a presigned

        URL. Subsequent calls skip the vendor and serve from the cache.


        Cache key uses `vendor_voice_id` (NOT the BIGSERIAL id) so a sequence

        reuse edge case can''t serve a stale blob for a different clone.


        Cross-workspace requests return 404.'
      operationId: preview_clone_api_voice_clones__clone_id__preview_get
      parameters:
      - name: clone_id
        in: path
        required: true
        schema:
          type: integer
          title: Clone Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    Body_enroll_api_voice_clones_enroll_post:
      properties:
        audio:
          type: string
          contentMediaType: application/octet-stream
          title: Audio
        provider:
          type: string
          title: Provider
        label:
          type: string
          title: Label
        consent_accepted:
          type: string
          title: Consent Accepted
        language_hint:
          anyOf:
          - type: string
          - type: 'null'
          title: Language Hint
      type: object
      required:
      - audio
      - provider
      - label
      - consent_accepted
      title: Body_enroll_api_voice_clones_enroll_post
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError