К содержанию
Lumean API

GET/voices/cartesia

Каталог голосов сервиса озвучки Cartesia: активные голоса с фильтрами по языку (ISO 639-1), полу и строке поиска. voice_id из ответа кладётся в tts_settings.voice_id шаблона с service_key: cartesia; параметр voice_id находит один голос по точному id — подпись голоса, уже выбранного в шаблоне.

voices.read

Свой клонированный голос в каталоге не появляется — его voice_id отдаёт GET /voices/cartesia/clones (только у клона в статусе ready). Голос, склонированный вне Lumean (например, на cartesia.ai), тоже принимается: его id у Cartesia (UUID) кладётся в tts_settings.voice_id как есть.

Если сервис закрыт для владельца ключа (закрытый тест), ответ — 404 с reason: service_not_found.

Требуемое право ключа: voices.read.

На этой странице(3)

Параметры

Поля ввода живут прямо в строке запроса: подставьте значение — и получите готовый URL. Ниже — тип, обязательность и допустимые значения каждого параметра.

GEThttps://api.lumean.app/api/public/voices/cartesia
  • stringв queryнеобязательный≤ 16 симв.

    Язык голоса, код ISO 639-1 (ru, en, …).

  • stringв queryнеобязательный≤ 32 симв.

    Пол голоса в написании каталога Cartesia (masculine, feminine, gender_neutral).

  • stringв queryнеобязательный≤ 255 симв.

    Поиск по названию и описанию голоса.

  • stringв queryнеобязательный≤ 255 симв.

    Точный voice_id голоса — найти подпись и превью голоса, уже выбранного в шаблоне, без перебора страниц. Снятый с каталога голос в ответ не попадает: пустой список.

  • integerв queryнеобязательный≥ 1

    Номер страницы, начиная с 1.

  • integerв queryнеобязательный1..200

    Сколько записей вернуть на странице. Метаданные пагинации лежат рядом с items: current_page, last_page, per_page, total.

Возможные ответы

200

Успех. Полезная нагрузка — в поле data.

Пример тела
{
  "success": true,
  "message": "Success",
  "data": {
    "items": [
      {
        "id": 12,
        "voice_id": "a0e99841-438c-4a64-b679-ae501e7d6091",
        "name": "Russian Narrator",
        "description": "Calm male narrator for audiobooks.",
        "language": "ru",
        "gender": "masculine",
        "preview_url": "https://files.cartesia.ai/previews/a0e99841-438c-4a64-b679-ae501e7d6091.wav"
      },
      {
        "id": 13,
        "voice_id": "2ee87190-8f84-4925-97da-e52547f9462c",
        "name": "Warm Storyteller",
        "description": null,
        "language": "ru",
        "gender": "feminine",
        "preview_url": null
      }
    ],
    "current_page": 1,
    "last_page": 1,
    "per_page": 50,
    "total": 2
  }
}
Поля ответа
successобязательное

Признак успеха. Решение принимайте по HTTP-коду: у любого ответа 2xx здесь true, а ошибка приходит телом другой формы, где этого поля может не быть вовсе.

boolean
messageобязательное

Пояснение для человека, на языке аккаунта. Показать пользователю можно; разбирать программно — нет: формулировки меняются без предупреждения и кодом ошибки не являются.

string
dataобязательное

Полезная нагрузка ответа.

object
itemsобязательное

Голоса каталога Cartesia на этой странице.

array<CartesiaVoice>CartesiaVoice
элемент массива
idобязательное

Внутренний id записи каталога. Для озвучки не нужен — в шаблон идёт voice_id.

string
voice_idобязательное

Идентификатор голоса Cartesia — значение для tts_settings.voice_id шаблона с service_key: cartesia.

string
nameобязательное

Название голоса.

string
descriptionобязательное

Описание голоса от Cartesia либо null.

string
languageобязательное

Язык голоса (ISO 639-1) либо null.

string
genderобязательное

Пол голоса: masculine, feminine, gender_neutral либо null.

string
preview_urlобязательное

Ссылка на демо-запись голоса либо null.

string
current_pageобязательное

Номер текущей страницы, с единицы.

integer
last_pageобязательное

Номер последней страницы.

integer
per_pageобязательное

Размер страницы, применённый сервером.

integer
totalобязательное

Сколько записей всего по фильтру.

integer
401

Невалидный или отсутствующий X-API-KEY

Разобрать этот ответ
Пример тела
{
  "success": false,
  "message": "API key is missing. Provide it in the X-API-KEY header.",
  "data": null
}
Поля ответа
successобязательное

Всегда false в ответах об ошибке.

boolean
messageобязательное

Текст ошибки на языке ключа (задаётся заголовком X-Locale).

string
dataобязательное

Всегда null, когда запрос отклонён до обработки.

может быть null
null
403

У ключа нет права voices.read

Разобрать этот ответ
Пример тела
{
  "success": false,
  "message": "This API key does not have permission to perform this action."
}
Поля ответа
successобязательное

Всегда false в ответах об ошибке.

boolean
messageобязательное

Текст ошибки на языке ключа (задаётся заголовком X-Locale).

string
404

Сервис Cartesia закрыт для владельца ключа (service_not_found)

Разобрать этот ответ
Пример тела
{
  "success": false,
  "message": "Service not found.",
  "reason": "service_not_found",
  "error_code": "service_not_found"
}
Поля ответа
successобязательное

Всегда false у ошибок.

boolean
messageобязательное

Причина отказа словами, на языке аккаунта. Для показа пользователю; ветвиться по ней нельзя — формулировки меняются.

string
reasonобязательное

Машиночитаемая причина бизнес-отказа (например, input_expired, insufficient_balance). Ветвите обработку по ней, а не по тексту message.

string
error_codeобязательное

Тот же машинный код, что в reason, — второе имя поля. Значения всегда совпадают.

string
422

Ошибка валидации. Поля с ошибками перечислены в errors.

Разобрать этот ответ
Пример тела
{
  "message": "string",
  "errors": {}
}
Поля ответа
messageобязательное

Errors overview.

string
errorsобязательное

A detailed description of each field that failed validation.

object
*необязательное
произвольные ключи
array<string>

Рядом

Объекты

Соседние операции

Скормить страницу ИИ

Открыть .mdllm.md

спека 0.0.1