Skip to content
Lumean API
GET/voices/{voice}

Show Voice

One voice card: language, gender, tags, status and preview.

voices.read

A voice is visible if it is yours, published in the shared catalogue, or added to your library. Someone else's private voice returns 403.

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/
  • stringin pathrequired

    Voice UUID — 36 characters, not a number.

    Take it from the id field in GET /voices (your own voices) or GET /voices/public (the shared catalogue). This is not an external provider’s voice_id: ElevenLabs and HeyGen use identifiers of their own format, and those will not work here.

    The value goes straight into the request line above.

Possible responses

200

Success. The payload is in data.

Body example
{
  "success": true,
  "message": "Success",
  "data": {
    "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"
    }
  }
}
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 full voice: tags, language versions and preview links.

LumVoiceLumVoice
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
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
404

Not found, or not reachable with this key.

Analyse this response
Body example
{
  "success": false,
  "message": "Resource not found."
}
Response fields
successrequired

Always false in error responses.

boolean
messagerequired

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

string
reasonoptional

Machine-readable reason — present on business refusals (for example, invalid_order_status); other errors omit it. Branch on it, not on the message text.

string
error_codeoptional

The same machine-readable code as in reason — a second name for the field. Arrives together with reason; the values always match.

string

Nearby

The same in words

Neighbouring operations

Feed this page to an AI

Open .mdllm.md

spec 0.0.1