WebAPI 仕様書
目次
目次 ......................................................................................................................................... 1
1. WebAPI 基本仕様 ............................................................................................................... 2
1-1. 通信プロトコル ........................................................................................................... 2
1-2. リクエスト URL .......................................................................................................... 2
1-3. リクエスト／レスポンスフォーマット ....................................................................... 2
1-3-1. リクエストフォーマット ...................................................................................... 2
1-3-2. レスポンスフォーマット ...................................................................................... 2
1-4. 提供 WebAPI ............................................................................................................... 2
1-5. 出力の音声データ形式................................................................................................. 3
2. WebAPI 仕様 ....................................................................................................................... 4
2-1. ttsget.php／音声合成 API ........................................................................................... 4
2-1-1. リクエストパラメータ .......................................................................................... 4
2-1-2. レスポンスデータ ................................................................................................. 7
3. 対応話者一覧 ...................................................................................................................... 8
3-1. 標準話者 ...................................................................................................................... 8
3-2. 関西弁話者 ................................................................................................................... 8
3-3. 感情対応話者 ............................................................................................................... 8
3-4. カスタム話者（ハッカソン特別提供） ....................................................................... 8
4. エラーメッセージ ............................................................................................................... 9
4-1. エラーフォーマット .................................................................................................... 9
4-2. エラーコード ............................................................................................................. 10
1
All Rights Reserved. Copyright AI Inc,.
1
WebAPI 基本仕様
1. WebAPI 基本仕様
1-1.
通信プロトコル
HTTP、HTTPS
1-2.
リクエスト URL
webapi.aitalk.jp/webapi/v2/
1-3.
リクエスト／レスポンスフォーマット
1-3-1. リクエストフォーマット
HTTP POST、または HTTP GET フォーマットで行う。
1-3-2. レスポンスフォーマット
WebAPI 成功時は、各 WebAPI 仕様に則る。
WebAPI 失敗時は、XML 形式のテキストデータでエラーが返却される。
1-4.
提供 WebAPI
WebAPI 名
ttsget.php
メソッド名
音声合成 API
内容
読み上げを行いたい文字列を送信することで、音声合成データ
や AI 中間言語等を取得する。
リクエスト時は、リクエスト URL に上記 WebAPI 名を追記して利用する。
(例) http://webapi.aitalk.jp/webapi/v2/ttsget.php
2
All Rights Reserved. Copyright AI Inc,.
1
WebAPI 基本仕様
1-5.
出力の音声データ形式
音声
ビット
サンプリング
ビット
データ形式
レート
レート
深度
ogg/vorbis
48kbps
22.05kHz
16bit
チャンネル数
2ch
補足
コンテナ：ogg
コーデック：vorbis
aac
48kbps
22.05kHz
16bit
2ch
wav
352kbps
22.05kHz
16bit
1ch
μ-law
64kbps
8kHz
8bit
1ch
A-law
64kbps
8kHz
8bit
1ch
[補足 1]参照
[補足 1]
記載の wav 形式はデフォルトのものとなる。
後述のリクエストパラメータにて、ext パラメータ、wav_format パラメータを指定した場合は、指定し
た形式に準じた音声データ形式となる。
3
All Rights Reserved. Copyright AI Inc,.
2
WebAPI 仕様
2. WebAPI 仕様
2-1.
ttsget.php／音声合成 API
音声合成リクエストにより音声データや AI 中間言語等を取得する。
2-1-1. リクエストパラメータ
パラメータ
パラメータ内容
必須
補足
username
ユーザ名
○
Mashup Awards12専用「MA12_WebAPI」を指定。
password
パスワード
○
Mashup Awards12専用「TNLPXb9d」を指定。
UTF-8 エンコード。
SSML で文章中の音声効果を指定可能。詳細は別紙
「SSML リファレンス」を参照。
text
合成文字列
○
1 リクエストあたりの文字数の上限は、契約プランに
準じる。上限数には、SSML タグを除いた文字数と、
タグを含めた文字数の 2 種類がある。詳細は、管理画
面を参照。
「3.対応話者一覧」のspeaker_nameを指定。
speaker_name
話者名
○
存在しない話者を指定した場合、また未指定の場合は
エラーとなる。
ssml：合成文字列（text）にSSMLを指定可能
input_type
合成文字種別
text：合成文字列（text）にSSMLを指定不可
省略時はssml。
volume
音量
範囲は0.01～2.00。省略時は1.00。
speed
話速
範囲は0.50～4.00。省略時は1.00。
pitch
range
ピッチ
(声の高さ)
抑揚
(声の高さの範囲)
範囲は0.50～2.00。省略時は1.00。
範囲は0.00～2.00。省略時は1.00。
（次頁へ続く）
4
All Rights Reserved. Copyright AI Inc,.
2
WebAPI 仕様
（前頁からの続き）
パラメータ
use_wdic
パラメータ内容
必須
単語辞書利用
フラグ
補足
1：単語辞書を利用する
1以外：単語辞書を利用しない
単語辞書の反映は標準話者、感情対応話者に限る。
sound：音声を出力
output_type
出力データタイプ
kana：UTF-8エンコードのAI中間言語を出力
jeita：CP932エンコードのJEITA TT-6004を出力
省略時はsound。
後述の「①extパラメータについて」を参照。
ext
出力音声形式
output_typeパラメータがkanaかjeitaの場合は無効。
省略時はogg。
wav形式にて任意のフォーマットとする場合に指定。
wav_format
wavフォーマット
後述の「②wav_formatパラメータについて」を参照。
extパラメータにてwavを指定した時のみ有効。
感情表現を行う場合に指定。
style
感情パラメータ
後述の「③styleパラメータについて」を参照。
感情パラメータは感情話者指定時にのみ有効。
対応話者の詳細は「3 対応話者一覧」を参照。
①ext パラメータについて
パラメータ値
補足
ogg
ogg/vorbis 形式の音声データを返却
aac
aac 形式の音声データを返却
wav
サンプリングレート：22.05kHz、ビット深度：16bit、チャンネル数：1ch
wav 形式の音声データを返却
※wav_format パラメータを指定した時は指定した形式に準ずる。
wav8
サンプリングレート：8kHz、ビット深度：16bit、チャンネル数：1ch
wav 形式の音声データを返却
wav16
サンプリングレート：16kHz、ビット深度：16bit、チャンネル数：1ch
wav 形式の音声データを返却
wav22
サンプリングレート：22.05kHz、ビット深度：16bit、チャンネル数：1ch
wav 形式の音声データを返却
wav44
サンプリングレート：44.1kHz、ビット深度：16bit、チャンネル数：1ch
wav 形式の音声データを返却
alaw
A-law 形式の音声データを返却
ulaw
μ-law 形式の音声データを返却
5
All Rights Reserved. Copyright AI Inc,.
2
WebAPI 仕様
②wav_format パラメータについて
ビットレート、ビット深度、チャンネル数を JSON 形式で指定することで、既定以外の wav 形式の音声
データを返却可能。有効な値は以下となる。有効な値以外を指定した場合はエラーとなる。
パラメータ値
説明
有効な値
rate
サンプリングレート
8000, 11025, 16000, 22050*, 24000, 32000, 44100, 48000
bit
ビット深度
8, 16*
channels
チャンネル数
1*, 2
*印がついた値はデフォルト値を示す
(記載例)
{"rate":"16000","bit":"16","channels":"2"}
※URL パラメータとして渡す場合は、URL エンコードを行うこと。
③style パラメータについて
感情に対応した話者に限り、対応している感情パラメータのみ有効となる。
但し全パラメータの合計上限値は1.0となること。
有効な値は以下となる。範囲外の値を指定した場合は未指定時の挙動となる。
パラメータ値
説明
有効な値
j
喜び(joy)パラメータ
0.0～1.0。省略時は 0.0。
s
悲しみ(sadness)パラメータ
0.0～1.0。省略時は 0.0。
a
怒り(anger)パラメータ
0.0～1.0。省略時は 0.0。
(記載例)
{"j":"1.0"}
{"j":"0.5","s":"0.2","a":"0.3"}
※URL パラメータとして渡す場合は、URL エンコードを行うこと。
【呼び出しサンプル】
■GET メソッドの場合
http://webapi.aitalk.jp/webapi/v2/ttsget.php?username=xxxxx&password=xxxxx&text=%E4%BB%8A%E6%97
%A5%E3%81%AF%E3%81%84%E3%81%84%E5%A4%A9%E6%B0%97%E3%81%A7%E3%81%99%E3%81%AD%E3%80%82
※注釈
・username と password に指定する値は契約時に通知されたものを指定すること
・text に指定する値は UTF-8 エンコードとすること
・POST メソッドの場合、URL パラメータで指定している内容を BODY として送信すること
6
All Rights Reserved. Copyright AI Inc,.
2
WebAPI 仕様
2-1-2. レスポンスデータ
成功した場合、音声合成された音声データ（バイナリデータ）を返却する。
（http ステータス：200）
失敗した場合、
エラーメッセージを含む xml 形式のテキストデータを返却する。
（http ステータス：500）
エラーの詳細は、
「4.エラーメッセージ」を参照。
合成した結果、下記に該当する場合は合成エラーとなる。
①合成文字列に読みが存在しない場合（例：
「？」など読みがない記号のみの場合）
②合成文字列中に制御コードが含まれる場合
③合成文字種別が ssml で、合成文字列中が SSML 構文に則っていない場合
④合成文字種別が ssml で、合成文字列中に「&」
（半角アンパサンド）や「<」（半角小なり）が
含まれる場合
なお、④は全角文字として入力することで回避可能である。
7
All Rights Reserved. Copyright AI Inc,.
3
対応話者一覧
3. 対応話者一覧
本WebAPIで対応している話者は以下となる。
未対応の話者を指定した場合や未指定の場合は、合成エラーとなる。
3-1.
3-2.
標準話者
話者名
性別
speaker_name
話者名
性別
speaker_name
のぞみ
女
nozomi
せいじ
男
seiji
すみれ
女
sumire
ひろし
男
hiroshi
まき
女
maki
おさむ
男
osamu
かほ
女
kaho
たいち
男
taichi
あかり
女
akari
こうたろう
男
koutarou
ななこ
女
nanako
あんず
女
anzu
れいな
女
reina
ゆうと
男
yuuto
ちひろ
女
chihiro
関西弁話者
話者名
性別
speaker_name
みやび
女
miyabi_west
やまと
男
yamato_west
3-3.
感情対応話者
話者名
性別
speaker_name
対応感情
のぞみ（感情）
女
nozomi_emo
喜、悲、怒
まき（感情）
女
maki_emo
喜、悲、怒
れいな（感情）
女
reina_emo
喜
たいち（感情）
男
taichi_emo
喜
3-4.
カスタム話者（ハッカソン特別提供）
話者名
性別
speaker_name
琴葉 葵
女
aoi
琴葉 茜
女
akane_west
8
All Rights Reserved. Copyright AI Inc,.
4
エラーメッセージ
4. エラーメッセージ
各WebAPIエラー時は、下記フォーマットによりエラーメッセージが返却される。
4-1.
エラーフォーマット
タグ名
webapi
内容
補足
ルートタグ
code
エラーコード
message
エラーメッセージ
detail
エラー詳細
詳細は後述。
システム出力によるエラー詳細。
本項目は記載されていない場合がある。
【エラーサンプル】
<?xml version="1.0" encoding="UTF-8"?>
<webapi>
<code>1101</code>
<message>failed authentication</message>
<detail>CheckParam error</detail>
</webapi>
9
All Rights Reserved. Copyright AI Inc,.
4
エラーメッセージ
4-2.
エラーコード
エラーメッセージ中に記載されるエラーコードとその内容を記載する。
code
message
説明
1001
not exist user
存在しない話者を指定
1002
password is not correct
誤ったパスワード指定
1003
parameter error
パラメーターエラー
1004
not exist sound file
存在しないサウンドファイルを指定
1005
tts string length over
合成文字列が 1 回の合成可能文字数を超過
1101
failed authentication
認証失敗
1102
not accommodate contract term
契約期間外
1103
tts length over
月間合成文字数が基本文字数をオーバー
1201
failed select tts server
合成サーバ選択エラー
1202
failed TTS
合成エラー
1203
failed exec query
SQL 実行エラー
1204
failed send data by http
データ送出エラー
9999
other error
上記に当てはまらないエラー
10
All Rights Reserved. Copyright AI Inc,.
© Copyright 2024 Paperzz
