Moknah Документы
Начать бесплатно
Справочник по API

Преобразование статьи в речь (ATS)

Преобразуйте полную статью в аудиозапись и текстовую расшифровку, которые будут асинхронно отправлены на ваш callback-URL.

ПУБЛИКАЦИЯ https://api.moknah.io/process-text

Эндпоинт Article to Speech (ATS) принимает текст статьи и генерирует аудиоверсию в формате MP3 вместе с синхронизированным файлом транскрипции (.srt). Генерация происходит асинхронно: запрос сразу возвращает код 202 Accepted, а готовые файлы отправляются на указанный вами callbackURL. Это тот же сервис, который обеспечивает работу плагина ATS для WordPress.

Асинхронный по своей сути

Не ожидайте получения аудио в HTTP-ответе. Эндпоинт сразу возвращает код 202, а по завершении генерации отправляет результат методом POST на ваш callbackURL.

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

Укажите API-ключ вашей компании в качестве Bearer-токена в заголовке Authorization.

Authorization: Bearer your_api_key

Тело запроса

Отправьте JSON-тело, содержащее необработанный текст статьи и объект postData с описанием запроса.

Параметр Обязательно Тип Описание
text обязательный строка Полный текст статьи для преобразования в речь.
postData обязательный объект Метаданные запроса. См. поля ниже.

Объект postData

Поле Обязательно Тип По умолчанию Описание
name обязательный строка — Заголовок статьи. Используется в качестве названия запроса на генерацию аудио.
articleId обязательный строка — Ваш уникальный идентификатор статьи. Он служит ключом идемпотентности (см. раздел «Идемпотентность» ниже) и возвращается в обратном вызове (callback).
voiceId обязательный строка — Голос для озвучивания. Используйте ID из список голосов. Используйте голос того же типа, что и API-ключ вашей компании: стандартный ключ работает со стандартными голосами (voice_engine = standard), расширенный — с расширенными (voice_engine = advanced). Тип выбирается при создании ключа. В обоих случаях каждое предложение в файле .srt размечено по словам.
callbackURL обязательный строка (URL) — HTTPS-URL, на который Moknah будет отправлять (методом POST) URL-адреса готовой аудиозаписи и расшифровки. Для компании сохраняется последнее установленное значение.
preprocessType по выбору строка "0" Режим подготовки текста: «0» — без обработки (чтение дословно), «2» — арабский ташкиль (ИИ расставляет огласовки и записывает числа словами; стоимость за символ удваивается). Передаётся строкой или числом. «2» доступен только для арабского языка, и в ИИ отправляются только арабские предложения.
language по выбору строка "auto" Язык контента: "auto" или код ISO 639-1, например "ar" или "en". При "auto" preprocessType "2" применяется, только если текст на арабском; иначе статья озвучивается как с "0" и оплачивается один раз. Запрос с "2" и языком, отличным от арабского, отклоняется с ошибкой 422 VALIDATION_ERROR.
regenerate по выбору булев false Если установлено значение true, принудительно выполняется повторная генерация, даже если данный articleId уже был сгенерирован ранее.

Пример запроса

curl -X POST "https://api.moknah.io/process-text" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "الذكاء الاصطناعي يتطور بسرعة كبيرة في كل المجالات.",
    "postData": {
        "name": "AI is evolving fast",
        "articleId": "post-123",
        "voiceId": "12",
        "callbackURL": "https://your-site.com/wp-json/ats/v1/callback",
        "preprocessType": "0",
        "language": "auto",
        "regenerate": false
    }
  }'
import requests

response = requests.post(
    "https://api.moknah.io/process-text",
    headers={
        "Authorization": "Bearer your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "text": "الذكاء الاصطناعي يتطور بسرعة كبيرة في كل المجالات.",
        "postData": {
            "name": "AI is evolving fast",
            "articleId": "post-123",
            "voiceId": "12",
            "callbackURL": "https://your-site.com/wp-json/ats/v1/callback",
            "preprocessType": "0",
            "language": "auto",
            "regenerate": False
        }
    }
)

# 202 Accepted — the audio is delivered to your callbackURL
print(response.status_code, response.text)
const response = await fetch(
    'https://api.moknah.io/process-text',
    {
        method: 'POST',
        headers: {
            'Authorization': 'Bearer your_api_key',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            text: 'الذكاء الاصطناعي يتطور بسرعة كبيرة في كل المجالات.',
            postData: {
                name: 'AI is evolving fast',
                articleId: 'post-123',
                voiceId: '12',
                callbackURL: 'https://your-site.com/wp-json/ats/v1/callback',
                preprocessType: '0',
                language: 'auto',
                regenerate: false
            }
        })
    }
);

// 202 Accepted — result arrives at your callbackURL

Немедленное реагирование

Если запрос принят, эндпоинт отвечает немедленно:

Processing started. Results will be sent to the callback URL.

Полезная нагрузка обратного вызова

По завершении генерации Moknah отправляет POST-запрос на ваш callbackURL со следующим телом в формате JSON:

{
    "articleId": "post-123",
    "response": {
        "audioFile": "https://api-storage.moknah.io/.../******.mp3",
        "srtFile": "https://api-storage.moknah.io/.../******.srt",
        "signature": "<hmac-sha256-hex>"
    }
}
Поле Описание
articleId Тот же самый articleId, который вы отправили в запросе.
response.audioFile Публичный URL сгенерированной MP3-озвучки или null, если генерация не удалась.
response.srtFile Публичный URL-адрес файла синхронизированной расшифровки (.srt) или null, если создание файла не удалось.
response.signature Подпись HMAC-SHA256, которую можно использовать для проверки подлинности полезной нагрузки (см. ниже).
Обработка неудачных поколений

Callback также отправляется, если в результате генерации аудио не было создано. В этом случае поля response.audioFile и response.srtFile имеют значение null (подпись при этом охватывает комбинацию articleId|null|null). Любой callback, в котором audioFile или srtFile равен null, следует рассматривать как сбой: не помечайте статью как завершенную, а отправьте запрос повторно, установив параметр regenerate в значение true.

Проверка подписи

Подпись представляет собой HMAC-SHA256 (в формате hex) от строки articleId|audioFile|srtFile, вычисленный с использованием SHA-256-хеша (в формате hex) вашего API-ключа. Вычислите это значение на своей стороне и сравните его с полученным, чтобы убедиться, что callback поступил от Moknah и данные не были изменены.

import crypto from 'crypto';

const keyHash = crypto.createHash('sha256').update(API_KEY).digest('hex');
const payload = `${articleId}|${audioFile}|${srtFile}`;
const expected = crypto.createHmac('sha256', keyHash).update(payload).digest('hex');

const isValid = expected === signature;
import hashlib, hmac

key_hash = hashlib.sha256(API_KEY.encode()).hexdigest()
payload = f"{article_id}|{audio_file}|{srt_file}"
expected = hmac.new(key_hash.encode(), payload.encode(), hashlib.sha256).hexdigest()

is_valid = hmac.compare_digest(expected, signature)

Идемпотентность и регенерация

  • Запросы идентифицируются по параметру articleId в рамках каждой компании. Новый articleId инициирует новый цикл генерации.
  • Если в данный момент выполняется генерация статьи, повторные запросы отклоняются с кодом 409 ALREADY_PROCESSING.
  • Если статья уже была сгенерирована, а параметр regenerate имеет значение false, то существующая аудиозапись будет повторно отправлена на ваш callbackURL без повторной генерации (и без повторного списания средств).
  • Установите параметр regenerate в значение true, чтобы принудительно выполнить повторную генерацию для существующего articleId.
  • Если предыдущая попытка для articleId не удалась, повторная отправка создаст его заново; новый articleId не нужен.

Параллелизм и пропускная способность

Статьи создаются из очереди, в которой каждый клиент получает справедливую долю. Можно отправить много статей сразу: все они принимаются, создаются по несколько за раз, и каждая доставляется на ваш callback URL, как только будет готова.

  • Поэтому большая партия завершается постепенно, а не вся сразу; придерживать статьи на своей стороне не нужно.
  • Повторите попытку обработки любой статьи, завершившейся с ошибкой, установив параметр regenerate в значение true; уже сгенерированные статьи кэшируются, и их не нужно отправлять повторно.
  • Для эндпоинта /process-text также действуют ограничения по частоте запросов для каждого клиента; при превышении лимита возвращается ошибка 429 (Too Many Requests), поэтому следует распределять запросы во времени или отправлять их пакетами.

Выставление счетов

Стоимость в символах рассчитывается как количество символов в text, умноженное на коэффициент предварительной обработки (по умолчанию — 1, при preprocessType, равном 2, — 2). Кредиты списываются только в момент фактического выполнения генерации. Повторная отправка уже сгенерированной статьи бесплатна, а в случае сбоя генерации или отправки списанные кредиты возвращаются автоматически.

Расширенные голоса (voice_engine = advanced) оплачиваются по тарифу расширенного режима, в дополнение к множителю предварительной обработки.

Ошибки

Статус Код Описание
401 AUTH_FAILED Отсутствует заголовок Authorization или неверный API-ключ.
422 VALIDATION_ERROR Отсутствует текст либо поля postData недействительны или отсутствуют.
400 INVALID_VOICE_ID Указанный voiceId не существует.
400 UNSUPPORTED_VOICE Этот голос не соответствует типу вашего API-ключа (стандартный или расширенный) или сейчас недоступен.
409 ALREADY_PROCESSING Эта статья уже создается. Повторите попытку после завершения процесса.
422 PROCESSING_ERROR Сбой генерации. Списанные кредиты возвращены.
422 REFUND_FAILED Обработка не удалась, и автоматический возврат средств не был выполнен. Свяжитесь с api@moknah.io.
Поддержка API

По вопросам или проблемам, связанным с API, обращайтесь к нам по адресу api@moknah.io.