---
title: "GET /voices/{voice} — Show Voice"
url: https://lumean.app/en/developers/docs/api/get-voices-voice
locale: en
description: "Show Voice"
generated: 2026-10-17
operationId: voice.show
method: GET
path: "/voices/{voice}"
scopes: [voices.read]
spec_version: 0.0.1
---

# GET /voices/{voice}

**Show Voice**

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

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`.

- Required scope: `voices.read`

## Request

```bash
curl -X GET 'https://api.lumean.app/api/public/voices/{voice}' \
  -H 'Accept: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY'
```

## Parameters

| Field | In | Type | Req. | Description |
| --- | --- | --- | --- | --- |
| `voice` | path | `string` | required | 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. default: `7c0d9e8a-1b23-4a1e-9f3c-2b7d1e605a44` |

## Request body

No body.

## Responses

### 200 — Success. The payload is in `data`.

**Response fields**

| Field | Type | Req. | Description |
| --- | --- | --- | --- |
| `success` | `boolean` | required | 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. |
| `message` | `string` | required | 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. |
| `data` | `LumVoice` | required | The full voice: tags, language versions and preview links. |
| `data.id` | `string` | required | Voice UUID. Put it into a template’s `config.voice_id`; the same value goes into `/voices/{voice}` paths. |
| `data.display_name` | `string` | required | Display name of the voice. |
| `data.description` | `string` | required | Author’s description of the voice: timbre, delivery, intended use. |
| `data.gender` | `string` | required | Voice gender. |
| `data.accent` | `string` | required | Accent or regional pronunciation variant. |
| `data.default_language_code` | `string` | required | The language the voice defaults to, ISO-639-1. |
| `data.voice_status` | `string` | required | Cloning state of the voice. Only a fully prepared voice can be used in orders. |
| `data.publication_status` | `string` | required | Publication stage: draft, under review, published. It determines whether the voice appears in the shared catalogue `GET /voices/public`. |
| `data.allow_usage_in_orders` | `boolean` | required | 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. |
| `data.preview_generated_at` | `string` — date-time — nullable | required | When the preview clips were produced, ISO 8601. `null` means there is no preview yet. |
| `data.created_at` | `string` — date-time — nullable | required | When the voice was created, ISO 8601. |
| `data.updated_at` | `string` — date-time — nullable | required | When the voice last changed, ISO 8601. |
| `data.tags` | `array<VoiceTag>` | — | Voice tags for search and filtering. The full directory is `GET /voices/tags`. |
| `data.tags[].id` | `integer` | required | Internal identifier of the tag. |
| `data.tags[].code` | `string` | required | Tag code — the stable value to filter by, unlike the translatable `name`. |
| `data.tags[].name` | `string` | required | Tag name in the account language. |
| `data.tags[].description` | `string` — nullable | required | Explanation of the tag in the account language, when the author provided one. |
| `data.tags[].color` | `string` | required | Tag colour in HEX — a styling hint. |
| `data.tags[].sort_order` | `integer` | required | Sort weight within the tag list: lower comes first. |
| `data.languages` | `array<VoiceLanguage>` | — | Languages the voice has been cloned into, each with its own state. An order is only possible in a language that is ready. |
| `data.languages[].id` | `integer` | required | Internal identifier of the voice’s language version. |
| `data.languages[].language_code` | `string` | required | Language code, ISO-639-1. It is also the key used in `preview_urls`. |
| `data.languages[].status` | `string` | required | Cloning state for this language. Orders are accepted only in a language whose clone is ready. |
| `data.languages[].reference_duration_ms` | `integer` — nullable | required | Duration of the reference recording in milliseconds — the clone was trained on it. |
| `data.languages[].model_version` | `integer` | required | Version of the trained model. It increments whenever the voice is retrained. |
| `data.languages[].failure_reason` | `string` — nullable | required | Why cloning failed. `null` when there was no failure. |
| `data.languages[].clone_started_at` | `string` — date-time — nullable | required | When cloning started, ISO 8601. |
| `data.languages[].clone_completed_at` | `string` — date-time — nullable | required | When cloning finished, ISO 8601. `null` means it is still running or it failed. |
| `data.languages[].updated_at` | `string` — date-time — nullable | required | When the language version last changed, ISO 8601. |
| `data.preview_urls` | `object` | required | 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. |
| `data.preview_urls.*` | `string` — arbitrary keys — nullable | — |  |

**Example**

```json
{
  "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"
    }
  }
}
```

### 401 — The key is missing, unknown, disabled or expired.

**Response fields**

| Field | Type | Req. | Description |
| --- | --- | --- | --- |
| `success` | `boolean` | required | Always `false` in error responses. |
| `message` | `string` | required | Error text in the key's language (set through the `X-Locale` header). |
| `data` | `null` — nullable | required | Always `null` when the request is rejected before processing. |

**Example**

```json
{
  "success": false,
  "message": "API key is missing. Provide it in the X-API-KEY header.",
  "data": null
}
```

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

**Response fields**

| Field | Type | Req. | Description |
| --- | --- | --- | --- |
| `message` | `string` | required | Error overview. |

**Example**

```json
{
  "success": false,
  "message": "This API key does not have permission to perform this action."
}
```

### 404 — Not found, or not reachable with this key.

**Response fields**

| Field | Type | Req. | Description |
| --- | --- | --- | --- |
| `success` | `boolean` | required | Always `false` in error responses. |
| `message` | `string` | required | Error text in the key's language (set through the `X-Locale` header). |
| `reason` | `string` | — | Machine-readable reason — present on business refusals (for example, `invalid_order_status`); other errors omit it. Branch on it, not on the message text. |
| `error_code` | `string` | — | The same machine-readable code as in `reason` — a second name for the field. Arrives together with `reason`; the values always match. |

**Example**

```json
{
  "success": false,
  "message": "Resource not found."
}
```

---

- This page in the browser: https://lumean.app/en/developers/docs/api/get-voices-voice
- Full machine-readable reference: https://api.lumean.app/docs/llm.md