PATCHPUT/templates/{template}

Update Template

Partial update: send only the fields you are changing. Both PUT and PATCH are accepted and behave identically.

Spec fixes · 1

config is deep-merged, not replaced wholesale
The spec contradicts itself: the operation description says config is replaced wholesale, the request body description says it is deep-merged. The latter is correct: a key you omit keeps its previous value. Both the 200 response and the partial-update example confirm this. If you do need a full replacement, send the complete config object.

config is replaced wholesale, not merged: to change one setting, send the whole object containing it. service_key may only change together with config, otherwise the config will not validate against the new service's schema.

Editing a template does not affect orders already created: an order runs, is retried (POST /orders/{order}/retry) and is shown (template.config in GET /orders/{order}) with the settings it had at creation time. The exception is orders created before late September 2026: they have no settings snapshot, follow the template's current configuration (with config_override applied), and editing the template does affect them.

Required key permission: templates.write.

On this page(4)

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.

PATCHhttps://api.lumean.app/api/public/templates/

templatestringin pathrequireduuid
Template UUID — 36 characters, not a number.

Take it from the id field: POST /templates returns it on creation, and GET /templates and GET /templates/browse list it.
The value goes straight into the request line above.

Request body

application/json

The update is partial: send only the fields you are changing, the rest are kept.

Two quirks account for most 422 responses here:

service_key and config travel together. Validation rejects one without the other, so even when the service stays the same you have to repeat its code.
config is deep-merged into the current one, not swapped for it. A key you omit keeps its previous value; resetting it to the default is not possible through an update, only by creating the template anew.

Scenarios

Rename only Adjust the voice settings Switch the service

Adjust the voice settings

{
  "service_key": "elevenlabs",
  "config": {
    "tts_settings": {
      "voice_settings": {
        "stability": 0.7,
        "speed": 1.1
      }
    }
  }
}

Fields

folder_idoptional

UUID of the folder to move the template into. null moves it to the root.

nullableuuid

string

service_keyoptional

New service code. Changes only together with config — the config is validated against the new service's schema.

string

Example elevenlabs

nameoptional

New template name, up to 255 characters.

≤ 255 chars

string

is_publicoptional

Publish the template in the shared catalogue, or unpublish it.

boolean

configoptional

The complete new generation settings (not a partial patch). The accepted structure comes from GET /templates/config-options?service=<code>.

object

Possible responses

200

Success. The payload is in data.

Body example

{
  "success": true,
  "message": "Template updated",
  "data": {
    "id": "7e2a4c1d-8b3f-4a5e-9c6d-1f2e3a4b5c6d",
    "user_id": 501,
    "slug": null,
    "name": "Narrator Voice (EN) v2",
    "service_key": "elevenlabs",
    "config": {
      "tts_settings": {
        "model_id": "eleven_multilingual_v2",
        "voice_id": "21m00Tcm4TlvDq8ikWAM",
        "mode": "mode_v1",
        "language_code": "en",
        "advanced_voice_settings": true,
        "voice_settings": {
          "stability": 0.6,
          "similarity_boost": 0.75,
          "use_speaker_boost": true
        }
      }
    },
    "is_public": false,
    "folder_id": null,
    "created_at": "2026-06-01T10:00:00+00:00",
    "updated_at": "2026-07-17T16:45:00+00:00"
  }
}

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 template after the update, with config already merged. Check it when you sent a partial configuration.

TemplateTemplate

idrequired

Template UUID. Put it into template_id when creating an order.

string

user_idrequired

ID of the template owner.

integer

slugrequired

Short public identifier used for sharing. null on a template that was never shared.

string

namerequired

Template name — for humans only; it does not affect generation.

string

service_keyrequired

Code of the service whose schema validates config: elevenlabs, lumimg, and so on.

string

servicerequired

The template’s service for reference: name and pricing, without configuration schemas. null means no service with that code exists any more.

nullable

Service | null

configrequired

Generation settings: voice, model, speed and so on — the set of keys is defined by the service. Look up allowed values in GET /templates/config-options?service=<code>; anything outside the schema is rejected with 422. Inside an order (template in GET /orders/{order}) this is the order’s own settings — the snapshot taken at creation with config_override applied, not the template’s current configuration (for orders created before late September 2026 — the current template configuration with config_override).

object

is_publicrequired

Whether the template is published in the shared catalogue.

boolean

folder_idrequired

UUID of the folder holding the template, or null for the root. The folder tree is visible in GET /templates/browse.

string

created_atrequired

When the template was created, ISO 8601.

nullabledate-time

string

updated_atrequired

When the template last changed, ISO 8601.

nullabledate-time

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

422

Validation error. Offending fields are listed in errors.

Analyse this response

Body example

{
  "message": "string",
  "errors": {
    "key": [
      "string"
    ]
  }
}

Response fields

messagerequired

Errors overview.

string

errorsrequired

A detailed description of each field that failed validation.

object

*optional

arbitrary keys

array<string>

The same in words

Templates are required for TTS

Objects

Template

Neighbouring operations

Feed this page to an AI

Open .md llm.md

spec 0.0.1

Parameters

Request body

Possible responses

Nearby

Feed this page to an AI