AITalk WebAPIサービス～WebAPI仕様書

(1)

WebAPI 仕様書

バージョン2 系列

(2)

1

改訂履歴

改訂日改訂内容 2016/02/01 初版 2016/05/09 ・[音声合成 API]の[リクエストパラメータ]に [合成文字列種別]と[出力データタイプ]を追加 2016/06/20 ・感情対応話者を4 話者追加・[音声合成 API]の[リクエストパラメータ]に [wav フォーマット]、[感情パラメータ]を追加・[音声合成 API]の[リクエストパラメータ]の

[出力音声形式]の有効値(wav8, wav16, wav22, wav44, alaw, ulaw)を追加 2016/12/14 ・[音声合成 API]の[リクエストパラメータ]の

[出力音声形式]の有効値(wav11, wav8k-8b, wav11k-8b)を追加

(3)

2

改訂履歴 ... 1 1. WebAPI 基本仕様... 3 通信プロトコル ... 3 1-1. リクエスト URL ... 3 1-2. リクエスト／レスポンスフォーマット ... 3 1-3. リクエストフォーマット ... 3 1-3-1. レスポンスフォーマット ... 3 1-3-2. 提供 WebAPI ... 3 1-4. 出力の音声データ形式 ... 4 1-5. 2. WebAPI 仕様 ... 5 ttsget.php／音声合成 API ... 5 2-1. リクエストパラメータ ... 5 2-1-1. レスポンスデータ ... 8 2-1-2. ttscount.php／合成実績情報取得 ... 9 2-2. リクエストパラメータ ... 9 2-2-1. レスポンスデータ ... 9 2-2-2. 3. 対応話者一覧 ... 10 標準話者 ... 10 3-1. 関西弁話者 ... 10 3-2. 4. エラーメッセージ ... 11 エラーフォーマット ... 11 4-1. エラーコード ... 12 4-2.

(4)

3

1. WebAPI 基本仕様

通信プロトコル

1-1.

HTTP、HTTPS

リクエスト URL

1-2.

webapi.aitalk.jp/webapi/v2/

リクエスト／レスポンスフォーマット

1-3.

リクエストフォーマット 1-3-1. HTTP POST、または HTTP GET フォーマットで行う。 レスポンスフォーマット 1-3-2. WebAPI 成功時は、各 WebAPI 仕様に則る。 WebAPI 失敗時は、XML 形式のテキストデータでエラーが返却される。

提供 WebAPI

1-4.

WebAPI 名メソッド名内容 ttsget.php 音声合成API 読み上げを行いたい文字列を送信することで、音声合成データやAI 中間言語(※1)を取得する。 ttscount.php 合成実績情報取得リクエスト時点の合成実績情報を取得する。 (※1) AI 中間言語は日本語解析に限る。リクエスト時は、リクエストURL に上記 WebAPI 名を追記して利用する。 (例) http://webapi.aitalk.jp/webapi/v2/ttsget.php https://webapi.aitalk.jp/webapi/v2/ttsget.php (HTTPS の場合)

(5)

1 WebAPI 基本仕様

4

出力の音声データ形式

1-5.

音声データ形式ビットレートサンプリングレートビット深度チャンネル数補足

ogg/vorbis 48kbps 22.05kHz 16bit 2ch コンテナ：ogg

コーデック：vorbis aac 48kbps 22.05kHz 16bit 2ch mp3 48kbps 22.05kHz 16bit 2ch wav 352kbps 22.05kHz 16bit 1ch [補足 1]参照 μ-law 64kbps 8kHz 8bit 1ch A-law 64kbps 8kHz 8bit 1ch [補足 1] 記載のwav 形式はデフォルトのものとなる。後述のリクエストパラメータにて、ext パラメータ、wav_format パラメータを指定した場合は、指定した形式に準じた音声データ形式となる。

(6)

5

2. WebAPI 仕様

ttsget.php／音声合成 API

2-1.

音声合成リクエストにより音声データやAI 中間言語等を取得する。 リクエストパラメータ 2-1-1. パラメータパラメータ内容必須補足 username ユーザ名 ○ password パスワード ○ text 合成文字列 ○ UTF-8 エンコード。 SSML で文章中の音声効果を指定可能。詳細は別紙「SSML リファレンス」を参照。 1 リクエストあたりの文字数の上限は、契約プランに準じる。上限数には、SSML タグを除いた文字数と、タグを含めた文字数の2 種類がある。詳細は、管理画面を参照。 SSML を利用する場合、後述の注意事項を参照。 speaker_name 話者名 ○ 「3.対応話者一覧」のspeaker_nameを指定。存在しない話者を指定した場合、また未指定の場合はエラーとなる。 SSMLを利用する場合、カスタム話者を利用する場合は後述の注意事項を参照。 input_type 合成文字種別 ssml：合成文字列（text）にSSMLを指定可能 text：合成文字列（text）にSSMLを指定不可省略時はssml。 volume 音量範囲は0.01～2.00。省略時は1.00。 speed 話速範囲は0.50～4.00。省略時は1.00。 pitch ピッチ(声の高さ) 範囲は0.50～2.00。省略時は1.00。 range 抑揚 (声の高さの範囲) 範囲は0.00～2.00。省略時は1.00。

(7)

2 WebAPI 仕様

6

パラメータパラメータ内容必須補足 use_wdic 単語辞書利用フラグ 1：単語辞書を利用する 1以外：単語辞書を利用しない ※関西弁話者に対する単語辞書の利用は不可。 output_type 出力データタイプ sound：音声を出力 kana：UTF-8エンコードのAI中間言語を出力 jeita：CP932エンコードのJEITA TT-6004を出力省略時はsound。 ext 出力音声形式後述の「①extパラメータについて」を参照。 output_typeパラメータがkanaかjeitaの場合は無効。省略時はogg。 wav_format wavフォーマット wav形式にて任意のフォーマットとする場合に指定。 JSON形式で指定する。後述の「②wav_formatパラメータについて」を参照。 extパラメータにてwavを指定した時のみ有効。 style 感情パラメータ感情表現を行う場合に指定。 JSON形式で指定する。後述の「③styleパラメータについて」を参照。感情パラメータは感情話者指定時にのみ有効。対応話者の詳細は「3 対応話者一覧」を参照。【SSML を利用する場合の注意】 ①一回のリクエスト内で、標準話者、関西弁話者、カスタム話者(※1)を voice タグにて相互に切り替えることはできません。voice タグを利用する場合は、標準話者のみ、関西弁話者のみ、カスタム話者のみでの切り替えとしてください。 (※1)別途カスタム話者の利用契約を行っている場合のみカスタム話者の利用が行えます。 ②voice タグにてカスタム話者を利用する場合は、利用するカスタム話者のうち 1 名分を話者名パラメータに指定してください。 voice タグでカスタム話者を指定して、同パラメータに標準話者や関西弁話者を指定した場合、カスタム話者に切り替わらないことがあります。【カスタム話者を利用する場合】 ①カスタム話者を利用する場合は、話者パスワードパラメータ「speaker_pass」の指定が必要になる場合があります。カスタム話者の利用契約を行った際に、話者名と合わせて別途ご連絡いたします。

(8)

7

All Rights Reserved. Copyright AI Inc,. ①ext パラメータについてパラメータ値補足 ogg ogg/vorbis 形式の音声データを返却 aac aac 形式の音声データを返却 mp3 mp3 形式の音声データを返却 wav サンプリングレート：22.05kHz、ビット深度：16bit、チャンネル数：1ch wav 形式の音声データを返却 ※wav_format パラメータを指定した時は指定した形式に準ずる。 wav8 サンプリングレート：8kHz、ビット深度：16bit、チャンネル数：1ch wav 形式の音声データを返却 wav8k-8b サンプリングレート：8kHz、ビット深度：8bit、チャンネル数：1ch wav 形式の音声データを返却 wav11 サンプリングレート：11kHz、ビット深度：16bit、チャンネル数：1ch wav 形式の音声データを返却 wav11k-8b サンプリングレート：11kHz、ビット深度：8bit、チャンネル数：1ch wav 形式の音声データを返却 wav16 サンプリングレート：16kHz、ビット深度：16bit、チャンネル数：1ch wav 形式の音声データを返却 wav22 サンプリングレート：22.05kHz、ビット深度：16bit、チャンネル数：1ch wav 形式の音声データを返却 wav44 サンプリングレート：44.1kHz、ビット深度：16bit、チャンネル数：1ch wav 形式の音声データを返却 alaw A-law 形式の音声データを返却 ulaw μ-law 形式の音声データを返却 ②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 エンコードを行うこと。

(9)

2 WebAPI 仕様

8

All Rights Reserved. Copyright AI Inc,. ③style パラメータについて感情に対応した話者に限り、対応している感情パラメータのみ有効となる。但し全パラメータの合計上限値は1.0となること。有効な値は以下となり、これらをJSON形式で指定すること。範囲外の値を指定した場合は未指定時の挙動となる。パラメータ値説明有効な値 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&speaker_name=nozomi& 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 に指定する値は契約時に通知されたものを指定すること・speaker_name には利用したい話者名を指定すること・text に指定する値は UTF-8 エンコードとすること

・POST メソッドの場合、URL パラメータで指定している内容を BODY として送信すること レスポンスデータ 2-1-2. 成功時：音声合成された音声データ（バイナリデータ）を返却する。（HTTP ステータス：200）失敗時：エラーメッセージを含むxml 形式のテキストデータを返却する。（HTTP ステータス：500）エラーの詳細は、「4.エラーメッセージ」を参照。合成した結果、下記に該当する場合は合成エラーとなる。 ①合成文字列に読みが存在しない場合（例：「？」など読みがない記号のみの場合） ②合成文字列中に制御コードが含まれる場合 ③合成文字種別がssml で、合成文字列中が SSML 構文に則っていない場合 ④合成文字種別がssml で、合成文字列中に「&」（半角アンパサンド）や「<」（半角小なり）が含まれる場合なお、④は全角文字として入力することで回避可能である。

(10)

9

ttscount.php／合成実績情報取得

2-2.

リクエスト時点の合成実績情報を取得する。 リクエストパラメータ 2-2-1. パラメータパラメータ内容必須補足 username ユーザ名 ○ password パスワード ○ レスポンスデータ 2-2-2. 成功時：下記の合成実績情報を返却。（HTTP ステータス：200）失敗時：エラーメッセージを含むxml 形式のテキストデータを返却。（HTTP ステータス：500）エラーの詳細は、「4.エラーメッセージ」を参照。タグ名内容詳細 webapi ルートタグ対象言語をname要素で返す。 base_date 集計基準日集計基準日をyyyymmdd の形式で返す base_count 基本合成数 (※1) プランに応じた基本合成数フリープランの場合は0となる。 total_count 総合成数 (※1) 総合成回数 over_count 超過合成数 (※1) 基本合成数を超過した数 over_cost 追加料金 (※1) 超過合成数に対する追加料金 over_flag 超過状態 (※1) 0：超過していない 1：超過している (※1) 契約開始日を基点とし、契約プランで定められた単位月経過ごとに 0 にリセットされる。【出力サンプル】月間基本合成数500,000 文字を超過している例 <?xml version="1.0" encoding="UTF-8"?> <webapi name="ja">

<base_date>20160509</base_date> <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>

(11)

3 対応話者一覧

10

3. 対応話者一覧

本WebAPIで対応している話者は以下となる。未対応の話者を指定した場合や未指定の場合は、合成エラーとなる。

標準話者

3-1.

話者名性別 speaker_name のぞみ女性 nozomi すみれ女性 sumire まき女性 maki かほ女性 kaho あかり女性 akari ななこ女性 nanako れいな女性 reina 話者名性別 speaker_name せいじ男性 seiji ひろし男性 hiroshi おさむ男性 osamu たいち男性 taichi こうたろう男性 koutarou あんず女性 anzu ゆうと男性 yuuto ちひろ女性 chihiro 話者名性別 speaker_name 対応感情のぞみ (感情対応) 女性 nozomi_emo 喜、悲、怒まき (感情対応) 女性 maki_emo 喜、悲、怒れいな (感情対応) 女性 reina_emo 喜たいち (感情対応) 男性 taichi_emo 喜

関西弁話者

3-2.

話者名性別 speaker_name みやび女性 miyabi_west やまと男性 yamato_west 【カスタム話者について】別途カスタム話者の利用契約を行っている場合のみカスタム話者の利用が可能です。カスタム話者の情報は利用契約を行った際に別途ご連絡いたします。

(12)

11

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>

(13)

4 エラーメッセージ

12

エラーコード

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 データ送出エラー