← К версиямДля разработчиков
Подключение API
и установка на Linux.
Как поставить приложение на Ubuntu 24.04 и обратиться к локальному API из своего скрипта — без аккаунта на сайте для установки, аккаунт нужен только для активации.
Установка на Ubuntu 24.04
Скачайте архив на странице версий, распакуйте и откройте терминал в папке ProstoTTS-Linux.
bash install.sh # Общая поставка: графическое приложение и API.
# Для Ubuntu без графического рабочего стола вместо этого:
# bash install.sh --api-only
./api.sh activate # Скрыто ввести ключ приложения из личного кабинета.
./api.sh download-model # Скачать и проверить файлы модели.
./api.sh token-file # Создать локальный API-токен и показать путь к нему.
./api.sh serve # Запустить API без окна. Терминал оставить открытым.
Если приложение уже активировано через графическое окно и модель скачана, первые три действия повторять не нужно — GUI и API делят активацию, настройки и модель одного пользователя Ubuntu. Для экономии памяти закройте GUI перед запуском API: каждый процесс держит свой экземпляр модели.
Во втором терминале, из той же папки:
./api.sh status # Дождаться "state": "ready".
python3 api_example.py --list-voices # Публичные ID и названия голосов.
python3 api_example.py # Ввести реплику, получить answer.wav.
Остановить службу — Ctrl+C в терминале с serve. Проверка установки без активации: ./api.sh check.
Локальный API-токен
Это токен для обращения вашего скрипта к службе на этом же компьютере — он отличается от ключа активации приложения из личного кабинета.
./api.sh token-file
При первом вызове команда создаёт случайный токен, при следующих — использует тот же, и выводит только путь к файлу (обычно ~/.config/ProstoTTS/api.token, права 600), не само значение. Запускайте службу и свой скрипт от одного пользователя Ubuntu.
Фрагмент для своего скрипта
Если у вас уже есть свой ассистент, добавьте эту функцию и вызовите её там, где получен новый текст:
import json
from pathlib import Path
from urllib.request import Request, ProxyHandler, build_opener
TTS_URL = "http://127.0.0.1:8791/v1/synthesize"
TTS_TOKEN_FILE = Path("~/.config/ProstoTTS/api.token").expanduser()
def tts(text, voice_id, *, rate=1.0, pitch=0.0, format="wav", dictionary=True):
"""Передаёт текст локальной службе и возвращает байты WAV/MP3."""
token = TTS_TOKEN_FILE.read_text(encoding="utf-8").strip()
body = json.dumps({
"text": text, "voice_id": voice_id, "rate": rate,
"pitch": pitch, "format": format, "dictionary": dictionary,
}, ensure_ascii=False).encode("utf-8")
request = Request(TTS_URL, data=body, method="POST", headers={
"Authorization": "Bearer " + token,
"Content-Type": "application/json",
})
http = build_opener(ProxyHandler({})) # Подключаться к localhost без прокси.
with http.open(request, timeout=330) as response:
return response.read()
Параметры: text — строка UTF-8 до 5000 символов; voice_id — публичный ID из /v1/voices; rate — скорость 0.5–2.0 (по умолчанию 1.0); pitch — высота от -6 до +6 полутонов (по умолчанию 0.0); format — wav или mp3; dictionary — применять личный словарь (по умолчанию включено).
answer_from_ai = получить_ответ_от_вашего_ии()
audio = tts(answer_from_ai, voice_id=2, format="mp3")
Path("answer.mp3").write_bytes(audio)
Фрагмент уже сохранён в поставке как tts_fragment.py — можно скопировать или импортировать (from tts_fragment import tts). Расширенный пример с CLI и обработкой ошибок — в api_example.py.
Методы и коды ошибок
GET /v1/health — служба запущена, токен не нужен. GET /v1/status — состояние модели и активации. GET /v1/voices — публичные ID и названия голосов. POST /v1/synthesize — текст → байты WAV/MP3. Кроме /v1/health везде нужен заголовок Authorization: Bearer <токен>.
Один запрос синтеза выполняется за раз, очереди и потоковой выдачи аудио в этой версии нет. При ошибке возвращается JSON с полями error.code, error.message, error.details.
400 — неверные параметры или пустой текст. 401 — неверный локальный токен. 402 — закончился пробный доступ или нужна подписка. 403 — запрос из браузерной страницы вместо скрипта. 413 — слишком большой запрос. 429 — служба занята, дождитесь завершения предыдущей озвучки. 503 — модель загружается, нет активации или связи с сервером. 504 — синтез превысил 300 секунд.
Не повторяйте автоматически платный запрос после сетевого тайм-аута — результат выполнения может быть неизвестен.
Другой порт или отдельная папка данных
Если порт 8791 занят, укажите одинаковый новый порт в службе и скрипте:
./api.sh serve --port 8792
./api.sh status --port 8792
python3 api_example.py --port 8792
Параметр --home переносит настройки, авторизацию и модель в отдельную папку (указывается до имени команды во всех вызовах api.sh); для своего скрипта — token_file="/путь/tts-data/api.token".