---
title: "GET /templates/config-options — Get Template Config Options"
url: https://lumean.app/en/developers/docs/api/get-templates-config-options
locale: en
description: "Get Template Config Options"
generated: 2026-10-17
operationId: template.getConfigOptions
method: GET
path: /templates/config-options
scopes: [templates.read]
spec_version: 0.0.1
---

# GET /templates/config-options

**Get Template Config Options**

The reference of accepted `config` values for one service: what may go into a template
and into an order's `config_override`.

> The directory describes the **service's settings** and does not cover the whole
> `config`. The per-order generation mode (`generation_mode`, paragraph narration) is
> chosen separately and is not listed here — it is documented on the
> `config_override` field of `POST /orders`.

The response is a map of field descriptors. Each field carries `type`, `default` and
`nullable`, plus — depending on the type — `options` (allowed values) or
`min`/`max`/`step` (range). A separate `conditional_overrides` section describes
narrowings that kick in for a particular choice: for non-v3 ElevenLabs models the
language list shrinks from 73 to 29, and on the v3 family `stability` accepts only
`0.0`, `0.5` and `1.0`.

Consult this instead of guessing: a value outside the allowed set is rejected with
`422` when the template or order is created.

### `heygen`: `voice_engine` is per service, not per voice

The `options` listed here are what the **service** supports. Which of them a given
voice supports is a property of the voice: read `voice_engines` on the catalogue
entry from `GET /voices/heygen` and pick a value present in both lists. Of the 2330
catalogue voices, 1947 support `elevenLabs` and 383 support none of the engines
listed here.

Sending a voice and an engine that do not match is rejected with `422` on
`config.tts_settings.voice_id`.

### The section grouping is not always the path in the config

The response is always grouped: a section name, and its fields inside. For
`elevenlabs`, `heygen` and `lumimg` that name is also the path
(`tts_settings.model_id`, `image_settings.aspect_ratio`), so the structure can be
reproduced as is. For `sfx`, `music` and `voice_search` the section is purely
cosmetic: the real keys sit at the root. For those, take the **field names and their
ranges from the response, but not the wrapper**:

| Service | Shown in the directory | Accepted in `config` and `task_data` |
| --- | --- | --- |
| `elevenlabs` | `tts_settings` → `model_id` | `{"tts_settings": {"model_id": …}}` |
| `sfx` | `sfx_settings` → `text` | `{"text": …}` |
| `music` | `music_settings` → `prompt` | `{"prompt": …}` |
| `voice_search` | `voice_search_settings` → `top` | `{"top": …}` |

Sending the wrapper gives `422` in a template ("the field is required" — the
required key ended up hidden), and is silently dropped in an order's
`config_override`.

**Required key permission:** `templates.read`.

- Required scope: `templates.read`

## Request

```bash
curl -X GET 'https://api.lumean.app/api/public/templates/config-options' \
  -H 'Accept: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY'
```

## Parameters

| Field | In | Type | Req. | Description |
| --- | --- | --- | --- | --- |
| `service` | query | `string` | required | **Required.** The service code whose config options you need — a short latin string such as `elevenlabs`, `heygen`, `lumimg`, `sfx` or `music`. The codes available to you are listed by `GET /usage` in its `service_code` field. For example `elevenlabs`. The response is a map of field descriptors (`type`, `options`, `min`, `max`, `step`, `default`, `nullable`, `conditional_overrides`): allowed models, voices and setting ranges. Consult it instead of guessing. The directory describes the **service's settings** and does not cover the whole `config`: the per-order generation mode (`generation_mode`) is not part of it — see the `config_override` field of `POST /orders`. |

## 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` | `object` | required | A map of descriptors: the key is a `config` field name, the value describes what may go into it. A descriptor always carries `type`, `default` and `nullable`; beyond that it has either `options` (a list of allowed values) or `min`/`max`/`step` (a range). A separate `conditional_overrides` key describes narrowings that switch on for particular choices: on ElevenLabs v3 models, for instance, `stability` accepts only `0.0`, `0.5` and `1.0`, and non-v3 models offer a shorter language list. An empty object means the service has no configurable `config` — voice cloning is one such case. |
| `data.*` | `any` — arbitrary keys | — |  |

**Example**

```json
{
  "success": true,
  "message": "Template config options retrieved",
  "data": {
    "tts_settings": {
      "model_id": {
        "type": "select",
        "options": [
          "eleven_v4",
          "eleven_v4_exp",
          "eleven_v3",
          "eleven_v3_beta",
          "eleven_multilingual_v2",
          "eleven_flash_v2_5",
          "eleven_turbo_v2_5",
          "eleven_turbo_v2",
          "eleven_flash_v2"
        ],
        "default": "eleven_multilingual_v2"
      },
      "public_owner_id": {
        "type": "string",
        "default": null,
        "nullable": true
      },
      "voice_id": {
        "type": "string"
      },
      "mode": {
        "type": "select",
        "options": [
          "mode_v1"
        ],
        "default": "mode_v1"
      },
      "language_code": {
        "type": "select",
        "options": [
          "en",
          "ja",
          "zh",
          "de",
          "hi",
          "fr",
          "ko",
          "pt",
          "it",
          "es",
          "id",
          "nl",
          "tr",
          "fil",
          "pl",
          "sv",
          "bg",
          "ro",
          "ar",
          "cs",
          "el",
          "fi",
          "hr",
          "ms",
          "sk",
          "da",
          "ta",
          "uk",
          "ru",
          "af",
          "hy",
          "as",
          "az",
          "be",
          "bn",
          "bs",
          "ca",
          "ceb",
          "ny",
          "et",
          "gl",
          "ka",
          "gu",
          "ha",
          "he",
          "hu",
          "is",
          "ga",
          "jv",
          "kn",
          "kk",
          "ky",
          "lv",
          "ln",
          "lt",
          "lb",
          "mk",
          "ml",
          "mr",
          "ne",
          "no",
          "or",
          "ps",
          "fa",
          "pa",
          "sr",
          "sl",
          "sw",
          "te",
          "th",
          "ur",
          "vi",
          "cy"
        ],
        "default": null,
        "nullable": true
      },
      "advanced_voice_settings": {
        "type": "boolean",
        "default": false,
        "nullable": true
      },
      "prev_next_text": {
        "type": "boolean",
        "default": false,
        "nullable": true
      },
      "request_ids": {
        "type": "boolean",
        "default": false,
        "nullable": true
      },
      "apply_text_normalization": {
        "type": "select",
        "options": [
          "auto",
          "on",
          "off"
        ],
        "default": "auto",
        "nullable": true
      },
      "voice_settings": {
        "stability": {
          "type": "range",
          "default": 0.5,
          "min": 0,
          "max": 1,
          "step": 0.1,
          "conditional_overrides": [
            {
              "when": {
                "operator": "and",
                "rules": [
                  {
                    "field": "tts_settings.model_id",
                    "op": "eq",
                    "value": "eleven_v3"
                  }
                ]
              },
              "set": {
                "min": 0,
                "max": 1,
                "step": 0.5,
                "default": 0.5
              }
            },
            {
              "when": {
                "operator": "and",
                "rules": [
                  {
                    "field": "tts_settings.model_id",
                    "op": "eq",
                    "value": "eleven_v3_beta"
                  }
                ]
              },
              "set": {
                "min": 0,
                "max": 1,
                "step": 0.5,
                "default": 0.5
              }
            }
          ]
        },
        "similarity_boost": {
          "type": "range",
          "default": 0.75,
          "min": 0,
          "max": 1,
          "step": 0.01
        },
        "style": {
          "type": "range",
          "default": 0,
          "nullable": true,
          "min": 0,
          "max": 1,
          "step": 0.01
        },
        "use_speaker_boost": {
          "type": "boolean",
          "default": true
        },
        "speed": {
          "type": "range",
          "default": 1,
          "min": 0.7,
          "max": 1.2,
          "step": 0.01
        }
      }
    },
    "pause_settings": {
      "enabled": {
        "type": "boolean",
        "default": false
      },
      "max_pause_symbols": {
        "type": "integer",
        "default": 500,
        "min": 1,
        "max": 20000
      },
      "default_duration": {
        "type": "range",
        "default": 0.5,
        "min": 0.1,
        "max": 10,
        "step": 0.1
      },
      "auto_paragraph_pause": {
        "type": "boolean",
        "default": false
      },
      "max_shift": {
        "type": "range",
        "default": 0.1,
        "nullable": true,
        "min": 0,
        "max": 2,
        "step": 0.01
      },
      "min_anchor_silence": {
        "type": "number",
        "default": 0.00001,
        "nullable": true,
        "min": 0,
        "max": 1,
        "step": 0.00001
      }
    },
    "stress_settings": {
      "enabled": {
        "type": "boolean",
        "default": false
      }
    },
    "output_settings": {
      "audio_format": {
        "type": "select",
        "options": [
          "mp3",
          "wav",
          "ogg"
        ],
        "default": "mp3",
        "nullable": true
      },
      "audio_quality": {
        "type": "select",
        "options": [
          "low",
          "medium",
          "high",
          "lossless"
        ],
        "default": "high",
        "nullable": true
      },
      "sample_rate": {
        "type": "select",
        "options": [
          22050,
          44100,
          48000
        ],
        "default": 44100,
        "nullable": true
      },
      "crossfade_ms": {
        "type": "integer",
        "default": 0,
        "nullable": true,
        "min": 0,
        "max": 5000
      },
      "loudnorm": {
        "enabled": {
          "type": "boolean",
          "default": false,
          "nullable": true
        },
        "integrated_loudness": {
          "type": "number",
          "default": -16,
          "nullable": true,
          "min": -70,
          "max": 0,
          "step": 0.1
        },
        "true_peak": {
          "type": "number",
          "default": -1.5,
          "nullable": true,
          "min": -9,
          "max": 0,
          "step": 0.1
        },
        "loudness_range": {
          "type": "number",
          "default": 11,
          "nullable": true,
          "min": 1,
          "max": 50,
          "step": 0.1
        }
      }
    }
  }
}
```

### 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 |
| --- | --- | --- | --- |
| `success` | `boolean` | required | Always `false` in error responses. |
| `message` | `string` | required | Error text in the key's language (set through the `X-Locale` header). |

**Example**

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

### 422 — Validation error. Offending fields are listed in `errors`.

**Response fields**

| Field | Type | Req. | Description |
| --- | --- | --- | --- |
| `message` | `string` | required | Errors overview. |
| `errors` | `object` | required | A detailed description of each field that failed validation. |
| `errors.*` | `array<string>` — arbitrary keys | — |  |

**Example**

```json
{
  "message": "string",
  "errors": {}
}
```

---

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