Get Similar Voices

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Emma Voice",
      "provider": "google",
      "provider_voice_id": "en-US-Wavenet-F",
      "is_active": true,
      "created_at": "2023-11-20T14:22:00Z",
      "updated_at": "2024-04-10T10:15:00Z",
      "similarity_score": 0.92,
      "description": "Warm and clear female voice suitable for news reading.",
      "gender": "female",
      "accent": "american",
      "age": "middle_aged",
      "category": "news",
      "color": "#4A90E2",
      "tags": [
        "news",
        "clear",
        "professional"
      ],
      "descriptor": "Warm and professional news anchor voice",
      "uses_count": 1245,
      "user_id": null,
      "source": "platform",
      "duration_seconds": 12.5,
      "sample_url": "https://samples.onepin.ai/audio/3fa85f64-5717-4562-b3fc-2c963f66afa6/sample.mp3?expires=1687000000",
      "supported_languages": [
        "en-US",
        "en-GB"
      ],
      "supported_models": [
        "standard",
        "neural"
      ],
      "is_favorite": true
    },
    {
      "id": "7b9e1f2a-8c3d-4f1a-9a2b-1d2e3f4a5b6c",
      "name": "John Narrator",
      "provider": "aws",
      "provider_voice_id": "Matthew",
      "is_active": true,
      "created_at": "2023-10-05T08:00:00Z",
      "updated_at": "2024-03-25T12:00:00Z",
      "similarity_score": 0.87,
      "description": "Deep male voice ideal for storytelling and narration.",
      "gender": "male",
      "accent": "british",
      "age": "middle_aged",
      "category": "narration",
      "color": "#D94F4F",
      "tags": [
        "narration",
        "deep",
        "storytelling"
      ],
      "descriptor": "Deep British male voice for narration",
      "uses_count": 987,
      "user_id": null,
      "source": "platform",
      "duration_seconds": 15,
      "sample_url": "https://samples.onepin.ai/audio/7b9e1f2a-8c3d-4f1a-9a2b-1d2e3f4a5b6c/sample.mp3?expires=1687000000",
      "supported_languages": [
        "en-GB"
      ],
      "supported_models": [
        "neural"
      ],
      "is_favorite": false
    }
  ],
  "meta": {
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "timestamp": "2024-04-27T15:45:00Z"
  },
  "pagination": {
    "limit": 2,
    "next": "https://api.onepin.ai/api/v1/voices/3fa85f64-5717-4562-b3fc-2c963f66afa6/similar?limit=2&page=2",
    "prev": null
  }
}

Return voices acoustically similar to a reference voice.

Results are ranked by semantic similarity score (descending) and include the reference voice’s workspace voices and all platform voices. Each result includes a similarity_score between 0 and 1. Optionally filter by one or more language BCP-47 codes (repeat the parameter for OR semantics); up to 16 language values are accepted. Returns 503 when the reference voice has no embedding yet — retry after the indicated Retry-After interval. Prefer this endpoint over GET /voices with manual filtering when building a “voices like this” recommendation UI.

Return voices acoustically similar to a reference voice. Results are ranked by semantic similarity score (descending) and include the reference voice's workspace voices and all platform voices. Each result includes a `similarity_score` between 0 and 1. Optionally filter by one or more `language` BCP-47 codes (repeat the parameter for OR semantics); up to 16 language values are accepted. Returns 503 when the reference voice has no embedding yet — retry after the indicated `Retry-After` interval. Prefer this endpoint over `GET /voices` with manual filtering when building a "voices like this" recommendation UI.

Authentication

AuthorizationBearer

Clerk JWT token

Path parameters

voice_idstringRequiredformat: "uuid"

Query parameters

limitintegerOptional1-50Defaults to 10

Number of similar voices to return (1–50).

languagelist of strings or nullOptional

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

Response

Successful Response

datalist of objects

metaobject

paginationobject

Errors

422

Unprocessable Entity Error

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

Authentication

Path parameters

Headers

Query parameters

Response

Errors