Документация

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

Зарегистрируйтесь, откройте в консоли раздел «Ключи» и создайте ключ. Секрет показывается один раз — сохраните его в переменную окружения:

export SPEECHKIT_KEY=sk_...

Ключ передаётся заголовком Authorization: Api-Key …. Базовый адрес HTTP API — https://speech.ctai.dev.

Распознать запись

POST /speech/v1/stt:recognize — звук в теле запроса, в ответе JSON с текстом. Подходит для коротких записей — фраз, реплик, голосовых сообщений. Принимаются WAV и OGG/Opus (format=oggopus), а также сырой PCM: format=lpcm&sampleRateHertz=16000.

Язык указывать не нужно: модель сама понимает саха и русский, в том числе вперемешку. Параметр lang принимается для совместимости.

curl -X POST "https://speech.ctai.dev/speech/v1/stt:recognize?format=oggopus" \
  -H "Authorization: Api-Key $SPEECHKIT_KEY" \
  --data-binary @запись.ogg

# {"result": "Дорообо! Сегодня в Якутске минус сорок"}

Озвучить текст

Два варианта, как в SpeechKit: POST /speech/v1/tts:synthesize — форма, в ответе сразу звук;POST /tts/v3/utteranceSynthesis — JSON, в ответе построчный JSON с кусками звука в base64.

Голос задаётся параметром voice: готовый — sakha-female (женский, саха), или id вашего голоса. Форматы: oggopus, wav, lpcm.

# HTTP v1: форма, в ответе — сам звук
curl -X POST "https://speech.ctai.dev/speech/v1/tts:synthesize" \
  -H "Authorization: Api-Key $SPEECHKIT_KEY" \
  --data-urlencode "text=Дорообо! Добро пожаловать." \
  -d "voice=sakha-female" -d "format=oggopus" \
  -o речь.ogg

Свой голос через API

Голос создаётся по образцу: 10–30 секунд чистой речи одного человека без музыки и шума, плюс точная расшифровка того, что сказано. Отправьте POST /v1/voices как multipart/form-data с полями:

• name — название голоса;
• audio — файл образца (WAV, OGG, MP3);
• text — расшифровка образца.

В ответ придёт {id, name, status}. Дальше указывайте voice=<id> в любом запросе синтеза.

# 1. Создать голос: 10–30 секунд чистой речи и её расшифровка
curl -X POST "https://speech.ctai.dev/v1/voices" \
  -H "Authorization: Api-Key $SPEECHKIT_KEY" \
  -F "name=Диктор" \
  -F "audio=@образец.wav" \
  -F "text=Точная расшифровка того, что сказано в образце."

# {"id": "v_8f2k1q", "name": "Диктор", "status": "ready"}

# 2. Озвучить этим голосом — его id в параметре voice
curl -X POST "https://speech.ctai.dev/speech/v1/tts:synthesize" \
  -H "Authorization: Api-Key $SPEECHKIT_KEY" \
  --data-urlencode "text=Үтүө күнүнэн!" \
  -d "voice=v_8f2k1q" -d "format=oggopus" -o речь.ogg

Список голосов и удаление своего:

# Все доступные голоса: пресеты и ваши
curl -H "Authorization: Api-Key $SPEECHKIT_KEY" "https://speech.ctai.dev/v1/voices"

# Удалить свой голос
curl -X DELETE -H "Authorization: Api-Key $SPEECHKIT_KEY" "https://speech.ctai.dev/v1/voices/v_8f2k1q"

Длинные записи

Длинные записи — совещания, эфиры, лекции — разбираются через очередь и стоит дешевле.POST /stt/v3/recognizeFileAsync возвращает операцию, её состояние — в GET /operations/<id>, текст — в GET /stt/v3/getRecognition?operationId=<id>.

# 1. Поставить запись в очередь — в ответ придёт операция с id
curl -X POST "https://speech.ctai.dev/stt/v3/recognizeFileAsync" \
  -H "Authorization: Api-Key $SPEECHKIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "'"$(base64 < лекция.wav | tr -d '\n')"'",
    "recognitionModel": {
      "audioFormat": {"containerAudio": {"containerAudioType": "WAV"}}
    }
  }'

# 2. Дождаться done: true
curl -H "Authorization: Api-Key $SPEECHKIT_KEY" "https://speech.ctai.dev/operations/<id>"

# 3. Забрать текст
curl -H "Authorization: Api-Key $SPEECHKIT_KEY" \
  "https://speech.ctai.dev/stt/v3/getRecognition?operationId=<id>"

gRPC и потоки

Потоковое распознавание (звонки, голосовые боты) и синтез доступны по gRPC v3 с TLS: хост api.speech.ctai.dev:443. Сервисы и сообщения — как в облаке Яндекса (speechkit.stt.v3.Recognizer, speechkit.tts.v3.Synthesizer), поэтому подходят официальные клиентские заглушки. Ключ — в метаданных authorization: Api-Key ….

# pip install yandexcloud grpcio — официальные заглушки облака
import grpc, os
from yandex.cloud.ai.tts.v3 import tts_pb2, tts_service_pb2_grpc

channel = grpc.secure_channel("api.speech.ctai.dev:443", grpc.ssl_channel_credentials())
stub = tts_service_pb2_grpc.SynthesizerStub(channel)

request = tts_pb2.UtteranceSynthesisRequest(
    text="Дорообо! Добро пожаловать.",
    hints=[tts_pb2.Hints(voice="sakha-female")],
    output_audio_spec=tts_pb2.AudioFormatOptions(
        container_audio=tts_pb2.ContainerAudio(
            container_audio_type=tts_pb2.ContainerAudio.WAV)),
)
metadata = [("authorization", f"Api-Key {os.environ['SPEECHKIT_KEY']}")]

with open("речь.wav", "wb") as out:
    for chunk in stub.UtteranceSynthesis(request, metadata=metadata):
        out.write(chunk.audio_chunk.data)

В потоке распознавания передавайте сырой звук: LINEAR16_PCM, моно.

Переход с Yandex SpeechKit

• Замените адрес stt.api.cloud.yandex.net / tts.api.cloud.yandex.net на speech.ctai.dev (HTTP) или api.speech.ctai.dev:443 (gRPC).
• Замените ключ на ключ из нашей консоли — заголовок тот же.
• Голоса Яндекса заменяются нашими: sakha-female или ваш.
• Роли и эмоции (emotion, role) принимаются и влияют на подачу; разметка SSML читается как текст с паузами.
• Разделения по говорящим и аналитики речи пока нет — поля принимаются, но остаются пустыми.

Ошибки и лимиты

Ошибки — в том же виде, что у SpeechKit: 401 — неверный ключ, 402 — закончился баланс,429 — превышен лимит запросов или месячная квота ключа, 400 — запись длиннее предела или формат не поддержан.

Стоимость запроса и остаток баланса приходят в заголовках ответа: x-speechkit-charged-micros и x-speechkit-balance-micros (1 ₽ = 1 000 000).