Часто задаваемые вопросы
Какой формат ключа API?
Ключ начинается с префикса tts-. Он передается в заголовке Authorization: Bearer tts-... У каждого аккаунта один активный ключ. При выпуске нового старый немедленно становится недействительным. Ключ можно менять неограниченное количество раз через личный кабинет.
Можно ли использовать OpenAI SDK?
Да, API совместим по структуре запросов с OpenAI. Для использования измените base_url на https://api.getaagame.com/v1 и укажите свой ключ. Это позволяет применять официальные SDK OpenAI без изменения логики интеграции в ваш код.
Какая максимальная длина текста?
Максимальная длина составляет 4096 символов за один запрос. Для длинных текстов необходимо разбить их на части по 4096 символов, сгенерировать аудио для каждой и объединить файлы. Пробелы и знаки препинания учитываются в лимите символов.
Поддерживается ли параллельная генерация?
Запросы обрабатываются последовательно. При высокой нагрузке запросы могут стоять в очереди. Это может увеличить общее время синтеза при массовых запросах.
Как указать язык для латиницы?
Если язык не указан, система угадывает его по скрипту, и текст на латинице по умолчанию принимается за английский. Для других языков, использующих латиницу (например, немецкого или испанского), поле language необходимо задать явно кодом ISO.
Что делает поле model?
Поле model определяет движок синтеза: tts-1 или tts-1-hd. Оба варианта используют один и тот же движок и имеют одинаковую стоимость. Выбор модели не влияет на качество или цену, но обязателен для формирования запроса.
Возвращается ли файл сразу?
Да, сгенерированный аудиофайл возвращается непосредственно в ответе на запрос. Файлы не сохраняются на сервере после отправки. Поддерживаемые форматы: mp3, wav, opus, flac, pcm. Вы получаете готовый файл сразу после завершения синтеза.
Где найти список доступных голосов?
Список голосов, языков, форматов и цен доступен по эндпоинту GET /v1/voices. Также можно использовать GET /v1/models для получения информации о моделях. Эти данные позволяют выбрать подходящий голос и формат для интеграции.
Первый запрос
curl
curl https://api.getaagame.com/v1/audio/speech \
-H "Authorization: Bearer $TTS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
--output hello.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.getaagame.com/v1", api_key="tts-...")
with client.audio.speech.with_streaming_response.create(
model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
response.stream_to_file("hello.mp3")Node.js (openai)
import OpenAI from "openai";
import fs from "node:fs";
const client = new OpenAI({ baseURL: "https://api.getaagame.com/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));| voice | |
|---|---|
aria | женский |
nova | женский |
luna | женский |
sage | женский |
felix | мужской |
milo | мужской |
atlas | мужской |
orion | мужской |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
Быстрый старт
Для начала работы с Lectoris необходимо получить API-ключ на странице /get-api-key/. Учетные записи создаются через Google или по электронной почте. Ключ авторизации используется для всех запросов к API.
API поддерживает стандартный формат запросов OpenAI, что позволяет использовать готовые библиотеки. Базовый URL для всех запросов: https://api.getaagame.com/v1.
Получение API ключа
Перейдите на страницу регистрации /get-api-key/. Выберите авторизацию через Google или создайте учетную запись с паролем. После входа вы получите уникальный токен доступа в формате tts-....
- Регистрация доступна через Google или email+password
- Один активный ключ на аккаунт
- Ключ отображается сразу после входа
Первый запрос через cURL
Отправьте текст для синтеза с помощью HTTP-запроса POST. Укажите модель, голос и сам текст в теле запроса. В ответе вы получите аудиофайл в выбранном формате.
- Метод: POST https://api.getaagame.com/v1/audio/speech
- Заголовок: Authorization: Bearer <ваш_ключ>
- Тело: JSON с полями model, input, voice
Проверка баланса и ключей
На странице личного кабинета доступен текущий баланс, оставшиеся символы и история использования. Тестовый аккаунт получает $0.50 кредита на 7 дней при входе через Google.
- Просмотр баланса и истории запросов
- Отображение остатка символов
- Статус тестового кредита (если применимо)
Структура запроса
Запрос отправляется методом POST на endpoint /v1/audio/speech. Тело запроса содержит JSON-объект с обязательными полями модели, входного текста и голоса. Формат данных соответствует спецификации стандартных API синтеза речи, что упрощает интеграцию в существующие рабочие процессы образовательных платформ.
Поле model: tts-1 и tts-1-hd
Доступны две версии движка синтеза: «tts-1» и «tts-1-hd». Обе используют один и тот же базовый движок и имеют одинаковую стоимость генерации. Выбор между ними зависит от требуемого качества аудио и допустимой задержки при обработке.
Поле input: текст до 4096 символов
Поле input принимает строку текста, которая будет преобразована в аудио. Максимальная длина одного запроса составляет 4096 символов. Пробелы и знаки препинания учитываются при подсчете лимита.
Поле voice: выбор из 8 пресетов
Параметр voice определяет тембр и стиль озвучки. Доступно восемь предустановленных голосов, включая женские (Aria, Nova, Luna, Sage) и мужские (Felix, Milo, Atlas, Orion). Каждый голос подходит для разных типов образовательного контента: от лекций до промо-материалов.
- Aria: теплый, чистый повествовательный стиль
- Luna: мягкий, подходящий для сторителлинга
- Felix: энергичный, для промо-материалов
- Atlas: нейтральный, новостной стиль
Параметры настройки
Формат аудиофайла выбирается параметром response_format. Доступны mp3, wav, opus, flac и pcm. Выбор зависит от требований вашей LMS или плеера к совместимости и весу файлов.
Скорость воспроизведения регулируется параметром speed в диапазоне от 0.25 до 4.0. Стандартное значение — 1.0. Это позволяет адаптировать речь под темп восприятия аудитории в образовательных материалах.
Форматы ответа: mp3, wav, opus, flac, pcm
API возвращает аудио в запрошенном формате. MP3 оптимален для веба, WAV и FLAC обеспечивают высокое качество без сжатия. PCM подходит для прямой обработки сырого аудиопотока. Опус (Opus) обеспечивает малый размер файла при сохранении разборчивости голоса.
- mp3: сжатие, малый вес
- wav: без потерь
- opus: эффективное сжатие
- flac: Lossless
- pcm: сырой аудиопоток
Настройка скорости: от 0.25 до 4.0
Параметр speed принимает значения от 0.25 до 4.0. Значение 1.0 соответствует естественному темпу. Увеличение скорости полезно для кратких инструкций, снижение — для сложных объяснений или аудирования.
Указание языка через ISO код
Параметр language принимает ISO-код языка. Если поле не указано, система определяет язык по скрипту текста (латиница по умолчанию — английский). Для точного распознавания текста на других языках латиницей (например, немецком или польском) язык следует указывать явно.
- Поддерживаются 23 языка, включая русский, английский, немецкий, французский, испанский, китайский, японский и другие.
- Примеры кодов: ru, en, de, fr, es, zh, ja.
Интеграция с OpenAI SDK
API Lectoris совместим по структуре запросов с официальными SDK OpenAI, что позволяет интегрировать синтез речи в существующие проекты без написания кастомной логики. Для этого достаточно изменить базовый URL клиента на https://api.getaagame.com/v1, сохранив стандартную структуру запросов.
Такая архитектура упрощает поддержку кода: вы используете знакомые методы библиотеки, а инфраструктурные детали маршрутизации обрабатываются автоматически. Это подходит для no-code и low-code сценариев, где важна скорость внедрения.
Изменение base_url
Укажите базовый URL https://api.getaagame.com/v1 в настройках вашего SDK-клиента. Это перенаправляет запросы к нашей инфраструктуре, сохраняя совместимость с форматом данных OpenAI.
- Базовый URL: https://api.getaagame.com/v1
- Формат запроса идентичен OpenAI Speech endpoint
Использование стандартных библиотек
Используйте официальные SDK (Python, Node.js и др.) без модификации их ядра. Вам требуется только передать API-ключ в заголовке авторизации и указать правильный endpoint.
Пример кода на Python
```python import openai client = openai.OpenAI( base_url="https://api.getaagame.com/v1", api_key="tts-ваш_ключ" ) response = client.audio.speech.create( model="tts-1", voice="nova", input="Текст лекции для онлайн-курса", response_format="mp3" ) response.write_to_file("lecture.mp3") ```
Обработка ошибок
API возвращает стандартные HTTP-коды для индикации состояния. При успешном синтезе возвращается 200 OK с аудиофайлом в теле ответа. Ошибки клиентской стороны (неверный ключ, лимит символов) маркируются кодами 4xx, серверные сбои — 5xx.
Коды статусов HTTP
Используйте стандартные коды для интеграции. 200 означает успешное получение файла. 400 — ошибка валидации параметров (например, превышение лимита в 4096 символов или неверный формат голоса). 401 — недействительный или отсутствующий API-ключ. 429 — превышение лимита в 60 запросов в минуту. 500–503 — временные технические неполадки на стороне сервера, попробуйте повторить запрос с экспоненциальной задержкой.
- 200 OK: Успешный синтез
- 400 Bad Request: Ошибка параметров запроса
- 401 Unauthorized: Неверный API-ключ
- 429 Too Many Requests: Превышен лимит запросов
- 500 Internal Server Error: Внутренняя ошибка сервера
Возврат средств при сбое
Если синтез завершился ошибкой, средства за этот запрос возвращаются на баланс в полном объеме. Заряд списывается только при успешной генерации аудиофайла. Проверьте поле status в ответе API для подтверждения статуса транзакции.
Логирование метаданных
Система сохраняет метаданные запросов для биллинга и аудита. В логах фиксируются время запроса, объем использованных символов и итоговый статус. Эти данные доступны в личном кабинете и полезны для отладки интеграции и контроля расходов. Вводный текст и сгенерированное аудио в лог не сохраняются.
- Время запроса
- Количество обработанных символов
- Статус выполнения (успех/ошибка)
- Идентификатор запроса

Лимиты и ограничения
API Lectoris гарантирует стабильную обработку запросов в рамках установленных лимитов. Генерация звука происходит последовательно, поэтому при высокой нагрузке запросы могут находиться в очереди. Это обеспечивает корректную обработку каждого фрагмента текста без потери качества синтеза.
60 запросов в минуту
Один API-ключ позволяет отправлять до 60 запросов в минуту. Этого объема достаточно для большинства сценариев использования, включая пакетную генерацию лекций или учебных модулей. Если требуется увеличить пропускную способность, можно использовать дополнительные ключи или оптимизировать длину текста в одном запросе.
10 запросов до первого пополнения
Для новых аккаунтов без пополнения баланса лимит снижается до 10 запросов в минуту. Это ограничение действует до момента первого пополнения счета. После успешной транзакции лимит восстанавливается до стандартных 60 запросов в минуту.
Ограничение длины текста
В одном запросе можно передать текст длиной до 4096 символов. Символы пробела и знаки пунктуации также учитываются в лимите. Для более длинных материалов рекомендуется разбивать текст на части, генерировать аудиофайлы по отдельности и затем объединять их в итоговый файл.
Работа с длинными текстами
API обрабатывает текст последовательно, поэтому для длинных материалов требуется разбивка на фрагменты не более 4096 символов. Каждый фрагмент генерируется отдельным запросом, что позволяет сохранить стабильность соединения и корректность аудиофайла.
Разбиение на части
Текст разбивается на фрагменты по 4096 символов. Это ограничение гарантирует, что каждый запрос будет обработан корректно, без потери данных или обрезки предложений.
- Максимальная длина одного запроса — 4096 символов.
- Пробелы и знаки препинания учитываются в лимите.
Последовательное соединение аудио
Полученные аудиофрагменты объединяются в единый файл. Скрипт на стороне клиента должен склеить результаты последовательных запросов, чтобы получить полный аудиофайл лекции или курса.
Оптимизация запросов
Учитывая лимит в 60 запросов в минуту, рекомендуется группировать запросы и избегать одновременной генерации множества длинных текстов. Это предотвратит задержки в очереди.
- Лимит: 60 запросов в минуту на ключ.
- Генерация занимает около 25 символов в секунду.
Безопасность и авторизация
Все запросы к API Lectoris требуют обязательной авторизации через заголовок HTTP. Передайте ваш уникальный API-ключ в поле Authorization со схемой Bearer. Это обеспечивает защиту ваших данных и корректный учет списаний с баланса при генерации аудиофайлов.
Заголовок Authorization: Bearer
Для аутентификации используйте заголовок Authorization: Bearer <ваш_ключ>. Ключ генерируется при создании аккаунта на странице /get-api-key/. Передавайте его в каждом запросе к эндпоинту синтеза речи. Это стандартный метод авторизации, совместимый с большинством HTTP-клиентов и SDK.
Один активный ключ на аккаунт
В системе Lectoris действует принцип единственного активного ключа на аккаунт. При генерации нового токена предыдущий становится недействительным мгновенно. Это упрощает управление доступом к API для образовательных платформ и LMS, исключая необходимость отслеживания множества старых токенов.
Мгновенная отмена старого ключа
Отмена предыдущего ключа происходит без задержек. Как только вы создадите новый токен, старый перестанет принимать запросы сразу же. Это позволяет быстро реагировать на возможные утечки или смену серверов интеграции без ожидания обновления кэша на стороне сервера.
Послушайте 8 голосов
Каждый образец ниже сгенерирован этим API из одного и того же предложения. Для научных лекций предпочтительны нейтральные тембры, тогда как для мотивационных тренингов уместна энергичная подача.
23 языка
Любой голос может говорить на любом из этих языков.
