WebAPI 仕様書
バージョン 2 系列

2017/05/24

改訂履歴改訂日

改訂内容

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)を追加

2017/05/24

・[音声合成 API]の[リクエストパラメータ]の[出力音声形式]の有効値(mp3)を追加

1

All Rights Reserved. Copyright AI Inc,.

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

All Rights Reserved. Copyright AI Inc,.

1WebAPI 基本仕様

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

ttscount.php

合成実績情報取得

内容
読み上げを行いたい文字列を送信することで、音声合成データや AI 中間言語(※1)を取得する。
リクエスト時点の合成実績情報を取得する。

(※1) AI 中間言語は日本語解析に限る。
リクエスト時は、リクエスト URL に上記 WebAPI 名を追記して利用する。
(例)
http://webapi.aitalk.jp/webapi/v2/ttsget.php
https://webapi.aitalk.jp/webapi/v2/ttsget.php (HTTPS の場合)

3

All Rights Reserved. Copyright AI Inc,.

1

WebAPI 基本仕様

1-5.

出力の音声データ形式
音声ビット

サンプリングビット

データ形式

レート

レート

深度

48kbps22.05kHz

16bit

ogg/vorbis

チャンネル数2ch

補足コンテナ：ogg
コーデック：vorbis

aac

48kbps22.05kHz

16bit

2ch

mp3

48kbps22.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 パラメータを指定した場合は、指定した形式に準じた音声データ形式となる。

4

All Rights Reserved. Copyright AI Inc,.

2

WebAPI 仕様

2. WebAPI 仕様

2-1.

ttsget.php／音声合成 API

音声合成リクエストにより音声データや AI 中間言語等を取得する。
2-1-1. リクエストパラメータ
パラメータ

パラメータ内容

必須username

ユーザ名○password

パスワード

○

補足

UTF-8 エンコード。
SSML で文章中の音声効果を指定可能。詳細は別紙「SSML リファレンス」を参照。
text

合成文字列

○

1 リクエストあたりの文字数の上限は、契約プランに準じる。上限数には、SSML タグを除いた文字数と、タグを含めた文字数の 2 種類がある。詳細は、管理画面を参照。
SSML を利用する場合、後述の注意事項を参照。
「3.対応話者一覧」のspeaker_nameを指定。
存在しない話者を指定した場合、また未指定の場合はspeaker_name

話者名○

エラーとなる。
SSMLを利用する場合、カスタム話者を利用する場合は後述の注意事項を参照。
ssml：合成文字列（text）にSSMLを指定可能

input_type

合成文字種別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。

5

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フォーマット

JSON形式で指定する。
後述の「②wav_formatパラメータについて」を参照。
extパラメータにてwavを指定した時のみ有効。
感情表現を行う場合に指定。
JSON形式で指定する。

style感情パラメータ

後述の「③styleパラメータについて」を参照。
感情パラメータは感情話者指定時にのみ有効。
対応話者の詳細は「3 対応話者一覧」を参照。

【SSML を利用する場合の注意】①一回のリクエスト内で、標準話者、関西弁話者、カスタム話者(※1)を voice タグにて相互に切り替えることはできません。voice タグを利用する場合は、標準話者のみ、関西弁話者のみ、カスタム話者のみでの切り替えとしてください。
(※1)別途カスタム話者の利用契約を行っている場合のみカスタム話者の利用が行えます。
②voice タグにてカスタム話者を利用する場合は、利用するカスタム話者のうち 1 名分を話者名パラメータに指定してください。
voice タグでカスタム話者を指定して、同パラメータに標準話者や関西弁話者を指定した場合、カスタム話者に切り替わらないことがあります。
【カスタム話者を利用する場合】①カスタム話者を利用する場合は、話者パスワードパラメータ「speaker_pass」の指定が必要になる場合があります。カスタム話者の利用契約を行った際に、話者名と合わせて別途ご連絡いたします。

6

All Rights Reserved. Copyright AI Inc,.

2

WebAPI 仕様①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 エンコードを行うこと。

7

All Rights Reserved. Copyright AI Inc,.

2

WebAPI 仕様③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 で、合成文字列中に「&」（半角アンパサンド）や「<」（半角小なり）が含まれる場合
なお、④は全角文字として入力することで回避可能である。
8

All Rights Reserved. Copyright AI Inc,.

2

WebAPI 仕様

2-2.

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

リクエスト時点の合成実績情報を取得する。
2-2-1. リクエストパラメータ
パラメータ

パラメータ内容

必須username

ユーザ名○password

パスワード

○

補足

2-2-2. レスポンスデータ
成功時：下記の合成実績情報を返却。（HTTP ステータス：200）
失敗時：エラーメッセージを含む xml 形式のテキストデータを返却。（HTTP ステータス：500）
エラーの詳細は、「4.エラーメッセージ」を参照。
タグ名
webapi

内容詳細

ルートタグ

対象言語をname要素で返す。

base_date

集計基準日

集計基準日を yyyymmdd の形式で返す

base_count

基本合成数 (※1)

total_count

総合成数 (※1)

総合成回数

over_count

超過合成数 (※1)

基本合成数を超過した数

over_cost

追加料金 (※1)

超過合成数に対する追加料金

over_flag

超過状態 (※1)

プランに応じた基本合成数
フリープランの場合は0となる。

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>

9

All Rights Reserved. Copyright AI Inc,.

3 対応話者一覧

3. 対応話者一覧

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

3-1.

標準話者
性別

speaker_name性別

speaker_name

のぞみ

女性

nozomi

せいじ

男性

seiji

すみれ

女性

sumireひろし

男性hiroshi

まき女性

maki

おさむ

男性

osamu

かほ

女性

kaho

たいち

男性

taichi

あかり

女性

akari

こうたろう

男性

koutarou

ななこ

女性nanako

あんず女性

anzu

れいな

女性

reina

ゆうと男性yuuto

ちひろ

女性

chihiro

話者名

話者名

話者名

性別

speaker_name

対応感情

のぞみ (感情対応)

女性nozomi_emo

喜、悲、怒

まき (感情対応)

女性maki_emo

喜、悲、怒

れいな (感情対応)

女性reina_emo

喜

たいち (感情対応)

男性

taichi_emo

喜

3-2.

関西弁話者
性別

speaker_name

みやび

女性

miyabi_west

やまと

男性

yamato_west

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

10

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>

11

All Rights Reserved. Copyright AI Inc,.

4 エラーメッセージ

4-2.

エラーコード

エラーメッセージ中に記載されるエラーコードとその内容を記載する。
codemessage

説明

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

上記に当てはまらないエラー

12

All Rights Reserved. Copyright AI Inc,.