Преобразование статьи в речь (ATS)
Преобразуйте полную статью в аудиозапись и текстовую расшифровку, которые будут асинхронно отправлены на ваш callback-URL.
Эндпоинт 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@moknah.io.