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

# List Voices



## OpenAPI

````yaml 2024-11-13/api.yml GET /voices
openapi: 3.0.1
info:
  title: Cartesia API
  version: '2024-11-13'
servers:
  - url: https://api.cartesia.ai
    description: Production
security: []
paths:
  /voices:
    get:
      tags:
        - Voices
      summary: List Voices
      operationId: voices_list
      parameters:
        - $ref: '#/components/parameters/CartesiaVersionHeader'
        - name: limit
          in: query
          description: The number of Voices to return per page, ranging between 1 and 100.
          required: false
          schema:
            type: integer
            nullable: true
        - name: starting_after
          in: query
          description: >-
            A cursor to use in pagination. `starting_after` is a Voice ID that
            defines your

            place in the list. For example, if you make a /voices request and
            receive 100

            objects, ending with `voice_abc123`, your subsequent call can
            include

            `starting_after=voice_abc123` to fetch the next page of the list.
          required: false
          schema:
            type: string
            nullable: true
        - name: ending_before
          in: query
          description: >-
            A cursor to use in pagination. `ending_before` is a Voice ID that
            defines your

            place in the list. For example, if you make a /voices request and
            receive 100

            objects, starting with `voice_abc123`, your subsequent call can
            include

            `ending_before=voice_abc123` to fetch the previous page of the list.
          required: false
          schema:
            type: string
            nullable: true
        - name: is_owner
          in: query
          description: Whether to only return voices owned your organization.
          required: false
          schema:
            type: boolean
            nullable: true
        - name: gender
          in: query
          description: The gender presentation of the voices to return.
          required: false
          schema:
            $ref: '#/components/schemas/GenderPresentation'
            nullable: true
        - name: expand[]
          in: query
          description: Additional fields to include in the response.
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/VoiceExpandOptions'
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetVoicesResponse'
      security:
        - ApiKeyAuth: []
components:
  parameters:
    CartesiaVersionHeader:
      name: Cartesia-Version
      in: header
      description: API version header.
      required: true
      schema:
        type: string
        format: date
        example: '2024-11-13'
        enum:
          - '2024-11-13'
  schemas:
    GenderPresentation:
      title: GenderPresentation
      type: string
      enum:
        - masculine
        - feminine
        - gender_neutral
    VoiceExpandOptions:
      title: VoiceExpandOptions
      type: string
      enum:
        - preview_file_url
    GetVoicesResponse:
      title: GetVoicesResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Voice'
          description: The paginated list of voices.
        has_more:
          type: boolean
          description: Whether there are more voices to fetch.
        next_page:
          $ref: '#/components/schemas/VoiceId'
          nullable: true
          description: >-
            An ID that can be passed as `starting_after` or `ending_before` to
            get the next page of voices.
      required:
        - data
        - has_more
    Voice:
      title: Voice
      type: object
      properties:
        id:
          $ref: '#/components/schemas/VoiceId'
        is_owner:
          type: boolean
          description: Whether your organization owns the voice.
        name:
          type: string
          description: The name of the voice.
        description:
          type: string
          description: The description of the voice.
        created_at:
          type: string
          format: date-time
          description: The date and time the voice was created.
        embedding:
          $ref: '#/components/schemas/Embedding'
          nullable: true
          description: The vector embedding of the voice.
        language:
          $ref: '#/components/schemas/VoiceLanguage'
        country:
          $ref: '#/components/schemas/VoiceCountry'
          nullable: true
        preview_file_url:
          type: string
          nullable: true
          description: >-
            A URL to download a preview audio file of this voice. Useful to
            avoid consuming credits to sample the voice. The URL requires the
            same Authorization header. Voice previews may be changed, moved, or
            deleted so you should avoid storing the URL permanently. This
            property will be null if there's no preview available. Only included
            when `expand[]` includes `preview_file_url`.
      required:
        - id
        - is_owner
        - name
        - description
        - created_at
        - language
    VoiceId:
      title: VoiceId
      type: string
      description: The ID of the voice.
    Embedding:
      title: Embedding
      type: array
      items:
        type: number
        format: double
      description: >-
        A 192-dimensional vector (i.e. a list of 192 numbers) that represents
        the voice.
    VoiceLanguage:
      type: string
      description: The voice's language, as an ISO 639-1 code (e.g. `en`, `fr`, `zh`)
      example: en
    VoiceCountry:
      title: VoiceCountry
      type: string
      description: >-
        The country associated with the voice, as an ISO 3166-1 alpha-2 code
        when available (e.g. `US`, `GB`, `FR`).
      example: US
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````