Prosto TTS
← К версиям
Для разработчиков

Подключение 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".