Шаблоны обязательны для TTS

Первое, обо что спотыкается интеграция озвучки: поля orders.voice_id не существует. Голос, модель, формат вывода и тонкие настройки живут в шаблоне; в заказе остаётся текст. Заказ TTS без template_id не создать — task_type: "tts" пройдёт валидацию и упадёт на резолве сервиса.

Порядок из двух шагов

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

# 1. Шаблон: сервис, модель, голос, настройки — один раз
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. Заказ: текст — в top-level input_text, НЕ в 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": "Привет! Это тестовая озвучка." }'

task_data — форма для заказов без шаблона (sfx, music, voice_search): там лежит промпт. Штатные каналы текста TTS — input_text и .txt в input_files[], см. Текст озвучки.

Шаблон принадлежит аккаунту, а не ключу

Шаблон, созданный в веб-кабинете, годится для API, и наоборот: владелец — аккаунт, а не ключ. GET /templates по ключу видит те же шаблоны, что и кабинет. Чужой шаблон не откроется никаким ключом — 403 с reason: "template_access_denied".

Что кладётся в config

Структуру config задаёт сервис из service_key, и угадывать её не нужно: справочник конфигурации отдаёт по каждому полю type, default, nullable и, по типу, options либо min/max/step.

Ответ сгруппирован по секциям, но секция не всегда является путём в конфиге:

Секция conditional_overrides описывает сужения по выбору: у не-v3 моделей ElevenLabs список языков режется с 73 значений до 29, а на v3-семействе stability принимает только 0.0, 0.5 и 1.0. Значение вне схемы → 422 при создании шаблона.

Флаг, без которого три настройки молча не работают

similarity_boost, style и use_speaker_boost действуют только при tts_settings.advanced_voice_settings: true. По умолчанию флаг false, и до движка озвучки доезжают лишь stability и speed.

Разовое отклонение — config_override

config_override в POST /orders — единственный способ поменять параметры под конкретный заказ, не создавая новый шаблон. Форма — тот же объект, что и config; применяется поверх template.config только к этому заказу.

{
  "template_id": "<TEMPLATE_UUID>",
  "input_text": "Тот же текст, другой голос.",
  "config_override": { "tts_settings": { "voice_id": "<OTHER_VOICE_ID>" } }
}

Три правила, которые стоят отладочного вечера:

• Пути вне схемы сервиса отбрасываются молча — опечатка в ключе неотличима от «настройка не применилась»: ни 422, ни предупреждения.
• Явный null стирает, а не значит «оставить как есть»: мерж идёт array_replace_recursive. Сказать «не трогать» можно только отсутствием ключа.
• Работает только вместе с template_id — у template-less sfx/music параметры и так в task_data.

Ключ generation_mode (абзацный режим) лежит не внутри tts_settings, а рядом, в корне: {"generation_mode": "paragraph"}. В справочнике его нет — тот описывает настройки сервиса. Режим влияет на цену: минимальный тарифицируемый объём считается по каждому абзацу.

Правка шаблона: config сливается, а не заменяется

Вторая ловушка того же запроса: service_key и config ходят парой. Одно без другого валидация не принимает — даже когда сервис вы не меняете, код придётся продублировать. PUT и PATCH ведут себя одинаково, а правка не затрагивает уже созданные заказы.

Если заказ TTS не создаётся