openapi: 3.0.0
info:
  title: LOVO AI Genny API
  version: '1.0'
  description: >-
    REST API for LOVO AI's Genny text-to-speech and AI voice generation
    platform. Convert text into natural-sounding speech (synchronously or
    asynchronously), browse the speaker/voice catalog with its styles, and
    read team billing/usage information. Authenticate every request with the
    X-API-KEY header carrying an API key generated at https://genny.lovo.ai.
    TTS credits are deducted from the account associated with the API key.
    Generated audio URLs are valid for 24 hours and should be downloaded for
    further use. Endpoints and schemas here are grounded in Genny's published
    OpenAPI document at https://api.genny.lovo.ai/api/docs-json.
  contact:
    name: LOVO AI
    url: https://lovo.ai
servers:
  - url: https://api.genny.lovo.ai
    description: Genny API production
tags:
  - name: Text-to-Speech
    description: Convert text to speech synchronously or asynchronously and retrieve job results.
  - name: Speakers
    description: Retrieve the catalog of speakers/voices and their styles.
  - name: Pronunciation
    description: >-
      Pronunciation, pause, and emphasis controls applied to a TTS conversion.
      These are represented as data structures on the TTS output rather than a
      standalone endpoint.
  - name: Teams
    description: Read team billing and usage information for the API key's account.
components:
  securitySchemes:
    X-API-KEY:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key generated at https://genny.lovo.ai (profile tab).
  schemas:
    Pronunciation:
      type: object
      description: A word-level pronunciation override applied to a TTS conversion.
      properties:
        sourceWord:
          type: string
          description: The original word as written in the input text.
        targetWord:
          type: string
          description: The replacement spelling/phonetic form used for synthesis.
        isReplaced:
          type: boolean
          description: Whether the source word was replaced during synthesis.
      required:
        - sourceWord
        - targetWord
        - isReplaced
    Pause:
      type: object
      description: A pause inserted at a position within the synthesized text.
      properties:
        position:
          type: number
          description: Character position at which the pause is inserted.
        value:
          type: number
          minimum: 0
          maximum: 2
          description: Pause duration in seconds (0 to 2).
      required:
        - position
        - value
    Emphasis:
      type: object
      description: An emphasis marker applied at a position within the synthesized text.
      properties:
        position:
          type: number
          description: Character position at which emphasis is applied.
        value:
          type: number
          enum:
            - 0.25
            - 0.5
            - 0.75
          description: Emphasis strength.
      required:
        - position
        - value
    PublicSpeakerStyleResType:
      type: object
      properties:
        id:
          type: string
        displayName:
          type: string
        deprecated:
          type: boolean
          description: Deprecated speaker styles should not be used in the TTS API.
        sampleTtsUrl:
          type: string
          description: Sample TTS URL to preview the voice of the speaker.
      required:
        - id
        - displayName
        - deprecated
        - sampleTtsUrl
    GetSpeakersApiResponse:
      type: object
      properties:
        id:
          type: string
          description: Speaker ID.
        displayName:
          type: string
          description: Name of the speaker.
        locale:
          type: string
          description: Locale of the speaker (for example en-US, en-GB, ko-KR).
        gender:
          type: string
          enum:
            - male
            - female
            - other
        imageUrl:
          type: string
          description: Avatar URL of the speaker.
        ageRange:
          type: string
          enum:
            - child
            - children
            - young_adult
            - mature
            - mature_adult
            - old
            - other
        speakerStyles:
          $ref: '#/components/schemas/PublicSpeakerStyleResType'
      required:
        - id
        - displayName
        - locale
        - gender
        - imageUrl
    PaginatedResDto:
      type: object
      properties:
        totalCount:
          type: number
          description: Total item count available for pagination.
        count:
          type: number
          description: Item count for the current page.
        page:
          type: number
          description: Current page number.
        limit:
          type: number
          description: Limit of items per page.
        data:
          type: array
          items:
            $ref: '#/components/schemas/GetSpeakersApiResponse'
      required:
        - totalCount
        - count
        - data
    TextToSpeechRequest:
      type: object
      properties:
        text:
          type: string
          minLength: 1
          maxLength: 500
          description: Text to be converted to audio.
          example: Welcome to Genny!
        speaker:
          type: string
          description: Speaker ID retrieved from the Retrieve Speakers endpoint.
          example: 640f477d2babeb0024be422b
        speakerStyle:
          type: string
          description: Speaker style ID for the chosen speaker. Only some speakers have multiple styles.
        speed:
          type: number
          default: 1
          minimum: 0.05
          maximum: 3
          description: Speed of the generated audio.
        callbackUrls:
          type: array
          maxItems: 4
          items:
            type: string
          description: >-
            Callback URLs for an async job (max 4). A single POST callback with
            the same payload as the Async Retrieve Job endpoint is sent on
            completion. Endpoints must return a 2xx within 10 seconds.
      required:
        - text
        - speaker
    TextToSpeechSyncRequest:
      type: object
      properties:
        text:
          type: string
          minLength: 1
          maxLength: 500
          description: Text to be converted to audio.
          example: Welcome to Genny!
        speaker:
          type: string
          description: Speaker ID retrieved from the Retrieve Speakers endpoint.
          example: 640f477d2babeb0024be422b
        speakerStyle:
          type: string
          description: Speaker style ID for the chosen speaker.
        speed:
          type: number
          default: 1
          minimum: 0.05
          maximum: 3
          description: Speed of the generated audio.
      required:
        - text
        - speaker
    JobErrorResponse:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message
    TextToSpeechOutput:
      type: object
      properties:
        status:
          type: string
          enum:
            - pending
            - succeeded
            - failed
          description: Status of the individual TTS output.
        text:
          type: string
        speaker:
          type: string
        speakerStyle:
          type: string
        speed:
          type: number
        pause:
          type: array
          items:
            $ref: '#/components/schemas/Pause'
        emphasis:
          type: array
          items:
            $ref: '#/components/schemas/Emphasis'
        pronunciations:
          type: array
          default: []
          items:
            $ref: '#/components/schemas/Pronunciation'
          description: Pronunciations applied to the TTS request.
        urls:
          type: array
          items:
            type: string
          description: Audio URLs of the TTS result (valid for 24 hours).
        error:
          $ref: '#/components/schemas/JobErrorResponse'
      required:
        - status
        - text
        - speaker
        - speakerStyle
        - speed
        - pause
        - emphasis
        - pronunciations
    GetJobResponse:
      type: object
      properties:
        id:
          type: string
          example: 643e383551e2730025c5ae69
          description: Job ID used to check the progress of the TTS job.
        type:
          type: string
          enum:
            - tts
            - simple_tts
            - dubbing
            - localization
            - subtitles
          description: Type of the job. Currently only TTS is supported.
        status:
          type: string
          enum:
            - in_progress
            - done
        progress:
          type: number
        team:
          type: string
        workspace:
          type: string
        project:
          type: string
        error:
          $ref: '#/components/schemas/JobErrorResponse'
        createdAt:
          type: string
          format: date-time
          description: TTS requested time.
        estimatedTimeAt:
          type: string
          format: date-time
        estimatedTimeMs:
          type: number
        callbackUrls:
          type: array
          items:
            type: string
      required:
        - id
        - type
        - status
        - progress
        - team
        - createdAt
        - callbackUrls
    TextToSpeechResponse:
      allOf:
        - $ref: '#/components/schemas/GetJobResponse'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/TextToSpeechOutput'
          required:
            - data
    TextToSpeechSyncResponse:
      allOf:
        - $ref: '#/components/schemas/GetJobResponse'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/TextToSpeechOutput'
          required:
            - data
    TeamForApiResDto:
      type: object
      properties:
        name:
          type: string
        createdAt:
          type: string
          format: date-time
      required:
        - name
        - createdAt
    ApiUsageResDto:
      type: object
      properties:
        type:
          type: string
        unit:
          type: string
        amount:
          type: string
        currentPeriodStart:
          type: string
          format: date-time
        currentPeriodEnd:
          type: string
          format: date-time
      required:
        - type
        - unit
        - amount
    Subscription:
      type: object
      properties:
        status:
          type: string
          enum:
            - active
            - pending_pause
            - paused
            - trialing
            - past_due
            - canceled
            - unpaid
            - incomplete
            - incomplete_expired
        currentPeriodStart:
          type: string
          format: date-time
        currentPeriodEnd:
          type: string
          format: date-time
        description:
          type: string
        priceInterval:
          type: string
          enum:
            - year
            - month
            - onetime
            - day
        usage:
          type: array
          items:
            $ref: '#/components/schemas/ApiUsageResDto'
      required:
        - status
        - currentPeriodStart
        - currentPeriodEnd
        - priceInterval
        - usage
    ApiTeamBillingInformationResDto:
      type: object
      properties:
        team:
          $ref: '#/components/schemas/TeamForApiResDto'
        subscription:
          $ref: '#/components/schemas/Subscription'
      required:
        - team
        - subscription
security:
  - X-API-KEY: []
paths:
  /api/v1/tts:
    post:
      operationId: async-tts
      summary: Async TTS
      description: >-
        Returns a TTS job. Poll the job status with GET /api/v1/tts/{jobId}
        using the returned id, or supply callbackUrls to be notified on
        completion.
      tags:
        - Text-to-Speech
      security:
        - X-API-KEY: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TextToSpeechRequest'
            examples:
              default:
                value:
                  speaker: 640f477d2babeb0024be422b
                  text: Welcome to Genny!
      responses:
        '201':
          description: Job entity used to fetch the status of the TTS job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetJobResponse'
        '400':
          description: API key expired
        '401':
          description: API key invalid
        '402':
          description: No active subscription
        '422':
          description: API key not found
  /api/v1/tts/sync:
    post:
      operationId: sync-tts
      summary: Sync TTS
      description: >-
        Convert text to speech synchronously. Has a timeout of 90 seconds; if
        the process does not complete in time, it returns a pending TTS job
        (like Async TTS) whose status can be checked with GET
        /api/v1/tts/{jobId}.
      tags:
        - Text-to-Speech
      security:
        - X-API-KEY: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TextToSpeechSyncRequest'
            examples:
              default:
                value:
                  speaker: 640f477d2babeb0024be422b
                  text: Welcome to Genny!
      responses:
        '201':
          description: Generated audio URLs if completed within 90 seconds, otherwise an incomplete TTS job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TextToSpeechSyncResponse'
        '400':
          description: API key expired
        '401':
          description: API key invalid
        '402':
          description: No active subscription
        '422':
          description: API key not found
  /api/v1/tts/{jobId}:
    get:
      operationId: async-retrieve-job
      summary: Async Retrieve Job
      description: >-
        Retrieve a TTS job by id. Returns generated audio URLs if the job is
        successfully completed.
      tags:
        - Text-to-Speech
      security:
        - X-API-KEY: []
      parameters:
        - name: jobId
          in: path
          required: true
          description: The job id returned by an Async or Sync TTS request.
          schema:
            type: string
      responses:
        '200':
          description: The TTS job, including audio URLs when completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TextToSpeechResponse'
        '400':
          description: API key expired
        '401':
          description: API key invalid
        '422':
          description: Job not found
  /api/v1/speakers:
    get:
      operationId: retrieve-speakers
      summary: Retrieve speakers
      description: Retrieve all speakers with optional filtering and sorting. Supports pagination.
      tags:
        - Speakers
      security:
        - X-API-KEY: []
      parameters:
        - name: sort
          in: query
          required: false
          description: >-
            Sort by given order. Available fields are displayName, locale,
            gender, speakerType, and ageRange. Example "displayName:1" (no
            whitespace).
          schema:
            type: array
            default:
              - displayName:1
            items:
              type: string
        - name: page
          in: query
          required: false
          description: Number of pages to skip.
          schema:
            type: number
        - name: limit
          in: query
          required: false
          description: Number of speakers in each page.
          schema:
            type: number
      responses:
        '200':
          description: A paginated list of speakers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResDto'
        '400':
          description: API key expired
        '401':
          description: API key invalid
        '422':
          description: API key not found
  /api/v1/teams/status:
    get:
      operationId: get-team-billing-information
      summary: Get team billing information
      description: Get team billing and usage information for the account associated with the API key.
      tags:
        - Teams
      security:
        - X-API-KEY: []
      responses:
        '200':
          description: Team billing information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiTeamBillingInformationResDto'
        '400':
          description: API key expired
        '401':
          description: API key invalid
        '422':
          description: API key not found