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

# List Voices (Paginated)

> Returns a page of voices for the specified provider. Unlike `GET /api/open/v1/voice/list`, this endpoint paginates results and does not support filtering by name or gender.

**Pagination behavior varies by provider:**
- **OpenAI (system voices):** Uses `page`, `size`, and `total`.
- **ElevenLabs, Cartesia, and similar:** Cursor-style pagination — when `hasMore` is true, pass `nextPageToken` from the previous response on the next request.

**Constraints:** `size` must be between **1** and **100** (default **20**).



## OpenAPI

````yaml GET /api/open/v1/voice/page
openapi: 3.1.0
info:
  title: NavTalk API
  description: NavTalk API for AI avatar management, file uploads, and video generation
  version: 1.0.0
servers:
  - url: https://api.navtalk.ai
    description: NavTalk Production Environment Server
  - url: https://qaapi.navtalk.ai
    description: NavTalk QA Environment Server
  - url: https://devapi.navtalk.ai
    description: NavTalk Development Environment Server
security:
  - navtalkLicenseAuth: []
paths:
  /api/open/v1/voice/page:
    get:
      tags:
        - Voice
      summary: List Voices (paginated)
      description: >-
        Returns a page of voices for the specified provider. Unlike `GET
        /api/open/v1/voice/list`, this endpoint paginates results and does not
        support filtering by name or gender.


        **Pagination behavior varies by provider:**

        - **OpenAI (system voices):** Uses `page`, `size`, and `total`.

        - **ElevenLabs, Cartesia, and similar:** Cursor-style pagination — when
        `hasMore` is true, pass `nextPageToken` from the previous response on
        the next request.


        **Constraints:** `size` must be between **1** and **100** (default
        **20**).
      operationId: listVoicesPage
      parameters:
        - name: providerId
          in: query
          description: The provider ID (obtained from `/provider/list`)
          required: true
          schema:
            type: string
            example: b92a28fb2ea737457c7f13ba554759c0
        - name: page
          in: query
          description: >-
            Page number (most relevant for providers backed by database paging).
            Default: 1.
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
            example: 1
        - name: size
          in: query
          description: 'Page size. Must be between 1 and 100. Default: 20.'
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
            example: 20
        - name: nextPageToken
          in: query
          description: >-
            Cursor for the next page (from the previous response's
            `data.nextPageToken`). Omit or use empty string for the first page.
          required: false
          schema:
            type: string
            default: ''
            example: ''
      responses:
        '200':
          description: Paginated voice list retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoicePageResponse'
              example:
                code: 200
                message: SUCCESS
                data:
                  list:
                    - voice: CwhRBWXzGAHq8TQ4Fs17
                      name: Rachel
                      description: A calm and clear female voice
                      gender: female
                      url: https://example.com/voices/rachel-preview.mp3
                  hasMore: true
                  total: 150
                  page: 1
                  size: 20
                  nextPageToken: fE16cVVmMUhiSjhVbVEwd1VzeDJw
        '400':
          description: License validation failed, invalid parameters, or provider error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NavtalkErrorResponse'
              examples:
                invalidLicense:
                  summary: Invalid license
                  value:
                    code: 400
                    message: Invalid license key
                sizeTooLarge:
                  summary: size exceeds maximum
                  value:
                    code: 400
                    message: size must not exceed 100
                sizeTooSmall:
                  summary: size below minimum
                  value:
                    code: 400
                    message: size must be at least 1
      security:
        - navtalkLicenseAuth: []
components:
  schemas:
    VoicePageResponse:
      type: object
      properties:
        code:
          type: integer
          example: 200
        message:
          type: string
          example: SUCCESS
        data:
          $ref: '#/components/schemas/VoicePageData'
    NavtalkErrorResponse:
      type: object
      properties:
        code:
          type: integer
          example: 400
        message:
          type: string
          example: Invalid license key
    VoicePageData:
      type: object
      description: >-
        Paginated payload. Meaning of fields depends on provider:
        system/OpenAI-style providers populate `page`, `size`, and `total`;
        ElevenLabs and Cartesia emphasize `nextPageToken` and `hasMore` for
        cursor paging.
      properties:
        list:
          type: array
          items:
            $ref: '#/components/schemas/OpenVoice'
          description: Voices in the current page.
        hasMore:
          type: boolean
          description: >-
            Whether more voices can be fetched (use `nextPageToken` when true
            for cursor-based providers).
        total:
          type: integer
          format: int64
          description: >-
            Total count when the backend provides it (may be 0 for pure cursor
            APIs).
        page:
          type: integer
          description: Current page number (1-based) when applicable.
        size:
          type: integer
          description: Page size used for this response.
        nextPageToken:
          type: string
          description: >-
            Pass this value as `nextPageToken` on the next request to fetch the
            following page.
    OpenVoice:
      type: object
      properties:
        voice:
          type: string
          description: Voice key, used as the `voice` field when creating an avatar.
          example: CwhRBWXzGAHq8TQ4Fs17
        name:
          type: string
          description: Display name of the voice.
          example: Rachel
        description:
          type: string
          description: Short description of the voice characteristics.
          example: A calm and clear female voice
        gender:
          type: string
          description: Gender of the voice.
          example: female
        url:
          type: string
          description: Audio preview URL for this voice.
          example: https://example.com/voices/rachel-preview.mp3
  securitySchemes:
    navtalkLicenseAuth:
      type: apiKey
      in: header
      name: license
      description: NavTalk API license key (e.g. sk_navtalk_...)

````