記事の音声化(ATS)
記事全文を音声と文字起こしに変換し、コールバックURLへ非同期で配信します。
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@moknah.io.