Developer docs

TTS API

Endpoints для Text-to-Speech. Для server-to-server интеграции отправляйте X-Api-Key в каждом запросе.

API v1 TTS Sync / Async https://back.aisha.group

API ключи Связаться с командой

Быстрый старт

TTS API

Для генерации аудио отправьте transcript на POST /api/v1/tts/post/.

Если передать webhook_notification_url, запрос будет обработан async и вернет 202 Accepted.

Проверяйте результат через GET /api/v1/tts/status/{id}/ или history.

Аутентификация

API Key

X-Api-Key: <api_key>

Рекомендуется для server-to-server интеграций.

POST

Создать аудио

Endpoint /api/v1/tts/post/

Преобразует текст в аудио. Для language=uz используется built-in модель Gulnoza. Для en и ru параметры model, mood, speed не отправляются.

Аутентификация

Отправьте X-Api-Key. Public-запросы могут требовать reCAPTCHA.

Лимит: 1000 символов с API key, 500 символов для public-запроса.

speed: 0 или значение в диапазоне 0.5-2.0.

mood работает только для built-in Gulnoza. При voice_id параметр mood не используется.

Поля запроса

transcript обязательно

Пример: Assalomu alaykum

string

Текст для озвучивания.

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

Пример: uz

string

Поддерживается: uz, en, ru. Default: uz.

model необязательно

Пример: Gulnoza

string

Только для built-in потока uz. Сейчас доступна только одна модель: Gulnoza.

mood необязательно

Пример: Neutral

string

Только для built-in Gulnoza. Доступно 4 mood: Neutral, Cheerful, Happy, Sad. Для voice_id, en, ru не отправляется.

speed необязательно

Пример: 1.0

float

Только для потока uz. 0 означает default speed. Custom: 0.5-2.0.

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

Пример: 12

integer

READY custom voice ID, принадлежащий user'у. Если используется voice_id, mood не отправляется.

webhook_notification_url необязательно

Пример: https://example.com/webhooks/tts

string

Если задан, TTS запускается async.

Примеры

Sync request

curl --request POST \
  --url https://back.aisha.group/api/v1/tts/post/ \
  --header 'X-Api-Key: your_api_key' \
  --header 'Accept-Language: uz' \
  --form 'transcript=Assalomu alaykum, bu AIsha TTS sinovi.' \
  --form 'language=uz' \
  --form 'model=Gulnoza' \
  --form 'mood=Neutral' \
  --form 'speed=1.0'

Async request

curl --request POST \
  --url https://back.aisha.group/api/v1/tts/post/ \
  --header 'X-Api-Key: your_api_key' \
  --form 'transcript=Webhook orqali qaytadigan sinov matni.' \
  --form 'language=uz' \
  --form 'webhook_notification_url=https://example.com/webhooks/tts'

Ответы

201 Created

Sync success

{
  "audio_path": "/media/tts_audios/request-id.wav"
}

202 Accepted

Async queued

{
  "id": 184,
  "task_id": "7d5f8779-9cb0-4230-9318-2f8c3c3f0e31",
  "status": "PENDING"
}

Статус-коды

201

Аудио готово, вернулся `audio_path`.

202

Async task поставлен в очередь.

400

Ошибка transcript, language, model или speed.

401

Для custom voice нужна авторизация.

402

Недостаточно баланса.

503

TTS сервис временно недоступен.

GET

Проверить статус

Endpoint /api/v1/tts/status/{id}/

Возвращает состояние async TTS task.

Аутентификация

Отправьте X-Api-Key.

Возможные статусы: PENDING, SUCCESS, FAILED.

Примеры

Status request

curl --request GET \
  --url https://back.aisha.group/api/v1/tts/status/184/ \
  --header 'X-Api-Key: your_api_key'

Ответы

200 OK

Pending

{
  "id": 184,
  "status": "PENDING",
  "task_id": "7d5f8779-9cb0-4230-9318-2f8c3c3f0e31"
}

200 OK

Completed

{
  "id": 184,
  "status": "SUCCESS",
  "task_id": "7d5f8779-9cb0-4230-9318-2f8c3c3f0e31",
  "audio_path": "/media/tts_audios/request-id.wav",
  "characters": 42
}

Статус-коды

200

Статус получен.

403

Нет доступа к record другого user'а.

404

TTS record не найден.

GET

История

Endpoint /api/v1/tts/get/?page=1&limit=10

Возвращает paginated историю TTS audio текущего user'а.

Аутентификация

Требуется X-Api-Key.

Response приходит в формате count, next, previous, results.

Примеры

History request

curl --request GET \
  --url 'https://back.aisha.group/api/v1/tts/get/?page=1&limit=10' \
  --header 'X-Api-Key: your_api_key'

Ответы

200 OK

Paginated success

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 184,
      "transcript": "Assalomu alaykum, bu AIsha TTS sinovi.",
      "audio_url": "/media/tts_audios/request-id.wav",
      "model": "Gulnoza",
      "mood": "Neutral",
      "created_at": "2026-05-04T10:15:30Z"
    }
  ]
}

Статус-коды

200

History получена.

403

API key неверный или не отправлен.