テキスト読み上げ (TTS)
テキストを自然な音声に変換する
AI音声合成を使用してテキストを音声に変換します。MP3音声ファイルを返します。
認証
AuthorizationヘッダーにAPIキーを含めてください。
リクエストボディ
| パラメータ | 必須 | タイプ | 説明 |
|---|---|---|---|
| text | 必須 | 文字列 | 変換するテキスト(最大1500文字) |
| output_format | 任意 | 文字列 | 希望する音声出力形式。codec_sampleRate_bitrate(例: mp3_22050_32)の形式で指定します。デフォルトは mp3_44100_128 です。完全なリストについては、以下の「出力形式」セクションを参照してください。 |
| voice_id | 必須 | 整数 | ~からの音声ID ボイスリスト. |
| prerecording | 任意 | 整数 | 1(基本の強化)、2(AIによる強化/アラビア語のタシュキール)、または3(AI詩人)。2と3はアラビア語のコンテンツでのみ利用可能です(言語設定をご確認ください)。 |
| language | 任意 | 文字列 | ISO 639-1コード(例:arやen)で指定するコンテンツ言語です(ar-JOのような地域コードも使用可能です)。この設定は利用可能な事前録音モードを決定するものであり、音声には送信されません。 モード2と3は、アラビア語(ar)でのみ利用可能です。言語が指定されていない場合、モード2と3はアラビア語を指すものとして扱われるため、既存のインテグレーションはそのまま動作します。それ以外の言語でモード2または3を指定した場合、あるいは不明なコードを指定した場合は、`details.language` に理由が示された状態で `400 INVALID_REQUEST` が返されます。 |
| voice_settings | 任意 | 文字列 (JSON) | 音声カスタマイズのオプション |
対応出力形式
output_format パラメータには、以下のいずれかの値を指定できます。
- MP3: mp3_22050_32, mp3_24000_48, mp3_44100_32, mp3_44100_64, mp3_44100_96, mp3_44100_128, mp3_44100_192
- PCM: pcm_8000, pcm_16000, pcm_22050, pcm_24000, pcm_32000, pcm_44100, pcm_48000
- 作品: opus_48000_32, opus_48000_64, opus_48000_96, opus_48000_128, opus_48000_192
- WAV: wav_16000, wav_22050, wav_24000, wav_44100, wav_48000 — エンジン出力そのままの 16 ビット モノラル WAV(ロスレス)。ストリーミング WebSocket では使えないため、pcm_* を使用してください。
このセクションは参照用であり、メインのリクエスト表を煩雑にすることなく、適切なフォーマットを選択できるようになっています。
エンジンとモード
各音声は2つのエンジンのいずれかに属しています。音声リストではその情報が `voice_engine` として返され、選択した音声によって適用される設定が決まります。
各 API キーは 1 つのエンジン用です。標準(既定)かアドバンスを、キーの作成時に選びます。キーは自分のエンジンのボイスだけを一覧表示・使用します。もう一方を使うには 2 つ目のキーを作成してください。
- 標準エンジン (
standard) — 速度、表現力、価格のバランスが異なる3つのモードを備えたスタジオ・ボイス。 - 高度なエンジン (
advanced, アルファ) — 文脈、設定、文体、そしてペースを伴い、平易な言葉で語られる、独自の「声」。そこには「モード(様式)」は適用されません。
標準エンジンモード
| モード | 名前 | クレジット | ~に最適 |
|---|---|---|---|
emotion デフォルト |
感情と方言 | ×1 | 感情や方言を伴う、高速かつ表現力豊かな音声。[laughing](笑い)や[whispering](ささやき)といった感情タグにも対応しています。 |
quality |
高品質な感情と方言 | ×2 | より豊かで自然な感情表現や方言に対応しています。生成には少し時間がかかります。感情タグも利用可能です。 |
studio |
スタジオ品質 | ×2 | すべての音声コントロールを備えた、クリアで安定したスタジオ品質のナレーション。感情タグは使用できません。 |
モードが指定されていないリクエストは、エモーションモードで実行されます。
音声設定オブジェクト
標準のエンジン音
| パラメータ | タイプ | 範囲 | デフォルト | 説明 |
|---|---|---|---|---|
| mode | 文字列 | emotion, quality, studio | emotion | 標準エンジンモード。品質およびスタジオ費用は2倍のクレジットとなります。上記の「エンジンとモード」を参照してください。 |
| temperature | 整数 | 0 – 100 | 25 | 音声の変動や表現力を制御します。値を低くすると、より安定した予測可能な音声になります。一方、値を高くすると、変化や自発性、創造的な言い回しが増します。 |
| voice_similarity | 整数 | 0 – 100 | 100 | 生成される音声が、選択したボイスプロファイルにどの程度忠実であるかを決定します。値を高くすると元の音声の個性が維持され、値を低くすると、音色や発音においてより大きな変化が許容されるようになります。 |
| speed | 浮かぶ | 0.7 – 1.2 | 1.0 | 話す速度を調整します。1.0未満の値にすると速度が遅くなり聞き取りやすくなりますが、1.0を超える値にすると話す速度が速くなります。 スタジオモードのみ。エモーションや品質には影響しません。 |
| enable_emotions 非推奨 | ブール値 | false / true | — | 互換性のために引き続き受け入れられますが、出力には影響しなくなりました。代わりに mode を使用してください。 |
| fast_mode 非推奨 | 整数 | 0, 1, or 2 | — | 互換性のために引き続き受け付けられますが、出力には影響しません。「emotion mode」がすでに高速なオプションとなっているためです。リアルタイムの音声処理には、ストリーミング・エンドポイントを使用してください。 |
EmotionモードおよびQualityモードでは、temperatureとvoice_similarityが音声制御パラメータとなります(範囲内の値がそのまま使用されます)。一方、speedはStudioモードでのみ適用されます。
高度なエンジンサウンド
| パラメータ | タイプ | 価値観 | 説明 |
|---|---|---|---|
| context | 文字列 | 最大500文字 | 最も強力な制御要素です。アクセント、感情、雰囲気、または目的を記述します(例:「レバント方言で語られる、温かみのあるドキュメンタリー」)。 |
| setting | 文字列 | 最大500文字 | シーンや雰囲気(例:「静かで親密な、深夜のスタジオ」) |
| style | 文字列 | neutral, warm, energetic, serious, cheerful, poetic | 全体的な伝え方のスタイル |
| pace | 文字列 | slow, normal, fast | 話すペース |
Advancedエンジンの音声は、モードやStandardエンジンのスライダー設定を無視し、要求されたoutput_formatで結果を返します。生成には、Standardエンジンよりも少し時間がかかる場合があります。
音声設定のルールと制約
- 未知のキー、無効なモード・スタイル・ペース、あるいは500文字を超えるコンテキストや設定は、400 INVALID_REQUESTとして拒否されます。
-
互換性を維持するため、非推奨の enable_emotions が true の場合、voice_settings に以下のフィールドを含めてはなりません。
speed,fast_mode.
料金
クレジット = 文字数 × (事前録音レート + ボイス料金 %) × モード倍率。倍率は quality と studio が ×2、emotion が ×1、Advanced エンジンの各ボイスが ×1.5 です。
例
curl -X POST "https://moknah.io/api/v1/tts/generate/" \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"text": "مرحبا بك في منصة مكنة",
"voice_id": 1,
"prerecording": 1,
"language": "ar",
"voice_settings": {
"mode": "emotion",
"speed": 1.0,
"temperature": 25
}
}' \
--output speech.mp3
# Advanced engine voice (voice_engine = "advanced")
curl -X POST "https://moknah.io/api/v1/tts/generate/" \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"text": "مرحبا بك في منصة مكنة",
"voice_id": 2,
"voice_settings": {
"context": "A warm documentary read in a Levantine dialect.",
"pace": "slow"
}
}' \
--output speech-advanced.mp3
import requests
response = requests.post(
"https://moknah.io/api/v1/tts/generate/",
headers={
"Authorization": "Bearer your_api_key",
"Content-Type": "application/json"
},
json={
"text": "مرحبا بك في منصة مكنة",
"voice_id": 1,
"prerecording": 1,
"language": "ar",
"voice_settings": {
"mode": "emotion",
"speed": 1.0,
"temperature": 25
}
}
)
with open("speech.mp3", "wb") as f:
f.write(response.content)
const response = await fetch(
'https://moknah.io/api/v1/tts/generate/',
{
method: 'POST',
headers: {
'Authorization': 'Bearer your_api_key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
text: 'مرحبا بك في منصة مكنة',
voice_id: 1,
prerecording: 1,
language: 'ar',
voice_settings: {
mode: 'emotion',
speed: 1.0,
temperature: 25
}
})
}
);
const blob = await response.blob();
// Save or play the audio
回答
以下のヘッダーを伴い、要求された output_format(デフォルトは MP3)でバイナリオーディオデータを返します。
| ヘッダー | 説明 |
|---|---|
Content-Type |
output_format は、mp3_* では audio/mpeg、opus_* (Ogg/Opus) では audio/ogg、pcm_* (raw 16-bit little-endian、ヘッダーなし) では audio/pcm;rate=N;channels=1 となります。 |
エラー
| ステータス | コード | 説明 |
|---|---|---|
400 |
INVALID_REQUEST | 無効なパラメータ(不明なモード、スタイル、またはペースを含む) |
401 |
UNAUTHORIZED | 無効なAPIキー |
402 |
INSUFFICIENT_CREDITS | クレジットが不足しています |
429 |
RATE_LIMIT_EXCEEDED | リクエストが多すぎます |
APIに関するご質問や問題については、こちらまでお問い合わせください。 api@moknah.io.