Skip to content
Lumean API
GET/voices/public

Public Voices Catalog

The shared LumVoice catalogue available to everyone: only published (public), ready (ready) and order-enabled voices appear here.

voices.read

Spec fixes · 1

  • Pagination does not live in data.meta

    Four per_page descriptions promise pagination metadata in data.meta. No public API response contains that key: a page arrives flat — data.items[] plus data.current_page, data.last_page, data.per_page, data.total. Code reading data.meta.total gets undefined.

This is where you find a voice that is not yet in your library. Filters: tags (tag_ids[], listed by GET /voices/tags), language, gender and a search string.

Required key permission: voices.read.

On this page(3)

Parameters

The inputs live inside the request line: fill in a value and you get a ready URL. Below are the type, whether it is required and the allowed values of every parameter.

GEThttps://api.lumean.app/api/public/voices/public
  • array<integer>in queryoptional

    Tag filter, repeatable: ?tag_ids[]=3&tag_ids[]=7. Tags are listed by GET /voices/tags.

  • stringin queryoptional

    Language filter, ISO-639-1 (ru, en, de, …).

  • stringin queryoptional

    Voice gender.

    Allowed values
  • stringin queryoptional

    Substring to search for. Case-insensitive.

  • stringin queryoptional

    Catalogue ordering. Defaults to popular.

    Allowed values
  • integerin queryoptional

    How many records to return per page. Pagination metadata sits next to items: current_page, last_page, per_page, total.

Possible responses

200

Success. The payload is in data.

Body example
{
  "success": true,
  "message": "Success",
  "data": {
    "items": [
      {
        "id": "k3nH9vRt2Lw7ZpXb",
        "display_name": "Ava Narrator (EN)",
        "description": "Warm, measured narration voice cloned from a 45-second studio reference — ideal for long-form audiobook and e-learning narration.",
        "gender": "female",
        "accent": "us",
        "default_language_code": "en",
        "voice_status": "ready",
        "publication_status": "public",
        "allow_usage_in_orders": true,
        "preview_generated_at": "2026-06-02T09:15:00+00:00",
        "created_at": "2026-06-01T10:00:00+00:00",
        "updated_at": "2026-06-02T09:15:00+00:00",
        "tags": [
          {
            "id": 8,
            "code": "narration",
            "name": "Narration",
            "description": null,
            "color": null,
            "sort_order": 80
          },
          {
            "id": 4,
            "code": "calm",
            "name": "Calm",
            "description": null,
            "color": null,
            "sort_order": 40
          }
        ],
        "languages": [
          {
            "id": 1,
            "language_code": "en",
            "status": "ready",
            "reference_duration_ms": 47000,
            "model_version": 1,
            "failure_reason": null,
            "clone_started_at": "2026-06-01T10:05:00+00:00",
            "clone_completed_at": "2026-06-01T10:22:00+00:00",
            "updated_at": "2026-06-01T10:22:00+00:00"
          }
        ],
        "preview_urls": {
          "en": "https://s3.lumean.app/lumean/storage/lumvoice/voices/k3nH9vRt2Lw7ZpXb/previews/en.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAEXAMPLE1234567%2F20260602%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260602T091500Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=3f9c2b0a1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a"
        }
      },
      {
        "id": "Yt5Fq2Wm8XbNc4Rp",
        "display_name": "Sofia Podcast Host (RU)",
        "description": "Energetic bilingual host voice, cloned for podcast intros and interview segments.",
        "gender": "female",
        "accent": null,
        "default_language_code": "ru",
        "voice_status": "ready",
        "publication_status": "public",
        "allow_usage_in_orders": true,
        "preview_generated_at": "2026-06-20T13:40:00+00:00",
        "created_at": "2026-06-18T08:00:00+00:00",
        "updated_at": "2026-06-20T13:40:00+00:00",
        "tags": [
          {
            "id": 5,
            "code": "energetic",
            "name": "Energetic",
            "description": null,
            "color": null,
            "sort_order": 50
          },
          {
            "id": 2,
            "code": "female",
            "name": "Female",
            "description": null,
            "color": null,
            "sort_order": 20
          }
        ],
        "languages": [
          {
            "id": 4,
            "language_code": "ru",
            "status": "ready",
            "reference_duration_ms": 58000,
            "model_version": 1,
            "failure_reason": null,
            "clone_started_at": "2026-06-18T08:05:00+00:00",
            "clone_completed_at": "2026-06-18T08:30:00+00:00",
            "updated_at": "2026-06-18T08:30:00+00:00"
          }
        ],
        "preview_urls": {
          "ru": "https://s3.lumean.app/lumean/storage/lumvoice/voices/Yt5Fq2Wm8XbNc4Rp/previews/ru.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAEXAMPLE1234567%2F20260620%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260620T134000Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c"
        }
      }
    ],
    "current_page": 1,
    "last_page": 1,
    "per_page": 20,
    "total": 2
  }
}
Response fields
successrequired

Success flag. Branch on the HTTP status code instead: any 2xx response carries true here, while an error comes back in a different shape that need not contain this field at all.

boolean
messagerequired

A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code.

string
datarequired

The shared catalogue of published voices. You do not need to add a voice to your library to use it in orders.

PublicVoiceListPublicVoiceList
itemsrequired

Records on the current page, in the list’s sort order.

array<LumVoice>LumVoice
array item
idrequired

Voice UUID. Put it into a template’s config.voice_id; the same value goes into /voices/{voice} paths.

string
display_namerequired

Display name of the voice.

string
descriptionrequired

Author’s description of the voice: timbre, delivery, intended use.

string
genderrequired

Voice gender.

string
accentrequired

Accent or regional pronunciation variant.

string
default_language_coderequired

The language the voice defaults to, ISO-639-1.

string
voice_statusrequired

Cloning state of the voice. Only a fully prepared voice can be used in orders.

string
publication_statusrequired

Publication stage: draft, under review, published. It determines whether the voice appears in the shared catalogue GET /voices/public.

string
allow_usage_in_ordersrequired

Whether the author lets others use the voice. Without this flag the voice is absent from the GET /voices/public catalogue, and library entries other users already made for it become unavailable.

boolean
preview_generated_atrequired

When the preview clips were produced, ISO 8601. null means there is no preview yet.

nullabledate-time
string
created_atrequired

When the voice was created, ISO 8601.

nullabledate-time
string
updated_atrequired

When the voice last changed, ISO 8601.

nullabledate-time
string
tagsoptional

Voice tags for search and filtering. The full directory is GET /voices/tags.

array<VoiceTag>VoiceTag
array item
idrequired

Internal identifier of the tag.

integer
coderequired

Tag code — the stable value to filter by, unlike the translatable name.

string
namerequired

Tag name in the account language.

string
descriptionrequired

Explanation of the tag in the account language, when the author provided one.

nullable
string
colorrequired

Tag colour in HEX — a styling hint.

string
sort_orderrequired

Sort weight within the tag list: lower comes first.

integer
languagesoptional

Languages the voice has been cloned into, each with its own state. An order is only possible in a language that is ready.

array<VoiceLanguage>VoiceLanguage
array item
idrequired

Internal identifier of the voice’s language version.

integer
language_coderequired

Language code, ISO-639-1. It is also the key used in preview_urls.

string
statusrequired

Cloning state for this language. Orders are accepted only in a language whose clone is ready.

string
reference_duration_msrequired

Duration of the reference recording in milliseconds — the clone was trained on it.

nullable
integer
model_versionrequired

Version of the trained model. It increments whenever the voice is retrained.

integer
failure_reasonrequired

Why cloning failed. null when there was no failure.

nullable
string
clone_started_atrequired

When cloning started, ISO 8601.

nullabledate-time
string
clone_completed_atrequired

When cloning finished, ISO 8601. null means it is still running or it failed.

nullabledate-time
string
updated_atrequired

When the language version last changed, ISO 8601.

nullabledate-time
string
preview_urlsrequired

Preview clips by language: the key is a language code, the value a temporary audio link or null when there is no preview for that language. The links live for about a minute.

object
*optional
nullablearbitrary keys
string
current_pagerequired

Current page number, starting from one.

integer
last_pagerequired

Number of the last page. The walk is over once current_page equals last_page.

integer
per_pagerequired

Page size the server applied.

integer
totalrequired

Total number of records matching the filter.

integer
401

The key is missing, unknown, disabled or expired.

Analyse this response
Body example
{
  "success": false,
  "message": "API key is missing. Provide it in the X-API-KEY header.",
  "data": null
}
Response fields
successrequired

Always false in error responses.

boolean
messagerequired

Error text in the key's language (set through the X-Locale header).

string
datarequired

Always null when the request is rejected before processing.

nullable
null
403

The key lacks the required permission, or the object belongs to another user.

Analyse this response
Body example
{
  "success": false,
  "message": "This API key does not have permission to perform this action."
}
Response fields
messagerequired

Error overview.

string
422

Validation error. Offending fields are listed in errors.

Analyse this response
Body example
{
  "message": "string",
  "errors": {}
}
Response fields
messagerequired

Errors overview.

string
errorsrequired

A detailed description of each field that failed validation.

object
*optional
arbitrary keys
array<string>

Nearby

The same in words

Neighbouring operations

Feed this page to an AI

Open .mdllm.md

spec 0.0.1