> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withhopper.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List voices

> Lists platform voices plus your org's own voices, cursor-paginated.



## OpenAPI

````yaml /api-reference/openapi.json get /voices
openapi: 3.1.0
info:
  title: Hopper API
  version: 1.0.0
  description: >-
    Inference for voice agents: LLM, text to speech, and speech to text at
    api.withhopper.com. OpenAI-compatible routes are served under /v1; native
    routes are served at the root. All errors use the OpenAI envelope.
servers:
  - url: https://api.withhopper.com
security:
  - bearerAuth: []
tags:
  - name: LLM
    description: OpenAI-compatible chat completions and model listing.
  - name: Text to Speech
    description: >-
      Speech synthesis: native /tts routes and the OpenAI-compatible
      /v1/audio/speech.
  - name: Speech to Text
    description: Batch transcription. Streaming runs over WS /stt/websocket.
  - name: Voices
    description: Voice library, cloning, profiles, and localization.
  - name: Pronunciation
    description: Pronunciation dictionaries applied at synthesis time.
  - name: Jobs
    description: Status of async voice jobs.
  - name: Health
    description: Unauthenticated liveness check.
paths:
  /voices:
    get:
      tags:
        - Voices
      summary: List voices
      description: Lists platform voices plus your org's own voices, cursor-paginated.
      parameters:
        - name: scope
          in: query
          schema:
            type: string
            enum:
              - featured
              - all
              - mine
              - saved
            default: all
          description: Which voices to list.
        - name: gender
          in: query
          schema:
            type: string
          description: Filter by gender.
        - name: language
          in: query
          schema:
            type: string
          description: Filter by language.
        - name: tag
          in: query
          schema:
            type: string
          description: Filter by tag.
        - name: q
          in: query
          schema:
            type: string
          description: Search query.
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
          description: Page size.
        - name: cursor
          in: query
          schema:
            type: string
          description: Cursor from a previous page's next_cursor.
      responses:
        '200':
          description: One page of voices. next_cursor is null on the last page.
          content:
            application/json:
              schema:
                type: object
                properties:
                  voices:
                    type: array
                    items:
                      $ref: '#/components/schemas/Voice'
                  next_cursor:
                    type:
                      - string
                      - 'null'
        '400':
          description: 'Invalid scope or limit. Codes: invalid_scope, invalid_limit.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    Voice:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type:
            - string
            - 'null'
        language:
          type:
            - string
            - 'null'
        gender:
          type:
            - string
            - 'null'
        tags:
          type: array
          items:
            type: string
        featured:
          type: boolean
        source:
          type: string
          enum:
            - library
            - instant_clone
            - pro_clone
            - localized
        parent_voice_id:
          type:
            - string
            - 'null'
        source_audio_blob_id:
          type:
            - string
            - 'null'
        source_transcript:
          type:
            - string
            - 'null'
        source_metadata:
          type: object
        source_version:
          type:
            - string
            - 'null'
        profiles:
          type: array
          items:
            $ref: '#/components/schemas/VoiceProfile'
        model_family:
          type:
            - string
            - 'null'
          deprecated: true
        sample_blob_id:
          type:
            - string
            - 'null'
          deprecated: true
        is_owner:
          type: boolean
          description: True when your org owns the voice.
        saved:
          type: boolean
        created_at:
          type: string
    Error:
      type: object
      description: OpenAI error envelope, used by every error response.
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
            code:
              type: string
            param:
              type:
                - string
                - 'null'
    VoiceProfile:
      type: object
      description: >-
        Per-model preparation of a voice. TTS requests need a ready profile for
        the target model.
      properties:
        model_id:
          type: string
        upstream_id:
          type:
            - string
            - 'null'
        profile_kind:
          type: string
          enum:
            - voice_ref
            - icl
            - embedding
        profile_version:
          type:
            - string
            - 'null'
        source_version:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - pending
            - ready
            - failed
        cached_at:
          type:
            - string
            - 'null'
        expires_at:
          type:
            - string
            - 'null'
  responses:
    Unauthorized:
      description: >-
        Missing, malformed, or revoked API key. Codes: invalid_api_key,
        api_key_disabled.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: >-
                Incorrect API key provided. Check your key at
                https://withhopper.com/dashboard.
              type: invalid_request_error
              code: invalid_api_key
              param: null
    PaymentRequired:
      description: Credit balance is zero.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: You have run out of credits. Contact us to add more.
              type: insufficient_quota
              code: insufficient_quota
              param: null
    RateLimited:
      description: >-
        Over 600 requests per minute on this key. Retry after the number of
        seconds in Retry-After.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: >-
                Rate limit reached: 600 requests per minute per key. Retry after
                21s.
              type: rate_limit_error
              code: rate_limit_exceeded
              param: null
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key in the Authorization header: Bearer sk_hopper_... Keys are
        minted in the dashboard at withhopper.com/console/keys and shown once at
        creation. WebSocket connections also accept ?api_key=.

````