AITalk WebAPIサービス~WebAPI仕様書

仕様書
2016/02/01
改訂履歴
改訂日
改訂内容
2015/07/01
初版
2015/07/10
[音声合成 API]の[合成文字列]について補足
2015/11/04
[音声合成 API]の[単語辞書利用フラグ]について記載
2016/02/01
ver. 2.0 の仕様変更に伴う下記の変更
[WebAPI 基本仕様]の[リクエスト URL]を変更
[WebAPI 基本仕様]の[提供 WebAPI]を変更
[音声合成 API]の[パラメータ]を変更
[合成実績情報取得 API]の[パラメータ]を変更
[合成実績情報取得 API]の[レスポンスデータ]を変更
[対応話者一覧]の[外国語話者]を追記
[参考資料]を追記
1
All Rights Reserved. Copyright AI Inc,.
目次
改訂履歴 .................................................................................................................................. 1
1. WebAPI 基本仕様 ............................................................................................................... 3
1-1. 通信プロトコル ........................................................................................................... 3
1-2. リクエスト URL .......................................................................................................... 3
1-3. リクエスト/レスポンスフォーマット ....................................................................... 3
1-3-1. リクエストフォーマット ...................................................................................... 3
1-3-2. レスポンスフォーマット ...................................................................................... 3
1-4. 提供 WebAPI ............................................................................................................... 3
1-5. 出力の音声データ形式................................................................................................. 3
2. WebAPI 仕様 ....................................................................................................................... 4
2-1. ttsget.php/音声合成 API ........................................................................................... 4
2-1-1. パラメータ ............................................................................................................ 4
2-1-2. レスポンスデータ ................................................................................................. 5
2-2. ttscount.php/合成実績情報取得 ................................................................................ 5
2-2-1. パラメータ ............................................................................................................ 5
2-2-2. レスポンスデータ ................................................................................................. 6
3. 対応話者一覧 ...................................................................................................................... 7
3-1. 標準話者 ...................................................................................................................... 7
3-2. 関西弁話者 ................................................................................................................... 7
3-3. 外国語話者 ................................................................................................................... 8
4. エラーメッセージ ............................................................................................................... 9
4-1. エラーコード ............................................................................................................. 10
2
All Rights Reserved. Copyright AI Inc,.
1
WebAPI 基本仕様
1. WebAPI 基本仕様
1-1.
通信プロトコル
HTTP、HTTPS
1-2.
リクエスト URL
http://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
内容
読み上げを行いたい文字列を送信することで、音声合成デ
ータを取得する。
ttscount.php
合成実績情報取得
リクエスト時点の当月の合成実績情報を取得する。
リクエスト時は、リクエスト URL に上記 WebAPI 名を追記して利用する。
(例) http://webapi.aitalk.jp/webapi/v2/ttsget.php
1-5.
出力の音声データ形式
音声
ビット
サンプリング
ビット
データ形式
レート
レート
深度
ogg/vorbis
48kbps
22.05kHz
16bit
チャンネル数
2ch
補足
コンテナ:ogg
コーデック:vorbis
aac
48kbps
22.05kHz
16bit
2ch
wav
352kbps
22.05kHz
16bit
1ch
3
All Rights Reserved. Copyright AI Inc,.
2
WebAPI 仕様
2. WebAPI 仕様
2-1.
ttsget.php/音声合成 API
音声合成リクエストにより音声データを取得する。
2-1-1. パラメータ
パラメータ
パラメータ内容
必須
username
ユーザ名
○
password
パスワード
○
補足
1 リクエストあたりの合成文字列の上限は各プランに
準じたものとなる。
UTF-8 エンコード。
日本語の場合、SSML で文章中の音声効果を指定可
text
合成文字列
○
能。詳細は別紙「SSML リファレンス」を参照。
※合成した結果、①読みが一切存在しない場合 (例:
「?」など記号のみの場合)、②制御コードが含まれる
場合、③「< (小なり)」
「& (アンパサンド)」(いずれも
半角)が存在する場合は合成エラーとなる。
「3. 対応話者」に記載のspeaker_nameを指定。
speaker_name
話者名
○
存在しない話者や契約外話者を指定した場合、また未
指定の場合はエラーとなる。
ext
出力音声形式
volume
音量
speed
話速
pitch
ピッチ(声の高さ)
range
抑揚
(声の高さの範囲)
ogg、aac、wavの中から選択。省略時はogg。
日本語:範囲は0.01~2.00。省略時は1.00。
外国語:範囲は1~9。省略時は5。(※1)
日本語:範囲は0.50~4.00。省略時は1.00。
外国語:範囲は1~9。省略時は5。(※1)
日本語:範囲は0.50~2.00。省略時は1.00。
外国語:範囲は1~9。省略時は5。(※1)
範囲は0.00~2.00。省略時は1.00。日本語のみ対応。
単語辞書を利用する場合は1を指定。
use_wdic
単語辞書利用
パラメータをした場合、または1以外を指定した場合
フラグ
は、単語辞書を利用しない動作となる。
単語辞書の利用は、日本語の標準話者に限る。
(※1) 「参考資料. 合成 API の韻律パラメータ」を参照。
4
All Rights Reserved. Copyright AI Inc,.
2
WebAPI 仕様
2-1-2. レスポンスデータ
成功した場合、音声合成された音声データ(バイナリデータ)を返却する。
(http ステータス:200)
失敗した場合、
エラーメッセージを含む xml 形式のテキストデータを返却する。
(http ステータス:500)
エラーの詳細は、
「4 エラーメッセージ」を参照。
2-2.
ttscount.php/合成実績情報取得
リクエスト時点の当月の合成実績情報を取得する。
2-2-1. パラメータ
パラメータ
パラメータ内容
必須
username
ユーザ名
○
password
パスワード
○
補足
取得する実績の言語。
ja
:日本語
foreign:外国語
(複数言語を契約している場合は外国語の合計値)
en-gb :イギリス英語
en-us :アメリカ英語
zs-cn :中国語(北京語)
zs-hk :中国語(広東語)
type
言語
ko
:韓国語
es
:スペイン語
fr
:フランス語
de
:ドイツ語
pt
:ポルトガル語
it
:イタリア語
ru
:ロシア語
ar
:アラビア語
th
:タイ語
id
:インドネシア語
のいずれかを選択。省略時はja。
5
All Rights Reserved. Copyright AI Inc,.
2
WebAPI 仕様
2-2-2. レスポンスデータ
成功した場合、下記の合成実績情報を返却する。
(http ステータス:200)
失敗した場合、
エラーメッセージを含む xml 形式のテキストデータを返却する。
(http ステータス:500)
エラーの詳細は、
「4 エラーメッセージ」を参照。
タグ名
webapi
内容
詳細
ルートタグ
対象言語をname要素で返す。
yyyymm
対象年月
対象年月を yyyymm の形式で返す。
base_count
当月の基本合成数 (※1)
total_count
当月の総合成回数 (※1)
over_count (※2)
当月の超過合成数 (※1)
over_cost (※2)
当月の追加料金
over_flag (※2)
当月の超過状態
プランに応じた基本合成数。
フリープランの場合は0となる。
月が替わった時点で0にリセットされる。
基本合成数を超過した数。
月が替わった時点で0にリセットされる。
当月の超過合成数に対する追加料金。
月が替わった時点で0にリセットされる。
0:超過していない、0以外:超過している
月が替わった時点で0にリセットされる。
(※1) 単位は、文字数制限プランでの契約の場合は[文字]、リクエスト制限プランの契約の場合[リクエス
ト]となる。
(※2) 対象言語が ja の場合のみ表示される。
【出力サンプル】
日本語の月間基本合成数 500,000 文字を超過している例
<?xml version="1.0" encoding="UTF-8"?>
<webapi name="ja">
<yyyymm>201505</yyyymm>
<base_count>500000</base_count>
<total_count>25693</total_count>
<over_count>21562</over_count>
<over_cost>4312</over_cost>
<over_flag>1</over_flag>
</webapi>
6
All Rights Reserved. Copyright AI Inc,.
3
対応話者一覧
3. 対応話者一覧
本WebAPIで対応している話者は以下となる。
未対応の話者や契約外の話者を指定した場合は、合成エラーとなる。
3-1.
標準話者
話者名
性別
speaker_name
のぞみ
女
nozomi
すみれ
女
sumire
まき
女
maki
かほ
女
kaho
あかり
女
akari
ななこ
女
nanako
れいな
女
reina
せいじ
男
seiji
ひろし
男
hiroshi
おさむ
男
osamu
たいち
男
taichi
こうたろう
男
koutarou
あんず
女
anzu
ゆうと
男
yuuto
ちひろ
女
chihiro
3-2.
関西弁話者
話者名
性別
speaker_name
みやび
女
miyabi_west
やまと
男
yamato_west
7
All Rights Reserved. Copyright AI Inc,.
3
対応話者一覧
3-3. 外国語話者
言語
性別
speaker_name
イギリス英語
男
daniel
イギリス英語
女
serena
アメリカ英語
男
tom
アメリカ英語
女
samantha
アメリカ英語
女
allison
アメリカ英語
女
donna
アメリカ英語
女
jill
アメリカ英語
女
carol
北京語
男
haobo
北京語
女
wangjing
北京語
女
xiaokun
広東語
女
xiaojie
ロシア語
女
milena
フランス語
男
thomas
フランス語
男
sebastien
フランス語
女
audrey-ml
ドイツ語
男
yannick
ドイツ語
女
steffi
ドイツ語
女
anna
スペイン語
男
diego
スペイン語
女
monica
ポルトガル語
女
vera
ポルトガル語
女
joana
アラビア語
男
maged
韓国語
女
narae
イタリア語
女
alice-ml
タイ語
女
narisa
インドネシア語
女
damayanti
8
All Rights Reserved. Copyright AI Inc,.
4
エラーメッセージ
4. エラーメッセージ
各WebAPIエラー時は、下記フォーマットによりエラーメッセージが返却される。
タグ名
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-1.
エラーコード
エラーメッセージ中に記載されるエラーコードとその内容を記載する。
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,.