Moknah ドキュメント
無料で始める
APIリファレンス

記事の音声化(ATS)

記事全文を音声と文字起こしに変換し、コールバックURLへ非同期で配信します。

投稿 https://api.moknah.io/process-text

Article to Speech (ATS) エンドポイントは、記事のテキストを受け取り、MP3形式のナレーションと同期用トランスクリプト(.srt)ファイルを生成します。生成処理は非同期で行われます。リクエストに対しては直ちに `202 Accepted` が返され、生成されたファイルは指定した `callbackURL` に送信されます。これは、ATS WordPressプラグインの基盤となっているサービスと同じものです。

設計上、非同期

音声データのHTTPレスポンスを待機しないでください。エンドポイントは直ちに「202」を返し、生成完了時に結果をcallbackURLへPOSTします。

認証

Authorizationヘッダーに、貴社のAPIキーをBearerトークンとして含めてください。

Authorization: Bearer your_api_key

リクエストボディ

記事の生のテキストと、リクエストの内容を記述した postData オブジェクトを含む JSON ボディを送信してください。

パラメータ 必須 タイプ 説明
text 必須 文字列 音声に変換する記事の全文。
postData 必須 物体 リクエストのメタデータ。以下のフィールドを参照してください。

postData オブジェクト

フィールド 必須 タイプ デフォルト 説明
name 必須 文字列 — 記事のタイトル。生成される音声リクエストのタイトルとして使用されます。
articleId 必須 文字列 — 記事の固有識別子です。これは冪等性キーとして機能し(後述の「冪等性」を参照)、コールバックでもそのまま返されます。
voiceId 必須 文字列 — ナレーションに使用する音声。IDは……から使用してください。 ボイスリスト. 会社の API キーの種類に合ったボイスを使ってください。標準キーは標準ボイス(voice_engine = standard)、アドバンスキーはアドバンスボイス(voice_engine = advanced)を使います。種類はキーの生成時に選びます。どちらの場合も、.srt ファイルのすべての文に単語ごとのタイミングが付きます。
callbackURL 必須 文字列 (URL) — Moknah が完了した音声および文字起こしのURLをPOST送信する先のHTTPS URLです。企業ごとに最新の値が保存されます。
preprocessType 任意 文字列 "0" テキストの準備モード:「0」は処理なし(原文のまま読み上げ)、「2」はアラビア語のタシュキール(AIが母音記号を付け、数字を文字で書き表します。文字数コストは2倍)です。文字列でも数値でも指定できます。「2」はアラビア語でのみ利用でき、AIに送られるのはアラビア語の文だけです。
language 任意 文字列 "auto" コンテンツの言語:「auto」または「ar」「en」などのISO 639-1コード。「auto」の場合、preprocessType「2」はテキストがアラビア語のときだけ使われます。それ以外の記事は「0」として読み上げられ、料金も1倍です。アラビア語以外の言語で「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 は以下のJSONボディを含むPOSTリクエストを、指定されたcallbackURLに送信します。

{
    "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 生成されたMP3ナレーションの公開URL。生成に失敗した場合はnull。
response.srtFile 同期された文字起こし(.srt)ファイルの公開URL。生成に失敗した場合はnull。
response.signature ペイロードが本物であることを検証するために使用できるHMAC-SHA256署名(下記を参照)。
失敗した生成を処理する

生成によって音声が作成されなかった場合もコールバックが送信されます。その際、response.audioFile および response.srtFile は null となります(署名には引き続き articleId|null|null が含まれます)。audioFile または srtFile が null であるコールバックは失敗として扱い、記事を完了状態にせず、regenerate を true に設定して再送信してください。

署名の検証

この署名は、APIキーのSHA-256ハッシュ値(16進数)をキーとして、文字列 `articleId|audioFile|srtFile` に対してHMAC-SHA256(16進数)を適用したものです。受信側で同様に署名を計算・比較することで、そのコールバックが 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」に設定されている場合、再生成(および再課金)を行うことなく、既存の音声がコールバックURLに再送付されます。
  • 既存の articleId に対して強制的に新規生成を行うには、regenerate を true に設定してください。
  • articleId の前回の試行が失敗した場合、もう一度送ると再生成されます。新しい articleId は不要です。

並行性とスループット

記事はキューから生成され、各クライアントに公平な割り当てがあります。多くの記事を一度に送信できます。すべて受け付けられ、数件ずつ生成され、完成した記事から順にコールバック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.