For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
  • Get Started
    • Introduction
    • Quickstart
    • Authentication
  • API Reference
      • GETList Voices
      • GETGet Voice
      • GETGet Similar Voices
      • POSTFavorite Voice
      • DELUnfavorite Voice
  • Python SDK
    • Install
    • Usage
    • Errors
  • CLI
    • Overview
LogoLogo
API Referencevoices

List Voices

GET
/api/v1/voices
GET
/api/v1/voices
$curl https://api.onepin.ai/api/v1/voices \
>     -H "Authorization: Bearer <token>" \
>     -H "Content-Type: application/json"
1{
2  "data": [
3    {
4      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
5      "name": "Emma",
6      "provider": "elevenlabs",
7      "provider_voice_id": "elevenlabs-emma-v1",
8      "is_active": true,
9      "created_at": "2023-11-20T14:45:00Z",
10      "updated_at": "2024-04-10T08:15:00Z",
11      "description": "Clear and natural female voice suitable for news reading.",
12      "gender": "female",
13      "accent": "american",
14      "age": "middle_aged",
15      "category": "news",
16      "color": "#4A90E2",
17      "tags": [
18        "news",
19        "clear",
20        "professional"
21      ],
22      "descriptor": "Warm, professional tone with moderate pace",
23      "uses_count": 1523,
24      "user_id": null,
25      "source": "platform",
26      "duration_seconds": 12.5,
27      "sample_url": "https://samples.onepin.ai/voices/elevenlabs-emma-v1/sample.mp3",
28      "supported_languages": [
29        "en-us",
30        "en-gb"
31      ],
32      "is_favorite": true
33    }
34  ],
35  "meta": {
36    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
37    "timestamp": "2024-06-01T12:00:00Z"
38  },
39  "pagination": {
40    "limit": 20,
41    "total": 134,
42    "next": "eyJvZmZzZXQiOjIwLCJsaW1pdCI6MjB9",
43    "prev": null
44  }
45}
List TTS voices available to the current workspace. Every filter accepts repeat-key OR semantics: `?gender=female&gender=neutral&category=narration&source=platform&source=workspace`. Filters combine across fields with AND; within a field, values OR. `language` uses Postgres `?|` (exists-any) against `voices.supported_languages`. Platform voices with NULL `supported_languages` (catalog gaps) are treated as general-use and match every locale filter. User-uploaded / cloned voices with NULL stay excluded — NULL there means "language unknown" pending the clone flow's language detection. Multi-sort: `sort` and `order` are parallel lists. `?sort=uses_count&sort=name&order=desc&order=asc` orders primarily by uses_count DESC, secondarily by name ASC. When `order` is shorter than `sort`, missing entries default per-field: `name=asc, created_at=desc, uses_count=desc`. When `sort` is omitted, list defaults to newest-first (or most-recently-favorited-first if `favorites_only=true`). Every sort path appends `Voice.id ASC` as a deterministic tiebreaker for pagination stability.
Was this page helpful?
Previous

Get Voice

Next
Built with

List TTS voices available to the current workspace.

Every filter accepts repeat-key OR semantics: ?gender=female&gender=neutral&category=narration&source=platform&source=workspace. Filters combine across fields with AND; within a field, values OR.

language uses Postgres ?| (exists-any) against voices.supported_languages. Platform voices with NULL supported_languages (catalog gaps) are treated as general-use and match every locale filter. User-uploaded / cloned voices with NULL stay excluded — NULL there means “language unknown” pending the clone flow’s language detection.

Multi-sort: sort and order are parallel lists. ?sort=uses_count&sort=name&order=desc&order=asc orders primarily by uses_count DESC, secondarily by name ASC. When order is shorter than sort, missing entries default per-field: name=asc, created_at=desc, uses_count=desc. When sort is omitted, list defaults to newest-first (or most-recently-favorited-first if favorites_only=true). Every sort path appends Voice.id ASC as a deterministic tiebreaker for pagination stability.

Authentication

AuthorizationBearer
Clerk JWT token
OR
AuthorizationBearer

Onepin live API key (op_live_...). Test and public keys are reserved in Phase 1.

Headers

X-Workspace-Idstring or nullOptional

Query parameters

offsetintegerOptional>=0Defaults to 0
limitintegerOptional1-100Defaults to 20
favorites_onlybooleanOptionalDefaults to false
sourcelist of enums or nullOptional
Repeat for OR across scopes
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
sortlist of enums or nullOptional

Repeat for multi-sort. Pairs with order index-wise.

Allowed values:
orderlist of enums or nullOptional

Parallel to sort[]; shorter is padded with per-field defaults.

Allowed values:
providerlist of enums or nullOptional

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

Allowed values:
languagelist of enums or nullOptional

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

Response

Successful Response
datalist of objects
metaobject
paginationobject
PaginationMeta variant for endpoints that compute an unpaginated total.

Errors

422
Unprocessable Entity Error