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

# List voices (unified)

> Search and list voices across one or more TTS providers in a single normalized shape. Filter by language, gender, accent and providers[].

The unified endpoint is the easiest way to find a voice. It fans out to every requested provider in parallel, normalizes the result, then applies your filters.

## Examples

### Only English female voices across all providers

```bash theme={null}
curl "https://eu-gcp-api.vg-stuff.com/v3/voices?language=en&gender=female&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### German voices from ElevenLabs and Cartesia only

```bash theme={null}
curl "https://eu-gcp-api.vg-stuff.com/v3/voices?providers=elevenlabs,cartesia&language=de" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Australian-accent voices

```bash theme={null}
curl "https://eu-gcp-api.vg-stuff.com/v3/voices?accent=australian&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## How filters work

* **`language`** — accepts ISO short codes (`en`), BCP-47 (`en-US`) or English names (`English`). Matches are inclusive: filter `en` returns `en`, `en-US`, `en-GB`, `English`, etc.
* **`gender`** — `male` / `female` / `neutral`. Also accepts `masculine`, `feminine`, `m`, `f` (case-insensitive).
* **`accent`** — substring match (case-insensitive). `american` matches `American`, `North American`, etc.
* **`providers`** — comma-separated list (`?providers=elevenlabs,cartesia`). When omitted, every supported provider is queried in parallel.

## Response

The response always contains:

* `voices[]` — the paginated, filtered list (each entry has `voiceId`, `name`, `provider`, `previewUrl`, `filters`)
* `total` — total matches before pagination
* `providersQueried` — providers that were actually queried
* `providersFailed` — providers that errored (e.g. missing workspace API key) along with the error message — **the request still succeeds**

<Tip>
  Each voice has a ready-to-play `previewUrl` MP3. Drop it straight into an `<audio>` element.
</Tip>

<Note>
  This endpoint is read-only and does **not** consume credits.
</Note>


## OpenAPI

````yaml GET /voices
openapi: 3.0.3
info:
  title: Convocore OpenAPI
  description: Full API reference for Convocore
  version: 1.0.4
servers:
  - url: https://eu-gcp-api.vg-stuff.com/v3
    description: EU Node.js API server
  - url: https://na-gcp-api.vg-stuff.com/v3
    description: NA Node.js API server
security: []
paths:
  /voices:
    get:
      tags:
        - Voices
      summary: List voices across all providers (unified)
      description: >-
        Returns voices across one or more providers in a single normalized
        shape. Filter by `providers[]`, `language`, `gender`, `accent` and
        paginate with `limit` & `offset`. If no `providers` are specified,
        queries every supported provider in parallel and skips providers that
        fail (e.g. missing workspace key).
      operationId: v2Audio-listVoices
      parameters:
        - name: providers
          in: query
          required: false
          schema:
            type: string
        - name: language
          in: query
          required: false
          schema:
            type: string
        - name: gender
          in: query
          required: false
          schema:
            type: string
        - name: accent
          in: query
          required: false
          schema:
            type: string
        - name: modelId
          in: query
          required: false
          schema:
            type: string
        - name: sampleText
          in: query
          required: false
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            anyOf:
              - not: {}
              - type: integer
                minimum: 1
                maximum: 500
            default: 100
        - name: offset
          in: query
          required: false
          schema:
            anyOf:
              - not: {}
              - type: integer
                minimum: 0
            default: 0
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: number
                  limit:
                    type: number
                  offset:
                    type: number
                  providersQueried:
                    type: array
                    items:
                      type: string
                  providersFailed:
                    type: array
                    items:
                      type: object
                      properties:
                        provider:
                          type: string
                        error:
                          type: string
                      required:
                        - provider
                        - error
                      additionalProperties: false
                  voices:
                    type: array
                    items:
                      type: object
                      properties:
                        voiceId:
                          type: string
                        name:
                          type: string
                        provider:
                          type: string
                        previewUrl:
                          type: string
                        filters:
                          type: object
                          properties:
                            accent:
                              type: string
                            gender:
                              type: string
                            useCase:
                              type: string
                            language:
                              type: string
                          required:
                            - accent
                            - gender
                            - useCase
                            - language
                          additionalProperties: false
                      required:
                        - voiceId
                        - name
                        - provider
                        - previewUrl
                        - filters
                      additionalProperties: false
                required:
                  - total
                  - limit
                  - offset
                  - providersQueried
                  - providersFailed
                  - voices
                additionalProperties: false
        default:
          $ref: '#/components/responses/error'
      security:
        - Authorization: []
components:
  responses:
    error:
      description: Error response
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
              code:
                type: string
              issues:
                type: array
                items:
                  type: object
                  properties:
                    message:
                      type: string
                  required:
                    - message
                  additionalProperties: false
            required:
              - message
              - code
            additionalProperties: false
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer

````