Templates are required for TTS

The first thing a voiceover integration trips over: there is no orders.voice_id field. The voice, model, output format, and fine-tuning settings live in the template; the order keeps only the text. You can't create a TTS order without template_id: task_type: "tts" will pass validation and fail at service resolution.

Two steps, in order

BASE=https://api.lumean.app/api/public

# 1. Template: service, model, voice, settings, created once
curl -s -X POST "$BASE/templates" -H "X-API-KEY: $KEY" -d '{
  "service_key": "elevenlabs",
  "name": "My TTS",
  "config": {
    "tts_settings": {
      "mode": "mode_v1",
      "model_id": "eleven_multilingual_v2",
      "voice_id": "<VOICE_ID>",
      "advanced_voice_settings": true,
      "voice_settings": { "stability": 0.5, "similarity_boost": 0.75, "use_speaker_boost": true, "speed": 1.0 }
    }
  }
}'
# → data.id = <TEMPLATE_UUID>

# 2. Order: the text goes in top-level input_text, NOT in task_data
curl -s -X POST "$BASE/orders" -H "X-API-KEY: $KEY" -H "Content-Type: application/json" \
  -d '{ "template_id": "<TEMPLATE_UUID>", "input_text": "Hello! This is a test voiceover." }'

task_data is the shape for orders without a template (sfx, music, voice_search): that is where the prompt goes. The standard channels for TTS text are input_text and a .txt file in input_files[]; see Speech text.

A template belongs to the account, not the key

A template created in the web dashboard works with the API, and vice versa: the owner is the account, not the key. GET /templates called with a key sees the same templates as the dashboard. Another account's template won't open with any key: you get 403 with reason: "template_access_denied".

What goes into config

The structure of config is defined by the service from service_key, and you don't need to guess it: the configuration reference returns type, default, nullable for each field and, depending on the type, either options or min/max/step.

The response is grouped into sections, but a section is not always a path in the config:

The conditional_overrides section describes restrictions that depend on your choices: for non-v3 ElevenLabs models the language list shrinks from 73 values to 29, and on the v3 family stability accepts only 0.0, 0.5, and 1.0. A value outside the schema → 422 when the template is created.

The flag without which three settings silently do nothing

similarity_boost, style, and use_speaker_boost take effect only with tts_settings.advanced_voice_settings: true. The flag defaults to false, and then only stability and speed reach the speech engine.

One-off deviation — config_override

config_override in POST /orders is the only way to change parameters for a specific order without creating a new template. Its shape is the same object as config; it is applied on top of template.config for this order only.

{
  "template_id": "<TEMPLATE_UUID>",
  "input_text": "Same text, different voice.",
  "config_override": { "tts_settings": { "voice_id": "<OTHER_VOICE_ID>" } }
}

Three rules that can each cost you an evening of debugging:

• Paths outside the service schema are silently dropped: a typo in a key is indistinguishable from “the setting wasn't applied”. No 422, no warning.
• An explicit null erases the value; it does not mean “leave as is”: the merge uses array_replace_recursive. The only way to say “don't touch” is to omit the key.
• It works only together with template_id: for template-less sfx/music the parameters are already in task_data.

The generation_mode key (paragraph mode) sits not inside tts_settings but next to it, at the root: {"generation_mode": "paragraph"}. It isn't in the reference, which describes service settings. The mode affects the price: the minimum billable volume is calculated for each paragraph.

Editing a template: config is merged, not replaced

The second trap of the same request: service_key and config go together. Validation doesn't accept one without the other, so even when you aren't changing the service, you have to repeat its key. PUT and PATCH behave the same way, and an edit doesn't affect orders that have already been created.

If a TTS order isn't created