Skip to content
Lumean API
GET/templates

List Templates

A paginated list of the key owner's templates: by default those at the root (no folder), newest first, 30 per page at most.

templates.read

A template is a saved set of generation settings — service, voice, model, output format. Its id goes into template_id when you create an order. There is no need to create a template per order: reuse one and adjust it per order with config_override in POST /orders.

Response: data.items[] — templates, data.current_page / last_page / per_page / total — pagination. To walk everything request page=1, 2, … until current_page = last_page. Find a template by name with search, by service with service, inside a folder with folder_id; folders together with templates — GET /templates/browse.

Legacy mode (deprecated). A request without a single parameter still returns every root template as one array in data and carries the Deprecation and Sunset (removal date) headers. After that date such a request gets the first page. To migrate, add ?page=1 and read data.items.

Required key permission: templates.read.

On this page(3)

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.

GEThttps://api.lumean.app/api/public/templates
  • integerin queryoptional

    Page number, starting at 1. Any list parameter switches the response to a page; a request with no parameters at all is the deprecated full list (until 06.11.2026).

  • integerin queryoptional

    Templates per page, 1..30. Defaults to 30.

  • stringin queryoptional

    Sort field. Defaults to created_at (newest first with sort_order=desc).

    Allowed values
  • stringin queryoptional

    Sort direction. Defaults to desc.

    Allowed values
  • stringin queryoptional

    Substring of the template name. Case-insensitive.

  • stringin queryoptional

    Show only templates of this service. The code is a short latin string: elevenlabs, heygen, cartesia, sfx, music.

  • stringin queryoptional

    Folder UUID. Omitted — root templates (folder_id = null).

Possible responses

200

Success. The payload is in data.

Body example
{
  "success": true,
  "message": "Templates retrieved",
  "data": {
    "items": [
      {
        "id": "7e2a4c1d-8b3f-4a5e-9c6d-1f2e3a4b5c6d",
        "user_id": 501,
        "slug": null,
        "name": "Narrator Voice (EN)",
        "service_key": "elevenlabs",
        "service": {
          "id": 3,
          "code": "elevenlabs",
          "name": "ElevenLabs",
          "display_name": "ElevenLabs TTS",
          "payg_access": "everyone",
          "billing_mode": "pay_as_you_go",
          "unit_asset_id": 5,
          "unit_asset": {
            "id": 5,
            "code": "tts_units",
            "kind": "unit",
            "precision": 0,
            "name": "TTS Units",
            "deleted_at": null,
            "created_at": "2026-01-10T09:00:00+00:00",
            "updated_at": "2026-01-10T09:00:00+00:00"
          },
          "required_entitlement_id": null,
          "units_per_call": null,
          "units_per_char": 1,
          "units_per_image": null,
          "units_per_second": null,
          "min_billable_chars": 1,
          "lumcoin_per_token": 10,
          "lumc_precision": 2,
          "price_lumc_minor": null,
          "unit_size": 1,
          "uses_money_first_pricing": false,
          "rate_unit": "char",
          "display_category": "voice",
          "is_premium": false,
          "display_order": 1,
          "metadata": null,
          "is_active": true,
          "created_at": "2026-01-10T09:00:00+00:00",
          "updated_at": "2026-01-10T09:00:00+00:00"
        },
        "config": {
          "tts_settings": {
            "model_id": "eleven_multilingual_v2",
            "voice_id": "21m00Tcm4TlvDq8ikWAM",
            "mode": "mode_v1",
            "language_code": null,
            "advanced_voice_settings": true,
            "voice_settings": {
              "stability": 0.5,
              "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-06-01T10:00:00+00:00"
      },
      {
        "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "user_id": 501,
        "slug": null,
        "name": "Podcast Host (RU)",
        "service_key": "elevenlabs",
        "service": {
          "id": 3,
          "code": "elevenlabs",
          "name": "ElevenLabs",
          "display_name": "ElevenLabs TTS",
          "payg_access": "everyone",
          "billing_mode": "pay_as_you_go",
          "unit_asset_id": 5,
          "unit_asset": {
            "id": 5,
            "code": "tts_units",
            "kind": "unit",
            "precision": 0,
            "name": "TTS Units",
            "deleted_at": null,
            "created_at": "2026-01-10T09:00:00+00:00",
            "updated_at": "2026-01-10T09:00:00+00:00"
          },
          "required_entitlement_id": null,
          "units_per_call": null,
          "units_per_char": 1,
          "units_per_image": null,
          "units_per_second": null,
          "min_billable_chars": 1,
          "lumcoin_per_token": 10,
          "lumc_precision": 2,
          "price_lumc_minor": null,
          "unit_size": 1,
          "uses_money_first_pricing": false,
          "rate_unit": "char",
          "display_category": "voice",
          "is_premium": false,
          "display_order": 1,
          "metadata": null,
          "is_active": true,
          "created_at": "2026-01-10T09:00:00+00:00",
          "updated_at": "2026-01-10T09:00:00+00:00"
        },
        "config": {
          "tts_settings": {
            "model_id": "eleven_multilingual_v2",
            "voice_id": "AZnzlk1XvdvUeBnXmlld",
            "mode": "mode_v1",
            "language_code": "ru",
            "advanced_voice_settings": true,
            "voice_settings": {
              "stability": 0.4,
              "similarity_boost": 0.8,
              "use_speaker_boost": true
            }
          }
        },
        "is_public": false,
        "folder_id": null,
        "created_at": "2026-06-10T08:00:00+00:00",
        "updated_at": "2026-06-10T08:00:00+00:00"
      }
    ],
    "current_page": 1,
    "last_page": 1,
    "per_page": 30,
    "total": 2
  }
}
Response fields
datarequired

A page of the key owner’s templates (30 at most): items plus pagination meta. For a walk that includes folders use GET /templates/browse.

TemplateListTemplateList
itemsrequired

Records on the current page, in the list’s sort order.

array<Template>Template
array item
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
current_pagerequired

Current page number, starting from one.

integer
last_pagerequired

Number of the last page. The walk is over once current_page equals last_page.

integer
per_pagerequired

Page size the server applied.

integer
totalrequired

Total number of records matching the filter.

integer
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
successrequired

Always false in error responses.

boolean
messagerequired

Error text in the key's language (set through the X-Locale header).

string
422

Validation error. Offending fields are listed in errors.

Analyse this response
Body example
{
  "message": "string",
  "errors": {}
}
Response fields
messagerequired

Errors overview.

string
errorsrequired

A detailed description of each field that failed validation.

object
*optional
arbitrary keys
array<string>

Nearby

Feed this page to an AI

Open .mdllm.md

spec 0.0.1