Get Voice Facets

{
  "data": {
    "providers": [
      {
        "value": "elevenlabs",
        "count": 24,
        "label": "Eleven Labs"
      },
      {
        "value": "rime",
        "count": 15,
        "label": "Rime AI"
      },
      {
        "value": "voicery",
        "count": 8,
        "label": "Voicery"
      }
    ],
    "models": [
      {
        "value": "arcana",
        "count": 18,
        "label": "Arcana"
      },
      {
        "value": "sonic-2",
        "count": 12,
        "label": "Sonic 2"
      },
      {
        "value": "vocalize",
        "count": 9,
        "label": "Vocalize"
      }
    ],
    "languages": [
      {
        "value": "en-us",
        "count": 30,
        "label": null
      },
      {
        "value": "ko-kr",
        "count": 10,
        "label": null
      },
      {
        "value": "fr-fr",
        "count": 7,
        "label": null
      }
    ],
    "genders": [
      {
        "value": "male",
        "count": 20,
        "label": null
      },
      {
        "value": "female",
        "count": 25,
        "label": null
      },
      {
        "value": "neutral",
        "count": 5,
        "label": null
      }
    ],
    "ages": [
      {
        "value": "young",
        "count": 15,
        "label": null
      },
      {
        "value": "middle_aged",
        "count": 25,
        "label": null
      },
      {
        "value": "old",
        "count": 10,
        "label": null
      }
    ],
    "categories": [
      {
        "value": "news",
        "count": 12,
        "label": null
      },
      {
        "value": "narration",
        "count": 18,
        "label": null
      },
      {
        "value": "story",
        "count": 10,
        "label": null
      },
      {
        "value": "podcast",
        "count": 8,
        "label": null
      },
      {
        "value": "conversational",
        "count": 20,
        "label": null
      },
      {
        "value": "social_media",
        "count": 5,
        "label": null
      },
      {
        "value": "educational",
        "count": 15,
        "label": null
      },
      {
        "value": "business",
        "count": 7,
        "label": null
      }
    ],
    "accents": [
      {
        "value": "american",
        "count": 22,
        "label": null
      },
      {
        "value": "british",
        "count": 18,
        "label": null
      },
      {
        "value": "australian",
        "count": 5,
        "label": null
      },
      {
        "value": "indian",
        "count": 7,
        "label": null
      },
      {
        "value": "canadian",
        "count": 3,
        "label": null
      },
      {
        "value": "irish",
        "count": 1,
        "label": null
      },
      {
        "value": "african",
        "count": 0,
        "label": null
      },
      {
        "value": "european",
        "count": 4,
        "label": null
      },
      {
        "value": "east_asian",
        "count": 6,
        "label": null
      },
      {
        "value": "southeast_asian",
        "count": 2,
        "label": null
      },
      {
        "value": "latin_american",
        "count": 3,
        "label": null
      },
      {
        "value": "middle_eastern",
        "count": 0,
        "label": null
      },
      {
        "value": "slavic",
        "count": 1,
        "label": null
      },
      {
        "value": "spanish",
        "count": 5,
        "label": null
      },
      {
        "value": "french",
        "count": 7,
        "label": null
      },
      {
        "value": "german",
        "count": 4,
        "label": null
      },
      {
        "value": "italian",
        "count": 3,
        "label": null
      },
      {
        "value": "portuguese",
        "count": 2,
        "label": null
      },
      {
        "value": "japanese",
        "count": 6,
        "label": null
      },
      {
        "value": "korean",
        "count": 8,
        "label": null
      },
      {
        "value": "chinese",
        "count": 7,
        "label": null
      },
      {
        "value": "thai",
        "count": 1,
        "label": null
      },
      {
        "value": "vietnamese",
        "count": 1,
        "label": null
      },
      {
        "value": "other",
        "count": 0,
        "label": null
      }
    ]
  },
  "meta": {
    "request_id": "a1b2c3d4-e5f6-7890-abcd-1234567890ef",
    "timestamp": "2024-01-15T09:30:00Z"
  }
}

Filter-bar options (chips) for the voice browser, one list per dimension.

Returns providers, models, languages (data-driven) plus genders, ages, categories, accents (fixed enums) as VoiceFacetItem[] so the FE builds the whole filter bar — with per-chip count badges — in a single request instead of hardcoding option lists (mirrors GET /dictionary/languages). Each item is {value, label, count}: value is passed straight back to GET /voices; label is the display name for providers/models and null elsewhere (the FE owns language + enum labels); count is the number of matching voices. A language surfaces as one chip keyed by its canonical allowlist locale: every declared locale is folded onto the locale the GET /voices filter would match it against (bare ko and regioned ko-kr both count under ko-kr), so variants never split into duplicate chips for the identical filter. Model counts include only voices that explicitly declare the model. Language counts include voices that declare the exact regional locale plus voices that declare its bare family (en contributes to every supported en-* locale). A voice with no declared supported_models is “general use” — GET /voices matches it against every model filter but no models chip counts it, so a model chip’s count can be lower than the GET /voices?model= result. Languages have no such gap: no-locale voices are excluded from both the language chips and GET /voices?language=, so language chip counts match the row counts.

Accepts the SAME filters as GET /voices (tab scope source/favorites_only, plus provider/model/language/gender/age/category/accent/search). count is context-aware (faceted search): each dimension’s counts apply every OTHER active filter but exclude that dimension’s own selection — e.g. with provider=elevenlabs the language counts are scoped to ElevenLabs, while the provider chips still show every provider so the caller can switch.

Count-0 policy: data-driven dimensions omit count-0 values (only present ones, each a valid GET /voices filter — providers/models restricted to the enabled catalog, languages to the supported-locale allowlist, so a chip never 422s). Enum dimensions always return the full enum in natural order, count-0 included, for the FE to grey out.

Filter-bar options (chips) for the voice browser, one list per dimension. Returns `providers`, `models`, `languages` (data-driven) plus `genders`, `ages`, `categories`, `accents` (fixed enums) as `VoiceFacetItem[]` so the FE builds the whole filter bar — with per-chip count badges — in a single request instead of hardcoding option lists (mirrors `GET /dictionary/languages`). Each item is `{value, label, count}`: `value` is passed straight back to `GET /voices`; `label` is the display name for providers/models and `null` elsewhere (the FE owns language + enum labels); `count` is the number of matching voices. A language surfaces as one chip keyed by its canonical allowlist locale: every declared locale is folded onto the locale the `GET /voices` filter would match it against (bare `ko` and regioned `ko-kr` both count under `ko-kr`), so variants never split into duplicate chips for the identical filter. Model counts include only voices that explicitly declare the model. Language counts include voices that declare the exact regional locale plus voices that declare its bare family (`en` contributes to every supported `en-*` locale). A voice with no declared `supported_models` is "general use" — `GET /voices` matches it against every model filter but no `models` chip counts it, so a model chip's count can be lower than the `GET /voices?model=` result. Languages have no such gap: no-locale voices are excluded from both the language chips and `GET /voices?language=`, so language chip counts match the row counts. Accepts the SAME filters as `GET /voices` (tab scope `source`/`favorites_only`, plus `provider`/`model`/`language`/`gender`/`age`/`category`/`accent`/`search`). `count` is context-aware (faceted search): each dimension's counts apply every OTHER active filter but exclude that dimension's own selection — e.g. with `provider=elevenlabs` the language counts are scoped to ElevenLabs, while the provider chips still show every provider so the caller can switch. Count-0 policy: data-driven dimensions omit count-0 values (only present ones, each a valid `GET /voices` filter — providers/models restricted to the enabled catalog, languages to the supported-locale allowlist, so a chip never 422s). Enum dimensions always return the full enum in natural order, count-0 included, for the FE to grey out.

Authentication

AuthorizationBearer

Clerk JWT token

Query parameters

favorites_onlybooleanOptionalDefaults to false

Favorites tab scope

sourcelist of enums or nullOptional

Tab scope — repeat for OR, same values as GET /voices (e.g. platform, workspace)

Allowed values:

genderlist of enums or nullOptional

Repeat for OR

Allowed values:

agelist of enums or nullOptional

Repeat for OR

Allowed values:

categorylist of enums or nullOptional

Repeat for OR

accentlist of enums or nullOptional

Repeat for OR

searchstring or nullOptional<=200 characters

providerlist of strings or nullOptional

Repeat for OR, e.g. ?provider=elevenlabs&provider=rime

modellist of strings or nullOptional

Repeat for OR. Filters platform voices by TTS model, e.g. ?model=arcana&model=sonic-2

languagelist of strings or nullOptional

Repeat for OR, e.g. ?language=en-us&language=ko-kr

Response

Successful Response

dataobject

Filter options for the voice browser, one VoiceFacetItem[] per chip.

Two families of dimension:

Data-driven — providers, models, languages: only values with a scoped voice count are returned (count is always ≥ 1; count-0 values are omitted). A language value may be derived from a bare family tag on a scoped voice. Every value is guaranteed to be a valid GET /voices filter (provider/model restricted to the enabled catalog, language to the supported-locale allowlist), so selecting one never yields a 422 or empty page. Sorted count DESC, then value ASC.
Enum — genders, ages, categories, accents: the FULL fixed enum is always returned in natural enum order, including count-0 values (the FE greys those out). label is None (the FE owns enum labels).

count is context-aware (faceted search): each dimension’s counts apply every OTHER active filter but exclude that dimension’s own selection, so a chip’s number reflects “results if I also pick this” without the dimension suppressing its own alternatives.

metaobject

Errors

422

Unprocessable Entity Error

Filter-bar options (chips) for the voice browser, one list per dimension.

$	curl https://api.onepin.ai/api/v1/voices/facets \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json"

Authentication

Headers

Query parameters

Response

Errors