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

# List voices

> List the voices available for text-to-speech. Use a voice's `id` as `style.voice_name` in the AI Voice Generator API. To fetch the next page, pass the response's next_cursor as cursor.



## OpenAPI

````yaml get /v1/voices
openapi: 3.0.2
info:
  title: Magic Hour API
  version: beta
  description: >

    Magic Hour provides a REST API (beta) for generating and editing video,
    images, and audio using AI.


    Webhook documentation can be found
    [here](https://docs.magichour.ai/webhook-reference).


    If you have any questions, please reach out to us via
    [discord](https://discord.gg/JX5rgsZaJp).


    # Authentication


    Every request requires an API key.


    To get started, first generate your API key
    [here](https://magichour.ai/developer?tab=api-keys&utm_source=docs&utm_medium=referral&utm_campaign=api-reference).


    Then, add the `Authorization` header to the request.


    | Key | Value |

    |-|-|

    | Authorization | Bearer mhk_live_apikey |


    > **Warning**: API generation and editing requests consume account credits.
    Cost varies by tool, model, and settings; see [API
    pricing](https://magichour.ai/api#api-cost-calculator).
  termsOfService: https://magichour.ai/terms-of-service
servers:
  - url: https://api.magichour.ai
security: []
tags:
  - name: Video Projects
    description: API related to video projects
  - name: Image Projects
    description: API related to image projects
  - name: Audio Projects
    description: API related to audio projects
  - name: Files
    description: API related to uploading and reusing assets
  - name: Account
    description: API related to the account that owns the API key
paths:
  /v1/voices:
    get:
      tags:
        - Audio Projects
      summary: List voices
      description: >-
        List the voices available for text-to-speech. Use a voice's `id` as
        `style.voice_name` in the AI Voice Generator API. To fetch the next
        page, pass the response's next_cursor as cursor.
      operationId: voices.list
      parameters:
        - name: limit
          in: query
          description: Maximum number of voices to return. Defaults to 20.
          schema:
            default: 20
            type: integer
            minimum: 1
            maximum: 100
            example: 20
        - name: cursor
          in: query
          description: Opaque pagination cursor from the previous response's next_cursor.
          schema:
            type: string
            minLength: 1
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  voices:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: cv-0001
                          description: >-
                            Unique ID of the voice. Pass it as
                            `style.voice_name` when generating speech. Names are
                            not unique, so use the ID.
                        name:
                          type: string
                          example: Ashley
                          description: Display name of the voice.
                        avatar_url:
                          type: string
                          nullable: true
                          example: >-
                            https://d28dkohlqf5vwj.cloudfront.net/models/nano-banana/female-portrait-turtleneck.webp
                          description: >-
                            URL of the voice's avatar image, or null when the
                            voice has no avatar.
                        preview_url:
                          type: string
                          example: >-
                            https://videos.magichour.ai/presets/voices/v2/cv-0001-ashley.mp3
                          description: URL of an audio sample of the voice.
                      required:
                        - id
                        - name
                        - avatar_url
                        - preview_url
                  next_cursor:
                    type: string
                    nullable: true
                    description: >-
                      Cursor for the next page, or null when there are no more
                      voices.
                required:
                  - voices
                  - next_cursor
        '400':
          description: Invalid Request
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - message
                properties:
                  code:
                    type: string
                    enum:
                      - invalid_request
                    description: >-
                      Machine-readable error code.


                      - `invalid_request`: Fix request syntax or validation
                      errors before retrying.
                  message:
                    type: string
                    description: Human-readable error message.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - message
                properties:
                  code:
                    type: string
                    enum:
                      - unauthorized
                    description: |-
                      Machine-readable error code.

                      - `unauthorized`: Provide a valid API key before retrying.
                  message:
                    type: string
                    description: Human-readable error message.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - message
                properties:
                  code:
                    type: string
                    enum:
                      - internal_server_error
                    description: >-
                      Machine-readable error code.


                      - `internal_server_error`: Retry later or contact support
                      if the error continues.
                  message:
                    type: string
                    description: Human-readable error message.
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer authentication header of the form `Bearer <api_key>`, where
        `<api_key>` is your API key. To get your API key, go to [Developer
        Hub](https://magichour.ai/developer?tab=api-keys&utm_source=docs&utm_medium=referral&utm_campaign=api-reference)
        and click "Create new API Key".

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.