Reference
I/O specifications of each API of COTOHA API are described.
- Get an Access Token
- API Reference
-
- Parsing
- Named Entity Extraction
- Company Name Normalization
- Reference Resolution
- Keyword Extraction
- Similarity Calculation
- Sentence Type Classification
- User Attribute Estimation (β)
- Filler Removal (β)
- Detect Misrecognition (β)
- Sentiment Analysis
- Speech-to-Text
- Text-to-Speech
- Summarization
- Text Classification
- List of Error Code
- Release Notes
Parsing
Parsing API receives the sentence written in Japanese as an input, parse and output its sentence structure. The input sentence is broken down into clause and morpheme, semantic relationship between clauses, dependency relationship between morphemes, and semantic information such as parts of speech information, etc.
Request
HTTP Endpoint
Request Header
Key Name | Description |
---|---|
Content-Type |
application/json;charset=UTF-8 |
Authorization |
Bearer [Access Token] |
Request Body
Key Name | Data Type | Required | Description |
---|---|---|---|
sentence |
string |
Required |
sentence to be analyzed |
type |
string |
Optional |
You can choose one from the following (default: default) default - normal sentence kuzure - Sentence contains 'word lengthening' often found in SNSs |
dic_type |
array |
Optional |
Specify technical term dictionaries. Choose from ther below.(only for Enterprise user) IT - Computer,information,communication automobile - Automobile chemistry - Chemical and Petroleum Industries company - Company Name construction - Civil engineering and construction economy - Economy and laws and regulations energy - Electric power and energy institution - Organizations machinery - Machinery medical - Medical metal - Metal |
Request Sample (cURL)
$ curl -X POST -H "Content-Type:application/json;charset=UTF-8" -H "Authorization:Bearer [Access Token]" -d '{"sentence":"犬は歩く。","type": "default"}' "[API Base URL]/nlp/v1/parse"
Response
Response
Key Name | Data Type | Description |
---|---|---|
result |
array(object) |
|
status |
integer |
Status Code 0:OK, >0:error |
message |
string |
Error message |
Parsing result object
Key Name | Data Type | Description |
---|---|---|
chunk_info |
object |
|
tokens |
array(object) |
Clause object
Key Name | Data Type | Description |
---|---|---|
id |
integer |
Clause number (zero-based) |
head |
integer |
Clause number of modifee |
dep |
string |
Modification type O - no modifee Q - Self modification A - Apposition I - Partial parallel P - Parallel D - Default |
chunk_head |
integer |
Starting position of content word (0 origin relative number within chunk) |
chunk_func |
integer |
Starting position of functional word (0 origin relative number within chunk) |
links |
array(object) |
|
predicate |
array(string) |
Array of information of functional word negative - Negative past - Past Tense passive - Passive voice |
Array of modifier
Key Name | Data Type | Description |
---|---|---|
link |
integer |
Clause number of modifier |
label |
string |
Morpheme object
Key Name | Data Type | Description |
---|---|---|
id |
integer |
Morpheme Number (zero-based) |
form |
string |
Form |
kana |
string |
Katakana Reading |
lemma |
string |
lemma |
pos |
string |
|
features |
array(string) |
|
dependency_labels |
array(object) |
|
attributes |
object |
Attributes information |
Array of morpheme info of the destination
Key Name | Data Type | Description |
---|---|---|
token_id |
integer |
Dependant morpheme number |
label |
string |
Responses example
{ "result" : [ { "chunk_info" : { "id" : 0, "head" : 1, "dep" : "D", "chunk_head" : 0, "chunk_func" : 1, "links" : [ ] }, "tokens" : [ { "id" : 0, "form" : "犬", "kana" : "イヌ", "lemma" : "犬", "pos" : "名詞", "features" : [ ], "dependency_labels" : [ { "token_id" : 1, "label" : "case" } ], "attributes" : { } }, { "id" : 1, "form" : "は", "kana" : "ハ", "lemma" : "は", "pos" : "連用助詞", "features" : [ ], "attributes" : { } } ] }, { "chunk_info" : { "id" : 1, "head" : -1, "dep" : "O", "chunk_head" : 0, "chunk_func" : 1, "links" : [ { "link" : 0, "label" : "agent" } ], "predicate" : [ ] }, "tokens" : [ { "id" : 2, "form" : "歩", "kana" : "アル", "lemma" : "歩く", "pos" : "動詞語幹", "features" : [ "K" ], "dependency_labels" : [ { "token_id" : 0, "label" : "nmod" }, { "token_id" : 3, "label" : "aux" }, { "token_id" : 4, "label" : "punct" } ], "attributes" : { } }, { "id" : 3, "form" : "く", "kana" : "ク", "lemma" : "く", "pos" : "動詞接尾辞", "features" : [ "終止" ], "attributes" : { } }, { "id" : 4, "form" : "。", "kana" : "", "lemma" : "。", "pos" : "句点", "features" : [ ], "attributes" : { } } ] } ], "status" : 0, "message" : "" }
Input/Output Item
List of Parts of Speech
The list of parts of speech output by the parsing API is displayed below.
Part of Speech | Details | Example |
---|---|---|
名詞 |
Morphemes representing concrete object such as a person, a place, etc. |
- |
名詞接尾辞 |
Morpheme that comes after noun |
「組」 in 「f組」, 「性」 in 「可用性」 |
冠名詞 |
Morpheme that comes before noun |
「大」 in 「大募集」 |
英語接尾辞 |
Morpheme that comes before noun |
“ing” in “talking” |
動詞語幹 |
The morpheme that comes after English noun |
「表」 in 「表す」, 「見え」 in 「見える」 |
動詞活用語尾 |
Morphemes representing verb stem |
「し」 in 「示している」 |
動詞接尾辞 |
Morpheme that come after verb stem, representing the verb conjugation. (Conjugated verb is a verb that has been altered from its base form.) |
「て」 in 「示している」 |
冠動詞 |
Morphemes that comes after verb stem, and verb conjugations |
「ぶち」 in 「ぶち破る」 |
補助名詞 |
Morphemes that comes before verb stem |
「ため」 in 「顔に出たため」, 「こと」 in 「見なかったこと」 |
形容詞語幹 |
Morphemes that appear right after adnominal phrases |
「安」 in 「安い価格」 |
形容詞接尾辞 |
Morphemes representing adjective stem |
「い」 in 「安い価格」 |
冠形容詞 |
Morphemes that come after adjective stem |
「同じ」 in 「同じ役割」 |
連体詞 |
Morphemes that come before adjective stem |
「同じ役割」の「同じ」 |
連用詞 |
Morphemes that constitute an attributive clause independently |
「また」 in 「また同様に」 |
接続詞 |
Morphemes that constitute conjunctive clause independently, which is commonly called "adverb". |
「しかし」「また」「なお」 |
独立詞 |
Morphemes that comes at the beginning of sentence, and expressing relations between two sentences. |
「さようなら」 |
接続接尾辞 |
Morphemes that express greetings and addressing, also called "interjection". |
「が」 in 「~であるが」 |
判定詞 |
Morphemes that come after verb and adjective |
「では」 in 「ニューデリーでは」 |
格助詞 |
Morphemes that constitute the clause of predicate that comes after the noun |
「が」 in 「リンゴが赤い」 |
引用助詞 |
Morphemes that constitute conjunctive and adnominal, that immediately follow the modified noun, verb, adjective, or sentence. |
「と」 in 「~だと推測される」 |
連用助詞 |
Morphemes that express quotes |
「も」 in 「現在も続く」 |
終助詞 |
Morphemes that also called as predicate |
「よ」 in 「~ですよ」 |
間投詞 |
Morphemes that terminate the sentence. |
「ね」 in 「私はね、~」 |
括弧 |
Parentheses and brackets. |
- |
句点 |
Morphemes consists of punctuation marks such are period, question mark, and exclamation point. |
- |
読点 |
Comma |
- |
空白 |
Space |
- |
Symbol |
Morphemes of symbol |
“♪”, “+”, etc. |
Number |
Morphemes that represent numerical value. |
- |
助数詞 |
Morphemes that follow the number |
「杯」 in 「約3杯」 |
助助数詞 |
Morphemes that follow counter suffix |
「あたり」 in 「五個あたり」 |
冠数詞 |
Morphemes that comes before the number |
「第」 in 「第3回目」 |
List of Features
The list of features output by the parsing API is displayed below. Features are classified with part of speech.
Part of Speech | Features | Details | Example |
---|---|---|---|
名詞 |
動作 |
Verb can be formed by adding 「する」at the end of a noun |
「学習」、「発展」 |
形容 |
Adjective verb |
「寛容」、「おてんば」 |
|
固有 |
Proper noun |
「キリスト」 |
|
固有:姓 |
A proper noun that used to represent a person’s surname |
「鈴木」 |
|
固有:名 |
A proper noun that used to represent a person’s name |
「一郎」 |
|
固有:地 |
A proper noun that used to represent a place name |
「日本」、「北海道」 |
|
固有:組織 |
A proper noun that used to represent an organization |
「国土交通省」、「NTT」 |
|
代名詞 |
Personal pronoun |
「彼」、「あなた」 |
|
指示 |
Demonstrative pronoun |
「それ」、「こちら」 |
|
日時 |
A noun that used to represent date |
「6月」、「去年」 |
|
時間 |
A noun that used to represent time |
「23時」、「15分」 |
|
動詞語幹 |
A |
Ru-verbs (Ichidan-verb) |
「食べる」の「食べ」 |
K |
U-verbs (Godan-verb) with 「く」ending |
「書く」の「書」 |
|
G |
U-verbs (Godan-verb) with 「ぐ」ending |
「泳ぐ」の「泳」 |
|
S |
U-verbs (Godan-verb) with 「す」ending |
「話す」の「話」 |
|
T |
U-verbs (Godan-verb) with 「つ」ending |
「打つ」の「打」 |
|
N |
U-verbs (Godan-verb) with 「ぬ」ending |
「死ぬ」の「死」 |
|
B |
U-verbs (Godan-verb) with 「ぶ」ending |
「飛ぶ」の「飛」 |
|
M |
U-verbs (Godan-verb) with 「む」ending |
「積む」の「積」 |
|
R |
U-verbs (Godan-verb) with 「る」ending |
「変わる」の「変わ」 |
|
W |
U-verbs (Godan-verb) with 「う」ending |
「失う」の「失」 |
|
KURU |
Irregular conjugation with 「くる」ending:「来る」「くる」only |
「来る」の「来」 |
|
SURU |
Irregular conjugation with 「する」ending:「する」only |
「する」の「す」 |
|
SX |
Irregular conjugation of s-stem verbs with 「する」ending |
「供する」の「供」 |
|
RX |
Irregular conjugation of a limited number of verbs ending in「る」(special):「いらっしゃる」「おっしゃる」「くださる」「ござる」「なさる」only |
「下さる」の「下さ」 |
|
IKU |
Irregular conjugation of a limited number of verbs ending in 「く」(special):「行く」「いく」only |
「行く」の「行」 |
|
ZX |
Irregular conjugation of the verb ending in 「ず」 |
「信ずる」の「信」 |
|
Lて連用 |
Auxiliary verb |
「聞いてみる」の「み」 |
|
形容詞語幹 |
アウオ段 |
Adjective that word before conjugational suffix turns into 'アウオ段' |
「暖かい」の「暖か」 |
イ段 |
Adjective that word before conjugational suffix turns into 'イ段' |
「美しい」の「美し」 |
|
Lて連用 |
Auxiliary adjective |
「買ってほしい」の「ほし」 |
|
名詞接尾辞 |
名詞 |
Adding a suffix to a noun to form a noun |
「家族ぐるみ」の「ぐるみ」 |
動作 |
You can attach「する」to a noun after adding a suffix to it |
「日陰干しする」の「干し」 |
|
形容 |
Adding a suffix to a noun to modify a noun that works the same as noun’s description |
「野菜嫌い」の「嫌い」 |
|
動詞語幹 |
Adding a suffix to a noun to form a verb |
「勇気づける」の「づけ」 |
|
形容詞語幹 |
Adding a suffix to a noun to form an adjective |
「パリ近くで発見」の「近」 |
|
動詞接尾辞 |
命令 |
The inflection changes the meaning of words into imperative mood |
「よく、考えろ!」の「ろ」 |
名詞 |
Adding a suffix to a verb to form a noun |
「使いっぱなしはよくない」の「っぱなし」 |
|
動詞語幹 |
Adding a suffix to a verb to form a verb |
「両立させる」の「せ」 |
|
形容詞語幹 |
Adding a suffix to a verb to form an adjective |
「動きたくない」の「な」 |
|
形容詞接尾辞 |
名詞 |
Adding a suffix to adjective to form a noun |
「かわいさ」の「さ」 |
動詞語幹 |
Adding a suffix to adjective to form a verb |
「寒がる」の「が」 |
|
形容詞語幹 |
Adding a suffix to adjective to form an adjective |
「美しかあない」の「かあな」 |
|
接続接尾辞 |
動詞語幹 |
Works as verb when adding a suffix to suffix |
「行くに違いありません」の「に違いあ」 |
形容詞語幹 |
Works as adjective when adding a suffix to a suffix |
「取り込めるらしい」の「らし」 |
|
判定詞 |
名詞 |
Works as noun when suffixing to noun |
「本物かどうかを見極める」の「かどうか」 |
形容詞語幹 |
Works as adjectives when adding to noun |
「大人っぽい」の「っぽい」 |
|
括弧 |
開括弧 |
"(", "{" etc. |
「]」 |
閉括弧 |
")" applies after "(" |
「)」 |
|
句点 |
疑問符 |
? |
「?」 |
感嘆符 |
! |
「!」 |
Semantic Role Label List
Here is the list of Semantic role label.
Semantic Label Name | Details | Example |
---|---|---|
agent |
An entity that causes intentional act |
|
agentnonvoluntary |
Agent that causes non intentional act |
|
coagent |
Subject that acts together with agent |
|
aobject |
Object that has an attribute |
|
object |
Object affected by action and change |
|
implement |
Means and instruments used for intentional act |
|
source |
Subject of the event or first position of object |
を |
material |
Material or component |
|
goal |
Subject of the event or last position of object |
|
beneficiary |
Destination of benefit and disadvantage |
|
place |
Place where the event happens |
|
scene |
Scene where event happens |
|
manner |
How to act and change |
|
time |
Time when the event occurs |
に |
timefrom |
Time when the event starts |
|
timeto |
Time when the event ends |
|
basis |
Standard crtiteria |
|
unit |
Unit |
|
fromto |
Range |
|
purpose |
Purpose |
|
condition |
Condition for circumstances. |
|
adjectivals |
Adjectivals |
|
adverbials |
Adverbials |
- |
other |
Other |
- |
Dependency Label List
Here is the list of dependency label.
These conform to Universal Dependencies v1.
Dependency label name | Description | Example |
---|---|---|
nsubj |
a nominal which is the syntactic subject and the proto-agent of a clause. |
空気が美味い 美味い → nsubj 空気 |
nsubjpass |
a passive nominal subject is a noun phrase which is the syntactic subject of a passive clause. |
希望が託される 託さ → nsubjpass 希望 |
dobj |
direct object of a verbal phrase. |
手を繋ぐ 繋ぐ → dobj 手 |
iobj |
nominal phrase that is a core argument of the verb but is not its subject or (direct) object that comes with "に", etc. |
花子にあげる あげる → iobj 花子 |
nmod |
a noun functioning as a non-core (oblique) argument or adjunct. |
ここで叫ぶ 叫ぶ → nmod ここ |
csubj |
a clausal syntactic subject of a clause. |
笑うのが下手 下手 → csubj 笑う |
csubjpass |
a clausal syntactic subject of a passive clause. |
言ったのが悔やまれる。 悔やま → csubjpass 言っ |
ccomp |
a dependent clause with an internal subject which functions like an object of the verb or adjective. |
甘えたいと思う 思う → ccomp 甘え |
advcl |
a clause which modifies a verb or other predicate (adjective, etc.), as a modifier not as a core complement. |
平凡だけどそこが良い 良い → advcl 平凡 |
advmod |
a (non-clausal) adverb or adverbial phrase that serves to modify a predicate or a modifier word. |
絶対許さない 許さ → advmod 絶対 |
neg |
negation word that modifies the word (verb, adjective, etc.) |
絶対許さない 許さ → neg ない |
nummod |
any number phrase that serves to modify the meaning of the noun with a quantity. |
3冊の本 冊 → nummod 3 |
appos |
any number phrase that serves to modify the meaning of the noun with a quantity. |
友達(♀) 友達 → appos ♀ |
acl |
Finite and non-finite clauses that modify a nominal. |
愛を込めたプレゼント プレゼント → acl 込め |
amod |
Any adjectival phrase that serves to modify the meaning of the noun phrase. |
偉大な力 力 → amod 偉大 |
det |
The relation between the head of an noun phrase and its determiner. |
この本 本 → det この |
compound |
Multiword expressions (MWEs) for general nouns and verbs. |
自覚症状 症状 → compound 自覚 |
name |
Multiword expressions (MWEs) of proper nouns (onomastics) |
山田太郎 山田 → name 太郎 |
conj |
The relation between two clauses (noun phrase) connected by a coordinating conjunction, such as and, or, etc. |
アダムとイブ アダム → conj イブ |
cc |
Conjuncation |
アダムとイブ アダム → cc と |
aux |
a function word that accompanies the lexical verb of a verb phrase and expresses grammatical distinctions not carried by the lexical verb, such as person, number, tense, mood, aspect, voice or evidentiality. |
甘えたいと思う 甘え → aux たい |
auxpass |
a non-main verb of the clause which contains the passive information. |
希望が託される 託さ → auxpass れる |
cop |
Copula |
太郎は学生だ。 学生 → cop だ |
case |
Case-marking-particle |
空気が美味い 空気 → case が |
mark |
The word introducing a clause subordinate to another clause. |
笑うのが下手 笑う → mark の |
punct |
Comma |
食べます。 食べ → punct 。 |
vocative |
Compellation |
太郎君、走れ 走る → vocative 君 |
discourse |
Discourse element |
あー疲れる 疲れる → discourse あー |
Named entity extraction
Named entity extraction API receives sentence written in Japanese as an input, analyzes, and outputs 8 types of named entity (the names of people, places, time expressions (time, date), the names of organization, quantitative expressions (amount of money, ratio) , artifacts), and extended named entity with more than 200 classes.
Request
HTTP Endpoint
Request Header
Key Name | Description |
---|---|
Content-Type |
application/json;charset=UTF-8 |
Authorization |
Bearer [Access Token] |
Request Body
Key Name | Data Type | Required | Description |
---|---|---|---|
sentence |
string |
Required |
Sentence to be analyzed |
type |
string |
Optional |
You can choose one from the following (default:default) default - Normal sentence kuzure - sentence contains word lengthening often found in SNSs |
dic_type |
array |
Optional |
Specify technical term dictionaries. Choose from ther below.(only for Enterprise user) IT - Computer,information,communication automobile - Automobile chemistry - Chemical and Petroleum Industries company - Company Name construction - Civil engineering and construction economy - Economy and laws and regulations energy - Electric power and energy institution - Organizations machinery - Machinery medical - Medical metal - Metal |
Request Sample (cURL)
$ curl -X POST -H "Content-Type:application/json;charset=UTF-8" -H "Authorization:Bearer [Access Token]" -d '{"sentence":"昨日は東京駅を利用した。","type": "default"}' "[API Base URL]/nlp/v1/ne"
Response
Response
Key Name | Data Type | Description |
---|---|---|
result |
array(object) |
|
status |
integer |
Status code 0:OK, >0 Error |
message |
string |
Error message |
Named entity extraction result objects
Key Name | Data Type | Description |
---|---|---|
begin_pos |
integer |
Beginning character position (zero-based) |
end_pos |
integer |
Beginning character position (zero-based) |
form |
string |
Form |
std_form |
string |
Standard Form |
class |
string |
|
extended_class |
string |
|
info |
string |
Attributes information |
source |
string |
Source of extraction |
Responses example
{ "result" : [ { "begin_pos" : 0, "end_pos" : 2, "form" : "昨日", "std_form" : "昨日", "class" : "DAT", "extended_class" : "", "info" : { "normalized_datetime" : "2021-12-22" }, "source" : "basic" }, { "begin_pos" : 3, "end_pos" : 6, "form" : "東京駅", "std_form" : "東京駅", "class" : "LOC", "extended_class" : "", "source" : "basic" } ], "status" : 0, "message" : "" }
Input/Output Item
Named-entity class list
The list of named entity classes output by the named entity recognition API is displayed below.
Name | Description |
---|---|
ORG |
Name of organizations |
PSN |
Name of person |
LOC |
Place |
ART |
Artifact |
DAT |
Date |
TIM |
Time |
NUM |
Number |
MNY |
Number |
PCT |
Percentage |
OTH |
Others |
Extended Named-Entity Class List
Here is the list of extended named-entity class.
Category | Sub Category | Name | Details |
---|---|---|---|
Name |
Name |
Name |
|
Name_Other |
Name/Other |
||
Person |
Person |
||
God |
Name of a god |
||
Organization |
Organization |
Organization |
|
Organization_Other |
Organization/Other |
||
International_Organization |
International organization |
||
Show_Organization |
Performance organization |
||
Family |
Family name |
||
Organization |
Ethnic Group |
Ethnic_Group |
Ethnic group |
Ethnic_Group_Other |
Ethnic group/Other |
||
Nationality |
Nationality |
||
Sports |
Sports_Organization |
Sports organization |
|
Sports_Organization_Other |
Sports organization/Other |
||
Pro_Sports_Organization |
Professional sports organization |
||
Sports_League |
Sports league |
||
Corporation |
Corporation |
Corporation |
|
Corporation_Other |
Corporation/Other |
||
Company |
Company |
||
Company_Group |
Company group |
||
Political |
Political_Organization |
Political organization |
|
Political_Organization_Other |
Political organization/Other |
||
Government |
Governmental organization |
||
Political_Party |
Political party |
||
Cabinet |
Cabinet |
||
Military |
Military |
||
Location |
Location |
Location |
|
Location_Other |
Location/Other |
||
Spa |
Spa |
||
Location |
GPE(Geographical/Social/Political Entities) |
GPE |
GPE (geographical/social/political entities: areas with a government) |
GPE_Other |
GPE/Other |
||
City |
City, ward, town, village |
||
County |
County |
||
Province |
Province, prefecture |
||
Country |
Country |
||
Region |
Region |
Region |
|
Region_Other |
Region/Other |
||
Continental_Region |
Continental region |
||
Domestic_Region |
Domestic region |
||
Geological Region |
Geological_Region |
Geological region |
|
Geological_Region_Other |
Geological region/Other |
||
Mountain |
Mountain |
||
Island |
Island |
||
River |
River |
||
Lake |
Lake |
||
Sea |
Sea |
||
Bay |
Bay |
||
Astronomical |
Astral_Body |
Astronomical object |
|
Astral_Body_Other |
Astronomical object/Other |
||
Star |
Star |
||
Planet |
Planet |
||
Constellation |
Constellation |
||
Address |
Address |
Address |
|
Address_Other |
Address/Other |
||
Postal_Address |
Postal address |
||
Phone_Number |
Telephone number |
||
|
|
||
URL |
URL |
||
Facility |
Facility |
Facility |
|
Facility_Other |
Facility/Other |
||
Facility_Part |
Part of facility name |
||
Facility |
Archaeological Place |
Archaeological_Place |
Archaeological place, ruins or similar site |
Archaeological_Place_Other |
Archaeological place, ruins or similar site/Other |
||
Tumulus |
Tumulus (burial mound) |
||
GOE(geographical and organizational entity) |
GOE |
GOE (geographical and organizational entity: facility with organization name attribute) |
|
GOE_Other |
GOE/Other |
||
Public_Institution |
Public institution |
||
School |
School |
||
Research_Institute |
Research institute |
||
Market |
Exchange, market |
||
Park |
Park |
||
Sports_Facility |
Sports facility |
||
Museum |
Museum |
||
Zoo |
Zoo |
||
Amusement_Park |
Amusement park |
||
Theater |
Theater |
||
Worship_Place |
Place of worship |
||
Car_Stop |
Vehicle terminal |
||
Station |
Station |
||
Airport |
Airport |
||
Port |
Port |
||
Line |
Line |
Line |
|
Line_Other |
Line/Other |
||
Railroad |
Railroad line |
||
Road |
Road |
||
Canal |
Canal |
||
Water_Route |
Maritime route |
||
Tunnel |
Tunnel |
||
Bridge |
Bridge |
||
Product |
Product |
Product |
|
Product_Other |
Product/Other |
||
Material |
Material |
||
Clothing |
Clothing |
||
Money_Form |
Currency |
||
Drug |
Medicinal product |
||
Weapon |
Weapon |
||
Stock |
Stock |
||
Award |
Award |
||
Decoration |
Decoration (e.g. medal) |
||
Offense |
Offense (e.g. crime) |
||
Service |
Service |
||
Class |
Class |
||
Character |
Character |
||
ID_Number |
ID number |
||
Product |
Vehicle |
Vehicle |
Vehicle |
Vehicle_Other |
Vehicle/Other |
||
Car |
Car |
||
Train |
Train |
||
Aircraft |
Aircraft |
||
Spaceship |
Spacecraft |
||
Ship |
Ship |
||
Food |
Food |
Food |
|
Food_Other |
Food/Other |
||
Dish |
Dish |
||
Artwork |
Art |
Artwork |
|
Art_Other |
Artwork/Other |
||
Picture |
Picture |
||
Broadcast_Program |
Television program |
||
Movie |
Movie |
||
Show |
Show |
||
Music |
Music |
||
Book |
Literature |
||
Printed Material |
Printing |
Printed material |
|
Printing_Other |
Printed material/Other |
||
Newspaper |
Newspaper |
||
Magazine |
Magazine |
||
Doctrine |
Doctrine_Method |
Doctrine |
|
Doctrine_Method_Other |
Doctrine/Other |
||
Culture |
Culture |
||
Religion |
Religion |
||
Academic |
Academics |
||
Style |
Style |
||
Sport |
Sport |
||
Movement |
Exercise or similar activity |
||
Theory |
Theory |
||
Plan |
Government policy and planning |
||
Rule |
Rule |
Rule |
|
Rule_Other |
Rule/Other |
||
Treaty |
Treaty |
||
Law |
Law |
||
Title |
Title |
Title |
|
Title_Other |
Title/Other |
||
Position_Vocation |
Position or job title |
||
Language |
Language |
Language |
|
Language_Other |
Language/Other |
||
National_Language |
National language |
||
Unit |
Unit |
Unit |
|
Unit_Other |
Unit/Other |
||
Currency |
Currency unit |
||
Event |
Event |
Event |
|
Event_Other |
Event/Other |
||
Event |
Occasion |
Occasion |
Entertainment or social event |
Occasion_Other |
Entertainment or social event/Other |
||
Religious_Festival |
Religious festival |
||
Game |
Competition |
||
Conference |
Conference |
||
Accident/Incident |
Incident |
Accident or incident |
|
Incident_Other |
Accident or incident/Other |
||
War |
War |
||
Natural Disaster |
Natural_Phenomenon |
Natural disaster |
|
Natural_Phenomenon_Other |
Natural phenomenon/Other |
||
Natural_Disaster |
Natural disaster |
||
Earthquake |
Earthquake |
||
Natural Object |
Natural_Object |
Natural object |
|
Natural_Object_Other |
Natural object/Other |
||
Element |
Element |
||
Compound |
Compound |
||
Mineral |
Mineral |
||
Natural Object |
Living Thing |
Living_Thing |
Living thing |
Living_Thing_Other |
Living thing/Other |
||
Fungus |
Fungus |
||
Mollusc_Arthropod |
Mollusk or arthropod |
||
Insect |
Insect |
||
Fish |
Fish |
||
Amphibia |
Amphibian |
||
Reptile |
Reptile |
||
Bird |
Bird |
||
Mammal |
Mammal |
||
Flora |
Flora |
||
Part of a Living Thing |
Living_Thing_Part |
Part of a living thing |
|
Living_Thing_Part_Other |
Part of a living thing/Other |
||
Animal_Part |
Part of an animal |
||
Flora_Part |
Part of a plant |
||
Disease |
Disease |
Disease |
|
Disease_Other |
Disease/Other |
||
Animal_Disease |
Animal disease |
||
Color |
Color |
Color |
|
Color_Other |
Color/Other |
||
Nature_Color |
Natural color |
||
Time Expression |
Time_Top |
Time expression |
|
Time_Top_Other |
Time expression/Other |
||
Time |
Time |
Timex |
Time |
Timex_Other |
Time/Other |
||
Time |
Time expression |
||
Date |
Date expression |
||
Day_Of_Week |
Day of the week expression |
||
Era |
Era (historic) expression |
||
Period |
Periodx |
Period |
|
Periodx_Other |
Period/Other |
||
Period_Time |
Period of time |
||
Period_Day |
Period of days |
||
Period_Week |
Period of weeks |
||
Period_Month |
Period of months |
||
Period_Year |
Period of years |
||
Number-Related Expression |
Numex |
Number-related expression |
|
Numex_Other |
Number-related expression/Other |
||
Money |
Money-related expression |
||
Stock_Index |
Stock index |
||
Point |
Points |
||
Percent |
Percentage expression |
||
Multiplication |
Multiplication expression |
||
Frequency |
Frequency expression |
||
Age |
Age |
||
School_Age |
School age |
||
Ordinal_Number |
Ordinal |
||
Rank |
Rank expression |
||
Latitude_Longtitude |
Latitude and longitude |
||
Number-Related Expression |
Measurement Expression |
Measurement |
Measurement expression |
Measurement_Other |
Measurement expression/Other |
||
Physical_Extent |
Length |
||
Space |
Area (measurement) |
||
Volume |
Volume |
||
Weight |
Weight |
||
Speed |
Speed |
||
Intensity |
Density |
||
Temperature |
Temperature |
||
Calorie |
Calories |
||
Seismic_Intensity |
Seismic intensity |
||
Seismic_Magnitude |
Magnitude |
||
Number of Items |
Countx |
Number of items |
|
Countx_Other |
Number of items/Other |
||
N_Person |
Number of people |
||
N_Organization |
Number of organizations |
||
N_Location |
Number of locations |
||
N_Location_Other |
Number of locations/Other |
||
N_Country |
Number of countries |
||
N_Facility |
Number of facilities |
||
N_Product |
Number of products |
||
N_Event |
Number of events |
||
N_Natural_Object |
Number of natural objects |
||
N_Natural_Object_Other |
Number of natural objects/Other |
||
N_Animal |
Number of animals |
||
N_Flora |
Number of plants |
Informaation(info)
The following is the attached information that is output by the Named Entity Extraction API.
key | description |
---|---|
normalized_datetime |
Normalized date and time. This information is output when a specific date and time can be estimated for a DAT or TIME entity. The format can be one of the following patterns in the ISO 8601 extended format. The time zone is JST fixed.
|
id |
If a industry dictionary is specified, the ID in the dictionary is output. The same ID is used even if there is a notation distortion, so identity can be determined by the ID. |
Company Name Normalization
Company Name Normalization API extracts and corrects proper nouns (Company Name) from text.
Corrected company name is provided for a company name that contain misrepresentation or fluctuation.
Since corrected company names can be extracted from input sentences, many text data including company names can be used for aggregation and analysis by company.
Please note that this API is not available in for Developers environment account.
Request
HTTP Endpoint
POST [API Base URL]/nlp/v1/normalize_ne/company
Request Header
Key Name | Description |
---|---|
Content-Type |
application/json;charset=UTF-8 |
Authorization |
Bearer [Access Token] |
Request Body
Key Name | Data Type | Required | Description |
---|---|---|---|
sentence |
string |
Required |
Text to be analyzed |
type |
string |
Optional |
Can be one of the following (Default:default) default - Normal Sentence kuzure - Broken sentences on social media |
Request Sample (cURL)
$ curl -X POST -H "Content-Type:application/json;charset=UTF-8" -H "Authorization:Bearer [Access Token]" -d '{"sentence":"NTTに勤務しています","type": "default"}' "[API Base URL]/nlp/v1/normalize_ne/company"
Response
Response
Key Name | Data Type | Description |
---|---|---|
result |
array(object) |
|
status |
integer |
Status Code 0:OK, >0:Error |
message |
string |
Error Message |
Company name normalization result object
Key Name | Data Type | Description |
---|---|---|
begin_pos |
integer |
Start character position (0 Origin) |
end_pos |
integer |
End character position (0 Origin) |
form |
string |
Uncorrected notation |
normalized |
array(object) |
Corrected company name information object
Key Name | Data Type | Description |
---|---|---|
form |
string |
Post-correction notation (common name) |
distance |
integer |
Distance between uncorrected and corrected notation (common name) |
std_forms |
array(string) |
Array of formal names |
Response Sample
{ "result": [ { "begin_pos": 0, "end_pos": 3, "form": "ntt", "normalized": [ { "distance": 0, "form": "ntt", "std_forms": ["日本電信電話株式会社", "東日本電信電話株式会社", "西日本電信電話株式会社"] }] }], "status": 0, "message": "" }
Reference Resolution
Receive multiple sentences written in Japanese as an input, extract pronouns such as "そこ", "それ","彼", "彼女", extract an antecedent that correspond to those pronouns, and outputs them as a pair of pronoun and object.
Request
HTTP Endpoint
POST [API Base URL]/nlp/v1/coreference
Request Header
Key Name | Description |
---|---|
Content-Type |
application/json;charset=UTF-8 |
Authorization |
Bearer [Access Token] |
Request body
Key Name | Data Type | Required | Description |
---|---|---|---|
document |
string / array(string) |
Required |
You can choose one from the following string - sentence to be analyzed array(string) - sentences to be analyzed |
type |
string |
Optional |
You can choose one from the following (default:default) default - normal sentence kuzure - entence contains word lengthening often found in SNSs |
do_segment |
boolean |
Optional |
You can choose whether to segment the sentences (default:false) true - if the type of 'document' is 'string', the document will be segmented. false - the document will not be segmented. #if the type of 'document' is 'array (string)', do_segment will be ignored. |
Request example (cURL)
$ curl -X POST -H "Content-Type:application/json;charset=UTF-8" -H "Authorization:Bearer [Access Token]" -d '{"document":"太郎は友人です。彼は焼き肉を食べた。","type": "default","do_segment":true}' "[API Base URL]/nlp/v1/coreference"
Responses
Response
Key Name | Data Type | Description |
---|---|---|
result |
object |
|
status |
integer |
Status code 0:OK, >0:error |
message |
string |
error message |
Result of reference resolution result object
Key Name | Data Type | Description |
---|---|---|
coreference |
array(object) |
|
tokens |
array(string) |
Array of forms |
Reference resolution object
Key Name | Data Type | Description |
---|---|---|
representative_id |
integer |
Reference resolution ID (zero-based) |
referents |
object |
Entity object
Key Name | Data Type | Description |
---|---|---|
referent_id |
integer |
Entity ID (zero-based) |
sentence_id |
integer |
Number of sentence that contains entity (zero-based) |
token_id_from |
integer |
Entity's starting morpheme number |
token_id_to |
integer |
Entity's ending morpheme number |
Response example
{ "result" : { "coreference" : [ { "representative_id" : 0, "referents" : [ { "referent_id" : 0, "sentence_id" : 0, "token_id_from" : 0, "token_id_to" : 0, "form" : "太郎" }, { "referent_id" : 1, "sentence_id" : 1, "token_id_from" : 0, "token_id_to" : 0, "form" : "彼" } ] } ], "tokens" : [ [ "太郎", "は", "友人", "です" ], [ "彼", "は", "焼き肉", "を", "食べ", "た" ] ] }, "status" : 0, "message" : "OK" }
Keyword extraction
Keyword extraction API receives multiple sentences written in Japanese as an input, and extracts characteristic phrases and words contained in input sentence as a keywords. Multiple phrases and words are output in decending order based on the characteristic score measured from the text.
Request
HTTP Endpoint
POST [API Base URL]/nlp/v1/keyword
Request Header
Key Name | Description |
---|---|
Content-Type |
application/json;charset=UTF-8 |
Authorization |
Bearer [Access Token] |
Request Body
Key Name | Data Type | Required | Description |
---|---|---|---|
document |
string |
Required |
You can choose one from the following string - sentence to be analyzed array(string) - sentences to be analyzed |
type |
string |
Optional |
You can choose one from the following (default:default) default - normal sentence kuzure - sentence contains word lengthening often found in SNSs |
do_segment |
boolean |
Optional |
You can choose whether to segment the sentences (default:false) ・true - if the type of 'document' is 'string', the document will be segmented. ・false - the document will not be segmented. #if the type of 'document' is 'array (string)', do_segment will be ignored. |
max_keyword_num |
integer |
Optional |
Maximum number of extracted keywords (default:5) |
dic_type |
array |
Optional |
Specify technical term dictionaries. Choose from ther below.(only for Enterprise user) IT - Computer,information,communication automobile - Automobile chemistry - Chemical and Petroleum Industries company - Company Name construction - Civil engineering and construction economy - Economy and laws and regulations energy - Electric power and energy institution - Organizations machinery - Machinery medical - Medical metal - Metal |
Request sample (cURL)
$ curl -X POST -H "Content-Type:application/json;charset=UTF-8" -H "Authorization:Bearer [Access Token]" -d '{"document":"レストランで昼食を食べた。","type": "default","do_segment":true,"max_keyword_num":2}' "[API Base URL]/nlp/v1/keyword"
Response
Response
Key Name | Data Type | Description |
---|---|---|
result |
array(object) |
|
status |
integer |
Status code 0:OK, >0: error |
message |
string |
Error message |
Array of extracted keyword objects
Key Name | Data Type | Description |
---|---|---|
form |
string |
Keyword |
score |
float |
Keyword score |
Response example
{ "result" : [ { "form" : "レストラン", "score" : 14.144054 }, { "form" : "昼食", "score" : 12.1121 } ], "status" : 0, "message" : "" }
Similarity Calculation
Similarity calculation receives two sentences written in Japanese as input, calculates and outputs semantic similarity between sentences. The degree of similarity is defined from 0 to 1, indicating that the closer to 1, the greater similarity betwen the texts.
Since the similarity is calculated using semantic information of words contained in sentences, we can also estimate the similarity between the sentences containing different words.
Request
HTTP Endpoint
POST [API Base URL]/nlp/v1/similarity
Request header
Key Name | Description |
---|---|
Content-Type |
application/json;charset=UTF-8 |
Authorization |
Bearer [Access Token] |
Request body
Key Name | Data Type | Required | Description |
---|---|---|---|
s1 |
string |
Required |
Sentence to be calculated for similarity |
s2 |
string |
Required |
Sentence to be calculated for similarity |
type |
string |
Optional |
You can choose one from the following (default:default) default - default sentence kuzure - sentence contains word lengthening often found in SNSs |
dic_type |
array |
Optional |
Specify technical term dictionaries. Choose from ther below.(only for Enterprise user) IT - Computer,information,communication automobile - Automobile chemistry - Chemical and Petroleum Industries company - Company Name construction - Civil engineering and construction economy - Economy and laws and regulations energy - Electric power and energy institution - Organizations machinery - Machinery medical - Medical metal - Metal |
Request example (cURL)
$ curl -X POST -H "Content-Type:application/json;charset=UTF-8" -H "Authorization:Bearer [Access Token]" -d '{"s1":"近くのレストランはどこですか?","s2":"このあたりの定食屋はどこにありますか?", "type": "default"}' "[API Base URL]/nlp/v1/similarity"
Response
Response
Key Name | Data Type | Description |
---|---|---|
result |
object |
|
status |
integer |
Status code 0:OK,>0:error |
message |
string |
Error message |
Similarity result object
Key Name | Data Type | Description |
---|---|---|
score |
float |
Similarity (0.0-1.0) |
Responses example
{ "result" : { "score" : 0.88565135 }, "status" : 0, "message" : "" }
Sentence type classification
Sentence type classification API receives a sentence written in Japanese as an input, identifies and outputs the Modality types (descriptions/questions/commands) and dialog act types.
Request
HTTP Endpoint
POST [API Base URL]/nlp/v1/sentence_type
Request header
Key Name | Description |
---|---|
Content-Type |
application/json;charset=UTF-8 |
Authorization |
Bearer [Access Token] |
Request body
Key Name | Data Type | Required | Description |
---|---|---|---|
sentence |
string |
Required |
Sentence to be analyzed |
type |
string |
Optional |
You can choose one from the following (default:default) default - default sentence kuzure - sentence includs word lengthening often found in SNSs |
Request sample (cURL)
$ curl -X POST -H "Content-Type:application/json;charset=UTF-8" -H "Authorization:Bearer [Access Token]" -d '{"sentence":"あなたの名前は何ですか?","type": "default"}' "[API Base URL]/nlp/v1/sentence_type"
Response
Response
Key Name | Data Type | Description |
---|---|---|
result |
object |
|
status |
integer |
Status code 0:OK,>0: error |
message |
string |
Error message |
Sentence type result object
Key Name | Data Type | Description |
---|---|---|
modality |
string |
Modality declarative interrogative imperative |
dialog_act |
array(string) |
Array of dialog act types |
Responses example
{ "result" : { "modality" : "interrogative", "dialog_act" : [ "information-seeking" ] }, "status" : 0, "message" : "" }
Input/Output Item
Speech act list
Here is the list of speech act.
Name | Details |
---|---|
greeting |
Greeting |
information-providing |
Information-providing |
feedback |
Feedback (giving responses to the other party) |
information-seeking |
Information-seeking |
agreement |
Agreement |
feedbackElicitation |
Feedback elicitation |
commissive |
Commitment |
acceptOffer |
Accepting |
selfCorrection |
Self-correction |
thanking |
Gratitude |
apology |
Apology |
stalling |
Stalling (time filler) |
directive |
Directive |
goodbye |
Farewell message |
declineOffer |
Decline |
turnAssign |
Turn assign |
pausing |
Pausing |
acceptApology |
Accept apologies |
acceptThanking |
Accept thanks |
User Attribute Estimation (β)
User attribute estimation API receives sentence written in Japanese as an input, estimates and outputs the attributes of people such as age, gender, hobby, occupation, etc.
This API is provided in Beta Version.
Request
HTTP Endpoint
POST [API Base URL]/nlp/beta/user_attribute
Request Header
Key Name | Description |
---|---|
Content-Type |
application/json;charset=UTF-8 |
Authorization |
Bearer [Access Token] |
Request Body
Key Name | Data Type | Required | Description |
---|---|---|---|
document |
string / array(string) |
Required |
You can choose from the following string - sentence to be analyzed array(string) - sentences to be analyzed |
type |
string |
Optional |
You can choose one from the following (default:default) default - default sentence kuzure - sentence contains word lengthening often found in SNSs |
do_segment |
boolean |
Optional |
You can choose whether to segment the sentences (default:false) true - if the type of document is string, the document will be segmented. false - the document will not be segmented. #if the type of document is array(string), do_segment will be ignored. |
Request example (cURL)
$ curl -X POST -H "Content-Type:application/json;charset=UTF-8" -H "Authorization:Bearer [Access Token]" -d '{"document":"私は昨日田町駅で飲みに行ったら奥さんに怒られた。", "type": "default","do_segment":true}' "[API Base URL]/nlp/beta/user_attribute"
Responses
Response
Key Name | Data Type | Description |
---|---|---|
result |
object |
|
status |
integer |
Status Code 0:OK, >0:error |
message |
string |
Error message |
Result of User's attribute estimation
Key Name | Data Type | Description |
---|---|---|
age |
string |
age |
civilstatus |
string |
numarried/married |
earnings |
string |
income |
gender |
string |
gender (female/male) |
habit |
array(string) |
habit |
hobby |
array(string) |
hobby |
kind_of_bussiness |
string |
industry |
kind_of_occupation |
string |
kinds of occupation |
location |
string |
hometown |
moving |
array(string) |
moving means |
occupation |
string |
occupation |
position |
string |
position |
Response example
{ "result" : { "age" : "40-49歳", "civilstatus" : "既婚", "earnings" : "不明", "gender" : "不明", "habit" : [ "ALCOHOL" ], "hobby" : [ "ANIMAL", "COOKING", "FISHING", "FORTUNE", "GAMBLE", "GRUME", "GYM", "INTERNET", "MOVIE", "PAINT", "SHOPPING", "STUDY" ], "kind_of_business" : "不明", "kind_of_occupation" : "不明", "location" : "不明", "moving" : [ "RAILWAY" ], "occupation" : "会社員", "position" : "不明" }, "status" : 0, "message" : "OK" }
Filler Removal (β)
Filler Removal API receives the text after speech recognition process, specify the fillers such as 「えーと」, 「あのー」, outputs the information and text without fillers. Also, it normalizes the wrong expressions which caused by long vowel and sound disruption, and outputs the normalized text strings.
This API is provided in β version.
Request
HTTP Endpoint
POST [API Base URL]/nlp/beta/remove_filler
Request Header
Key Name | Description |
---|---|
Content-Type |
application/json;charset=UTF-8 |
Authorization |
Bearer [Access Token] |
Request Body
Key Name | Data Type | Required | Description |
---|---|---|---|
text |
string |
Required |
Text to be analyzed |
do_segment |
boolean |
Optional |
Specify whether to delimit or not to delimit the sentence.Specify true when analyzing text that does not include punctuation marks.(default:false) true - delimit the sentence false - not delimit the sentence |
Request Sample (cURL)
$ curl -X POST -H "Content-Type:application/json;charset=UTF-8" -H "Authorization:Bearer [Access Token]" -d '{"text":"えーーっと、あの、今日の打ち合わせでしたっけ。すみません、ちょっと、急用が入ってしまって。","do_segment":true}' "[API Base URL]/nlp/beta/remove_filler"
Response
Response
Key Name | Data Type | Description |
---|---|---|
result |
array(object) |
|
status |
integer |
Status Code 0:OK, >0:Error |
message |
string |
Error Message |
Object Result of Filler Removal
Key Name | Data Type | Description |
---|---|---|
fillers |
list |
Array of Removed Fillers |
normalized_sentence |
string |
Couple of kuzure normalized forms |
fixed_sentence |
string |
Character string after fillers notation was removed from normalized_sentence. |
Removed Fillers
Key Name | Data Type | Description |
---|---|---|
begin_pos |
integer |
Start character position (0 Origin) |
end_pos |
integer |
End character position (0 Origin) |
form |
string |
Input Notation |
Response Sample
{ "result":[ { "fillers":[ { "begin_pos":0, "end_pos":5, "form":"えーっと、" }, { "begin_pos":5, "end_pos":8, "form":"あの、" } ], "normalized_sentence":"えーっと、あの、今日の打ち合わせでしたっけ。", "fixed_sentence":"今日の打ち合わせでしたっけ。" }, { "fillers":[], "normalized_sentence":"すみません。", "fixed_sentence":"すみません。" }, { "fillers":[ { "begin_pos":1, "end_pos":5, "form":" ちょっと" } ], "normalized_sentence":"、ちょっと、急用が入ってしまって。", "fixed_sentence":"、急用が入ってしまって。" } ], "status":0, "message":"OK" }
Detect Misrecognition (β)
Detect Misrecognition API receives the text after speech recognition process, outputs the suspected recognition error and the score at the same time. It also shows the error degree from the entire input sentences in numbers and outputs them.
This API is provided in β version.
Request
HTTP Endpoint
POST [API Base URL]/nlp/beta/detect_misrecognition
Request Header
Key Name | Description |
---|---|
Content-Type |
application/json;charset=UTF-8 |
Authorization |
Bearer [Access Token] |
Request Body
Key Name | Data Type | Required | Description |
---|---|---|---|
sentence |
string |
Required |
Text to be analyzed |
Request Sample(cURL)
$ curl -X POST -H "Content-Type:application/json;charset=UTF-8" -H "Authorization:Bearer [Access Token]" -d '{"sentence":"温泉認識は誤りを起こす"}' "[API Base URL]/nlp/beta/detect_misrecognition"
Response
Response
Key Name | Data Type | Description |
---|---|---|
result |
object |
|
status |
integer |
Status code 0:OK, >0:error |
message |
string |
Error message |
Detected misrecognition result object
Key Name | Data Type | Description |
---|---|---|
candidates |
list |
|
score |
float |
The degree of whole misrecognition of sentence. This is defined from 0 to 1, indicating that the closer to 1, the greater degree of misrecognition. |
Array of detected misrecognition objects
Key Name | Data Type | Description |
---|---|---|
begin_pos |
integer |
Beginning character position in error expression |
end_pos |
integer |
Ending character position in error expression |
form |
string |
Notation of error location |
detect_score |
float |
The degree of misrecognition. This is defined from 0 to 1, indicating that the closer to 1, the greater degree of misrecognition. |
correction |
array(object) |
Array of correction candidate results
Key Name | Data Type | Description |
---|---|---|
form |
string |
corrected result |
correct_score |
float |
The confidence score of correction. This is defined from 0 to 1, indicating that the closer to 1, the greater confidence. |
Response Sample
{ "result":{ "candidates":[ { "begin_pos":0, "end_pos":2, "form":"温泉", "detect_score":0.9993893004798938, "correction":[ { "form":"音声", "correct_score":0.7609916619441945 }, { "form":"怨念", "correct_score":0.6939287852666066 }, { "form":"おんねん", "correct_score":0.6939287852666066 }, { "form":"おんせい", "correct_score":0.6904490533362417 }, { "form":"論戦", "correct_score":0.6719738196456021 } ] } ], "score":0.9993893004798938 }, "status":0, "message":"OK" }
Sentiment Analysis
Sentiment Analysis is text classification tool that analyses an incoming message and determine whether the underlying sentiment is positive or negative. Sentiment Analysis API can also recognize types of more than 50 different feelings such as joy, surprise, fear, pleasure etc. within the sentences.
Request
HTTP Endpoint
POST [API Base URL]/nlp/v1/sentiment
Request Header
Key Name | Description |
---|---|
Content-Type |
application/json;charset=UTF-8 |
Authorization |
Bearer [Access Token] |
Request Body
Key Name | Data Type | Required | Description |
---|---|---|---|
sentence |
string |
Required |
Sentence to be analyzed |
Request Sample(cURL)
$ curl -X POST -H "Content-Type:application/json;charset=UTF-8" -H "Authorization:Bearer [Access Token]" -d '{"sentence":"人生の春を謳歌しています"}' "[API Base URL]/nlp/v1/sentiment"
Response
Response
Key Name | Data Type | Description |
---|---|---|
result |
object |
|
status |
integer |
Status Code 0:OK, >0: error |
message |
string |
Error message |
Object result of sentiment analysis
Key Name | Data Type | Description |
---|---|---|
sentiment |
string |
Sentiment analysis result. Output Positive/Negative/Neutral. |
score |
float |
Sentiment score |
emotional_phrase |
list |
Sentiment phrase object
Key Name | Data Type | Description |
---|---|---|
form |
string |
Notation |
emotion |
string |
Response Sample
{ "result": { "sentiment":"Positive", "score":0.20766788536018937, "emotional_phrase":[ { "form":"謳歌", "emotion":"喜ぶ,安心" } ] }, "status":0, "message":"OK" }
Input/Output Item
Sentiment label
Here is the list of Sentiment label.
Sentiment Label | Description |
---|---|
喜ぶ |
Happy/Joy |
怒る |
Anger |
悲しい |
Sad |
不安 |
Anxious |
恥ずかしい |
Embarrassed/Shy |
好ましい |
Desirable |
嫌 |
Disgust |
興奮 |
Excited |
安心 |
Relaxed |
驚く |
Surprised |
切ない |
Lonely/Painful |
願望 |
Desire/Wish |
P |
Positive |
N |
Negative |
PN |
Positive/Negative |
Speech-to-Text
Please note that this API is not available for developer accounts.
COTOHA Speech Recognition API consists of the following six API methods:
1.Speech Recognition from File
API for transcribing short audio files.
2.Speech Recognition from Stream
API for transcribing streaming audio, such as long audio files or input from a microphone.
3.Update Speech Recognition Dictionary※
API for adding words to the default dictionary.
The dictionary data is reflected every hour on the 0th minute (e.g 0800, 1100, 2300).
It takes a certain amount of time for the data to actually be reflected.
4.Delete Speech Recognition Dictionary※
API for deleting registered dictionary.
The dictionary data is reflected every hour on the 0th minute (e.g 0800, 1100, 2300).
It takes a certain amount of time for the data to actually be reflected.
5.Get Speech Recognition Dictionary State※
API for checking if the dictionary data is reflected.
6.Download speech Recognition Dictionary※
API for downloading the last uploaded dictionary.
※Japanese models only
GitHub
Following are sample codes released on GitHub by the Speech Recognition Team.
GitHub
・Python
・Node.js
・JavaScript
・Reference
Use cases
- Speech Recognition from File
If the audio is longer than 60 seconds, please use Speech Recognition from Stream.
Otherwise, Speech Recognition from File.
- Speech Recognition in Real Time
Please use Speech Recognition from Stream.
- Speech Recognition from WAV Files
If the audio format is wav, please remove the header properly and convert to Linear PCM or μ-Law format.
Please refer to this Sample Code, with wav file input.
- Register a Dictionary
If you want to register words in advance, please use Update Speech Recognition Dictionary.
If you want to change the dictionary for each speech recognition sequence, please use Temporary Dictionary
1.Speech Recognition from File
API for transcribing short audio files.
The length of the audio is limited up to 60 seconds.
Please use Speech Recognition from Stream if audio is longer than 60 seconds.
Request
HTTP Endpoint
POST [API Base URL]/asr/v1/speech_recognition/[ASR Model ID]
ASR Model id is the ID that identifies the model used for speech recognition.Refer to List of Models to select the appropriate model.
Request Header
You need to send a multipart form. Define a boundary delimiter and indicate it as "boundary" in your request header.
Key Name | Description |
---|---|
Content-Type |
multipart/form-data; boundary=<Boundary Delimiter> |
Authorization |
Bearer [Access Token] |
Request Body
Three parts are required for the request body.
1. Parameter Part
2. Audio Data Part
3. Command Part
The data structure to be set for each part of the multipart is specified in each Part Type.
Part Type is set with the Content-Disposition name parameter.
Body part must be set in the order of Parameter Part, Audio Data Part then Command Part.
Part Type | Required | Name | Content-Type |
---|---|---|---|
Parameter Part |
Required |
parameter |
application/json; charset=UTF-8 |
Audio Data Part |
Required |
audio |
application/octet-stream |
Command Part |
Required |
command |
application/json; charset=UTF-8 |
Parameter Part
Refer to Request to Start Speech Recognition for details.
Audio Data Part
Convert the audio data to one of the following formats and use the converted binary for this part.
※If the audio format is wav, please remove the header property and convert it to Linear PCM or μ-Law format.
Format | Sample Rate[Hz] | Quantization[bit] | Channel | Byte Order |
---|---|---|---|---|
Linear PCM |
more than Model's rate (8000 or 16000)※ |
16 |
1 |
Little-Endian |
μ-Law |
8000 |
8 |
1 |
Little-Endian |
※ Please note that we cannot guarantee correct operation for audio other than 8000, 11025, 16000, 22050, 32000, 44100, 48000, 88200, 96000[Hz]
Command Part
See section Request to Stop Speech Recognition for details.
Request Sample (HTTP Header)
Content-Type: multipart/form-data; boundary=<Boundary Delimiter> Authorization: Bearer [Access Token]
Request Sample(HTTP Body)
--<Boundary Delimiter> Content-Disposition: form-data; name="parameter" Content-Type: application/json { "msg": { "msgname": "start" }, "param": { "baseParam.samplingRate": 16000, "recognizeParameter.domainId": "<ASR Domain ID>" } } --<Boundary Delimiter> Content-Disposition: form-data; name="audio" Content-Type: application/octet-stream <Binary Audio Data> --<Boundary Delimiter> Content-Disposition: form-data; name="command" Content-Type: application/json { "msg": { "msgname": "stop" } } --<Boundary Delimiter>--
Response
Response Sample
[ { "msg" : { "msgname" : "started", "uniqueId" : "4d97031a-cfa9-4d66-968a-be708644a893" } }, { "msg" : { "msgname" : "speechStartDetected", "uniqueId" : "4d97031a-cfa9-4d66-968a-be708644a893" }, "timeinfo" : { "startDetectTime" : 0 } }, { "msg" : { "msgname" : "speechEndDetected", "uniqueId" : "4d97031a-cfa9-4d66-968a-be708644a893" }, "timeinfo" : { "endDetectTime" : 3460 } }, { "msg" : { "msgname" : "recognized", "uniqueId" : "4d97031a-cfa9-4d66-968a-be708644a893" }, "result" : { "type" : 1, "sentence" : [ { "surface" : "これ は テスト 用 の 音声ファイル です", "score" : 0.975848, "startTime" : 0.0, "endTime" : 3.46 } ] } }, { "msg" : { "msgname" : "recognized", "uniqueId" : "4d97031a-cfa9-4d66-968a-be708644a893" }, "result" : { "type" : 2, "sentence" : [ ] } }, { "msg" : { "msgname" : "completed", "uniqueId" : "4d97031a-cfa9-4d66-968a-be708644a893", "cause" : "STOP" } } ]
Error Code
Troubleshooting for Request sent
If the following error occurs, please try your request again after taking the rectifying using the described solutions.
If the error persists, please contact us using Contact Us.
code | message | detail | Description and Solution |
---|---|---|---|
410 |
Invalid Parameter |
msg.msgname is invalid -> XXX. |
Check msgname. |
410 |
Invalid Parameter |
param.baseParam.samplingRate is invalid -> XXX and over. |
Check that the sampling rate is higher than the model bandwidth. |
410 |
Invalid Parameter |
recognizeParameter.enableProgress must be false for file speech recognition. |
Sequential recognition result function cannot be used with Speech Recognition from File. |
410 |
Invalid Parameter |
param.baseParam.samplingRate is invalid -> The sampling rate must be 8000 Hz. |
Check that the sampling rate is 8000 Hz. |
411 |
Invalid State |
Invalid Unique ID |
Check the order in which the speech recognition API is called. |
413 |
Invalid Data |
Data is not available |
If the audio data length exceeds the maximum audio length, perform the recognition multiple times. Also make sure that the sampling rate, audio codec, and model specifications are appropriate. |
550 |
No Resource |
VRG_RESPONSE_SERVICE_UNAVAILABLE |
Check that ASR Domain id is correct. If the ASR Domain ID is correct, API access may be congested. Please wait a while and try again. |
651 |
Session Timeout |
Check the order and interval of API calls. |
|
652 |
Excess Of Max Voice Length |
Excess Of Max Voice Length -> 60 [s] |
If the audio data length exceeds the maximum audio length, perform the recognition multiple times. Also make sure that the sampling rate, audio codec, and model specifications are appropriate. |
Troubleshooting for temporary dictionary
If the following error occurs, please try your request again after taking the actions indicated.
If the error persists, please contact us using Contact Us.
code | message | detail | Solution |
---|---|---|---|
410 |
Invalid Parameter |
Invalid Parameter -> List is null |
The notation and the reading is missing |
410 |
Invalid Parameter |
Cascade words exceeded 1000 |
Reduce the additional words in the temporary dictionary to 1000 lines or less. |
410 |
Invalid Parameter |
Surface empty |
Write the notation. |
410 |
Invalid Parameter |
Reading empty |
Write the reading. |
410 |
Invalid Parameter |
Invalid domainid |
Check that ASR Domain id is correct. |
410 |
Invalid Parameter |
Invalid Model Name |
Check that ASR Model id is correct. |
410 |
Invalid Parameter |
Prob illegal |
Specify the weight as an integer between 1 and 100, inclusive. |
410 |
Invalid Parameter |
Surface illegal |
Check that the character string can be set as a notation. |
410 |
Invalid Parameter |
Reading illegal |
Check that the character string can be set as a reading. |
410 |
Invalid Parameter |
Surface too long |
Please ensure that the total of size of the notation and reading in in 251 bytes or less. |
Please contact us
If the following error occurs, please contact us using Contact Us.
Error Code | Message |
---|---|
500 |
Internal Error |
510 |
Out Of Memory |
551 |
Recognition Timeout |
552 |
Network Error |
553 |
Network Timeout |
601 |
Recognition Converter Error |
610 |
Out Of Memory |
611 |
Invalid License |
612 |
Invalid Config |
650 |
No Resource |
690 |
External Command Execute Failed |
691 |
External Command Fatal |
692 |
External Command Error |
693 |
External Command Warn |
Troubleshooting for Request sent
If there is an invalid parameter in the Request to Start Speech Recognition, the following response may be returned with HTTP status code 500.
{ "fault": { "faultstring": "NullPointerException", "detail": { "errorcode": "Internal Server Error" } } }
2.Speech Recognition from Stream
An API for transcribing streaming audio, such as long audio files or input from a microphone.
A length of audio can be up to 3,000 seconds.
If your audio exceeds 3,000 seconds, divide it into parts less than 3,000 seconds and use this method for each separate audio.
Request
Request Type
Speech Recognition for Streaming uses four possible types of requests.
- Request to Start Speech Recognition
- Send Audio Data
- Request to Stop Speech Recognition
- Request to Cancel Speech Recognition
The standard sequence for a Streaming request is as follows.
1. Request to Start Speech Recognition
2. Send Audio Data(one or more than one)
3. Request to Stop Speech Recognition
Request to Start Speech Recognition
This is a request to start speech recognition from the client to the API server.
When using speech recognition, you must first send this request.
This request requires parameter settings as follows.
HTTP Endpoint
POST [API Base URL]/asr/v1/speech_recognition/[ASR Model ID]
ASR Model id is the ID that identifies the model used for speech recognition.
Refer to List of Models to select the appropriate model.
Request Header
Key | Description |
---|---|
Connection |
Keep-Alive |
Content-Type |
application/json; charset=UTF-8 |
Authorization |
Bearer [Access Token] |
Request Body
Key | Required | Description | Valid Range |
---|---|---|---|
msg |
|||
msgname |
Required |
message type |
start |
param |
|||
baseParam.samplingRate |
Required |
sample rate |
more than Model's Rate (8000 or 16000)※1、8000 for mulaw |
recognizeParameter.domainId |
Required |
[ASR Domain ID] |
8 alphanumeric characters |
recognizeParameter.enableContinuous |
Optional※2 |
enable continuous recognition function |
true(default: true) |
recognizeParameter.enableProgress |
Optional |
sequential recognition result function※3 |
true, false(default: false) |
recognizeParameter.maxResults |
Optional |
getting N-Best |
1~30(default: 1) |
baseParam.audioCodec |
Optional |
audio codec |
pcm, mulaw(default: pcm) |
baseParam.filler |
Optional |
getting filler |
true, false(default: false) |
baseParam.punctuation |
Optional |
getting punctuation |
true, false(default: false) |
baseParam.reading |
Optional |
getting reading |
true, false(default: false) |
baseParam.delimiter |
Optional |
getting delimiter(space) |
true, false(default: true) |
words |
Optional |
temporary dictionary |
1000 words or less |
※1 Please note that we cannot guarantee correct operation for audio other than 8000, 11025, 16000, 22050, 32000, 44100, 48000, 88200, 96000[Hz]
※2 This is required until 2020/3/23, but it is now an optional parameter.
※3 Please note that this cannot be used with Speech Recognition from File.
Audio Codec
Linear PCM (pcm) and μ-Law (mulaw) can be specified.
However, μ-Law speech recognition is available only for 8kHz models(ja-gen_tf-08, ja-mdl1_nrw-08, ja-mdl2_nrw-08).
If the audio format is wav, please remove the header properly and convert to Linear PCM or μ-Law format.
Getting Filler
By setting this parameter to true, it is possible to output the filler results(utterances such as あー and えー) in the response, where they are wrapped with [].
※ This is valid only for the models (ja-gen_tf-16, ja-gen_sf-16, ja-gen_tf-08, ja-mdl1_nrw-08, ja-mdl2_nrw-08).
baseParam.filler=false(default)
これ は テスト 用 の 音声ファイル です
baseParam.filler=true
[えーと] これ は テスト 用 の 音声ファイル です
Getting Punctuation
By setting this parameter to true, speech recognition result is output with punctuation.
※ This is valid only for the models (ja-gen_tf-16, ja-gen_tf-08, ja-mdl1_nrw-08, ja-mdl2_nrw-08).
※ There is no guarantee that a sentence will end with a 。.
baseParam.punctuation=false(default)
こんにちは よろしくお願いします
baseParam.punctuation=true
こんにちは 。 よろしくお願いします
Getting Reading
By setting this parameter to true, you can also get the reading in the response.
※ This is valid only for (ja-gen_tf-16, ja-gen_sf-16, ja-gen_tf-08, ja-mdl1_nrw-08, ja-mdl2_nrw-08).
'reading': 'コレ ワ テスト ヨウ ノ オンセイファイル デス'
Please refer to Response Sample for output responses that include reading.
Getting Delimiter
By setting this parameter to false, it is possible to remove space normally inserted between words.
※ When using the English model (en_en-gen_sf-16), the setting true is recommended.
baseParam.delimiter=true(default)
これ は テスト 用 の 音声ファイル です
baseParam.delimiter=false
これはテスト用の音声ファイルです
Sequential Recognition Result Function
By setting this parameter to true, it is possible to sequentially obtain the results during a recognition that have not ended.
Recognition results are returned as recognition result type type = 0.
Note that reading will not be output and filler, punctuation, delimiter will be in the output for the results during recognition, regardless of the parameters.
Getting N-Best
Returns multiple speech recognition results up to the number specified in recognizeParameter.maxResults.
However, do note that the specified number is the upper limit, and it is not guaranteed that the specified number of results will always be returned.
For the output format when recognizeParameter.maxResults is set to 2 or more, refer to Response sample.
Temporary Dictionary
Temporary Dictionary that can be set for each speech recognition sequence.
It can be used in conjunction with Update Speech Recognition Dictionary.
Temporary Dictionary is discarded when the request sequence ends, and the user dictionary will not be updated.
Key | Description | Range | Required |
---|---|---|---|
surface |
surface※1 |
Character string that does not contain |, /, :, ;, [, ], \t, \" and is not empty |
Required |
reading |
reading※1 |
Full-width katakana(Annexed Table) |
Required |
prob |
weight of word※2 |
Integer value from 1 to 100(default: 30) |
Optional |
※1 Please ensure that the total of size of the notation and reading in in 251 bytes or less.
※2 Use this when you want to add weight to registered words.
By setting a value greater than 30, you will be setting a weight greater than the default user dictionary.
By setting a value smaller than 30, you will be setting a weight lower than the default user dictionary.
Sample Request
HTTP Header
Connection: Keep-Alive Content-Type: application/json; charset=UTF-8 Authorization: Bearer <Access Token>
HTTP Body
{ "msg": { "msgname": "start" }, "param": { "baseParam.samplingRate": 16000, "recognizeParameter.domainId": "<ASR Domain ID>", "baseParam.audioCodec": "pcm", "baseParam.filler": true, "baseParam.reading": true, "baseParam.delimiter": false, "baseParam.punctuation": true, "recognizeParameter.enableProgress": true, "recognizeParameter.maxResults": 2 }, "words": [ { "surface": "エヌ・ティ・ティ・コミュニケーションズ株式会社", "reading": "エヌティティコミュニケーションズカブシキガイシャ", "prob": "20" }, { "surface": "COTOHA", "reading": "コトハ", "prob": "40" } ] }
Send Audio Data
This is a request to send speech from the client to the API server.
Each request interval for submitting data is 240 milliseconds※.
Please ensure that the response contains no errors and before submitting the next audio request.
The first Send Audio Data must be performed within 1 second of receiving the response to Request to Start Speech Recognition .
※If the next request cannot be sent within the specified time due to network delay, please send it as soon as possible.
HTTP Endpoint
POST [API Base URL]/asr/v1/speech_recognition/[ASR Model ID]
Request Header
Key | Description |
---|---|
Connection |
Keep-Alive |
Content-Type |
application/octet-stream |
Unique-Id |
Unique-Id returned in the response header of Start Speech Recognition |
Authorization |
Bearer [Access Token] |
Cookie |
- token(A unique string used to identify the order of requests. Set as the token received in last response.) |
Request Body
Convert the audio data to one of the following formats and use the converted binary for this part.
※If the audio format is wav, please remove the header property and convert to Linear PCM or μ-Law format.
Format | Sample Rate[Hz] | Quantization[bit] | Channel | Byte Order | Audio length |
---|---|---|---|---|---|
Linear PCM |
more than Model's rate (8000 or 16000)※1 |
16 |
1 |
Little Endian |
240※2 |
μ-Law |
8000 |
8 |
1 |
Little Endian |
240※2 |
※1 Please note that we cannot guarantee correct operation for audio other than 8000, 11025, 16000, 22050, 32000, 44100, 48000, 88200, 96000[Hz]
※2 The time interval when sending the last speech request can be less than 240 milliseconds.
Sample Request
HTTP Header
Connection: Keep-Alive Content-Type: application/octet-stream Authorization: Bearer <Access Token> Cookie: GCLB=<GCLB that received in Speech Recognition Ready Response>;token=<token that received in last response>
HTTP Body
<Binary Audio Data>
Request to Stop Speech Recognition
This is the request to stop speech recognition from the client to the API server.
The API server returns 200(OK) after all speech recognition is complete.
Request to Stop Speech Recognition must be performed within 1 second of receiving the response to the last Send Audio Data .
HTTP Endpoint
POST [API Base URL]/asr/v1/speech_recognition/[ASR Model ID]
Request Header
Key | Description |
---|---|
Connection |
Keep-Alive |
Content-Type |
application/json; charset=UTF-8 |
Unique-Id |
Unique-Id returned in the response header of Start Speech Recognition |
Authorization |
Bearer [Access Token] |
Cookie |
- token(A unique string used to identify the order of requests. Set as the token received in last response.) |
Request Body
Key | Description | Valid Range |
---|---|---|
msg |
||
msgname |
message type |
stop |
Sample Request
HTTP Header
Connection: Keep-Alive Content-Type: application/json; charset=UTF-8 Authorization: Bearer <Access Token> Cookie: GCLB=<GCLB that received in Speech Recognition Ready Response>;token=<token that received in last response>
HTTP Body
{ "msg": { "msgname": "stop" } }
Request to Cancel Speech Recognition
This is the request to cancel speech recognition to the server.
The server will cancel speech recognition and return 200(OK).
Request to Cancel Speech Recognition must be performed within 1 second of receiving the response to the last Send Audio Data .
HTTP Endpoint
POST [API Base URL]/asr/v1/speech_recognition/[ASR Model ID]
Request Header
Key | Description |
---|---|
Connection |
Keep-Alive |
Content-Type |
application/json; charset=UTF-8 |
Unique-Id |
Unique-Id returned in the response header of Start Speech Recognition |
Authorization |
Bearer [Access Token] |
Cookie |
- token(A unique string used to identify the order of requests. Set as the token received in last response.) |
Request Body
Key | Description | Valid Range |
---|---|---|
msg |
||
msgname |
message type |
cancel |
Sample Request
HTTP Header
Connection: Keep-Alive Content-Type: application/json; charset=UTF-8 Authorization: Bearer <Access Token> Cookie: GCLB=<GCLB that received in Speech Recognition Ready Response>;token=<token that received in last response>
HTTP Body
{ "msg": { "msgname": "cancel" } }
Response
The HTTP response consists of a combination of the following server responses.
If there is more than one server response, an HTTP response containing JSON is returned with HTTP status code 200(OK).
If there are 0 server responses, an HTTP status code of 204(No Content) is returned.
Server Response Type | msgname | Description |
---|---|---|
started |
response to Speech Recognition Start Request |
|
speechStartDetected |
response to request after detection of speech start |
|
speechEndDetected |
response to request after detection of speech end |
|
recognized |
speech recognition results |
|
completed |
message when speech recognition ends or error occurs during speech recognition processing |
All server responses include msgname and uniqueId.
msgname represents the type of server response, and uniqueId is a unique identifier for each speech recognition.
Speech Recognition Ready Response
In response to Speech Recognition Start Request, this message is sent from the API server to the client to notify that the server is ready to receive audio data.
Response Header
Key | Description |
---|---|
Content-Type |
application/json; charset=UTF-8 |
Set-Cookie |
- token(A unique string used to identify the order of requests. ) |
Response Body
Key | Description | Remarks |
---|---|---|
msg |
||
msgname |
message type |
started |
uniqueId |
unique identifier for each speech recognition |
uniqueId is required for "Send Audio Data", "Request to Stop Speech Recognition" and "Request to Cancel Speech Recognition" |
Response Sample
[ { "msg": { "msgname": "started", "uniqueId": "3bfbe5de-eee7-4824-a661-3750d8cb9328" } } ]
Detect Speech Start Response
This message is returned when the start of an utterance is detected from sent audio.
Response Header
Key | Description |
---|---|
Content-Type |
application/json; charset=UTF-8 |
Set-Cookie |
token(A unique string used to identify the order of requests. ) |
Response Body
Key | Description | Remarks |
---|---|---|
msg |
||
msgname |
message type |
speechStartDetected |
uniqueId |
unique identifier for each speech recognition |
uniqueId is required for "Send Audio Data", "Request to Stop Speech Recognition" and "Request to Cancel Speech Recognition" |
timeinfo |
||
startDetectTime |
start detect time[ms] |
time from beginning of audio to speech start |
Response Sample
[ { "msg" : { "msgname" : "speechStartDetected", "uniqueId" : "3bfbe5de-eee7-4824-a661-3750d8cb9328" }, "timeinfo" : { "startDetectTime" : 0 } } ]
Detect Speech End Response
This message is returned when the end of an utterance is detected from sent audio.
Response Header
Key | Description |
---|---|
Content-Type |
application/json; charset=UTF-8 |
Set-Cookie |
token(A unique string used to identify the order of requests. ) |
Response Body
Key | Description | Remarks |
---|---|---|
msg |
||
msgname |
message type |
speechEndDetected |
uniqueId |
unique identifier for each speech recognition |
uniqueId is required for "Send Audio Data", "Request to Stop Speech Recognition" and "Request to Cancel Speech Recognition" |
timeinfo |
||
endDetectTime |
start detect time[ms] |
time from beginning of audio to speech start |
Response Sample
[ { "msg" : { "msgname" : "speechEndDetected", "uniqueId" : "4b96875f-2137-48ed-8b49-1e20483a7c86" }, "timeinfo" : { "endDetectTime" : 3200 } } ]
Speech Recognition Result Response
This message is the speech recognition result.
Response Header
Key | Description |
---|---|
Content-Type |
application/json; charset=UTF-8 |
Set-Cookie |
token(A unique string used to identify the order of requests. ) |
Response Body
Key | Description | Remarks |
---|---|---|
msg |
||
msgname |
message type |
recognized |
uniqueId |
unique identifier for each speech recognition |
uniqueId is required for "Send Audio Data", "Request to Stop Speech Recognition" and "Request to Cancel Speech Recognition" |
result |
||
type |
Types of Recognition Result |
- Sequential Recognition Result |
sentence |
||
surface |
result text |
|
score |
score |
confidence of result (0-1 scale) |
startTime |
start time[s] |
time from beginning of audio to speech start |
endTime |
end time[s] |
time from beginning of audio to speech end |
reading |
reading of results |
baseParam.reading=true only |
Response Sample
Paramters Paramters Specified at Request to Start Speech Recognition
baseParam.filler: false(default) baseParam.reading: false(default) baseParam.delimiter: true(default) baseParam.punctuation: false(default) recognizeParameter.maxResults: 1(default)
Response
{ "msg": { "msgname": "recognized", "uniqueId": "49bbc297-6a8a-4354-9679-2866cc27385a" }, "result": { "type": 1, "sentence": [ { "surface": "これ は テスト 用 の 音声ファイル です", "score": 0.851436, "startTime": 0, "endTime": 2.99 } ] } }
Response Sample
filler=true, reading=true, delimiter=false, punctuation=true, maxResults=2
Paramters Paramters Specified at Request to Start Speech Recognition
baseParam.filler: true baseParam.reading: true baseParam.delimiter: false baseParam.punctuation: true recognizeParameter.maxResults: 2
Response
{ "msg": { "msgname": "recognized", "uniqueId": "a6342b20-6b0d-41b4-9c71-86af4f123369" }, "result": { "type": 1, "sentence": [ { "surface": "[えーと]、これはテスト用の音声ファイルです", "score": 0.851436, "startTime": 0, "endTime": 2.99, "reading": "エット、コレワテストヨウノオンセイファイルデス" }, { "surface": "[えーと]。これはテスト用の音声ファイルです", "score": 0.532213, "startTime": 0, "endTime": 2.99, "reading": "エット。コレワテストヨウノオンセイファイルデス" } ] } }
Speech Recognition End Response
This message is returned when speech recognition is completed.
This message is also returned if an error occurs during the speech recognition process.
Response Header
Key | Description |
---|---|
Content-Type |
application/json; charset=UTF-8 |
Set-Cookie |
token(A unique string used to identify the order of requests. ) |
Response Body
Key | Description | Remarks |
---|---|---|
msg |
||
msgname |
message type |
completed |
uniqueId |
unique identifier for each speech recognition |
uniqueId is required for "Send Audio Data", "Request to Stop Speech Recognition" and "Request to Cancel Speech Recognition" |
cause |
reason for stop |
one of the following |
errorinfo |
||
code |
error code |
|
message |
error message |
|
level |
error level |
one of the following |
detail |
more information about the error |
※This is a stop factor that does not normally occur. When it occurs, please confirm that recognizeParameter.enableContinuous is set properly at the time of Request to Start Speech Recognition.
Response Sample
[ { "msg" : { "msgname" : "completed", "uniqueId" : "4b96875f-2137-48ed-8b49-1e20483a7c86", "cause" : "STOP" } } ]
Error Code
Troubleshooting for Request sent
If the following error occurs, please try your request again after taking the actions indicated.
Note that in the case of errors in Speech Recognition from Stream API, restart from Request to Start Speech Recognition . You don't need to Request to Stop Speech Recognition or Request to Cancel Speech Recognition.
If the error persists, please contact us using Contact Us.
code | message | detail | Description and Solution |
---|---|---|---|
410 |
Invalid Parameter |
msg.msgname is invalid -> XXX. |
Check msgname. |
410 |
Invalid Parameter |
param.baseParam.samplingRate is invalid -> XXX and over. |
Check that the sampling rate is higher than the model bandwidth. |
410 |
Invalid Parameter |
param.baseParam.samplingRate is invalid -> The sampling rate must be 8000 Hz. |
Check that the sampling rate is 8000 Hz. |
411 |
Invalid State |
Invalid Unique ID |
Check the order in which the speech recognition API is called. |
412 |
Interval Too Brief |
Audio transmission interval is too short. Set the transmission interval of audio correctly. |
|
450 |
Invalid Token |
token Error |
Cookie token (not the Access Token) is invalid. Please make a request after receiving a response. |
550 |
No Resource |
VRG_RESPONSE_SERVICE_UNAVAILABLE |
Check that ASR Domain id is correct. If the ASR Domain ID is correct, API access may be congested. Please wait a while and try again. |
552 |
Network Error |
Network |
Check that the request has been made within the specified time after receiving the response. |
600 |
Internal Error |
Check that the request has been made within the specified time after receiving the response. |
|
651 |
Session Timeout |
Check the API call order and call interval. |
Troubleshooting for temporary dictionary
If the following error occurs, please try your request again after taking the actions indicated.
Note that in the case of errors in Speech Recognition from Stream API, restart from Request to Start Speech Recognition .
You don't need to Request to Stop Speech Recognition or Request to Cancel Speech Recognition.
If the error persists, please contact us using Contact Us.
code | message | detail | Solution |
---|---|---|---|
410 |
Invalid Parameter |
Invalid Parameter -> List is null |
The notation and the reading is missing |
410 |
Invalid Parameter |
Cascade words exceeded 1000 |
Reduce the additional words in the temporary dictionary to 1000 lines or less. |
410 |
Invalid Parameter |
Surface empty |
Write the notation. |
410 |
Invalid Parameter |
Reading empty |
Write the reading. |
410 |
Invalid Parameter |
Invalid domainid |
Check that ASR Domain id is correct. |
410 |
Invalid Parameter |
Invalid Model Name |
Check that ASR Model id is correct. |
410 |
Invalid Parameter |
Prob illegal |
Specify the weight as an integer between 1 and 100, inclusive. |
410 |
Invalid Parameter |
Surface illegal |
Check that the character string can be set as a notation. |
410 |
Invalid Parameter |
Reading illegal |
Check that the character string can be set as a reading. |
410 |
Invalid Parameter |
Surface too long |
Please ensure that the total of size of the notation and reading in in 251 bytes or less. |
Please contact us
If the following error occurs, please contact us using Contact Us.
Error Code | Message |
---|---|
500 |
Internal Error |
510 |
Out Of Memory |
551 |
Recognition Timeout |
553 |
Network Timeout |
601 |
Recognition Converter Error |
610 |
Out Of Memory |
611 |
Invalid License |
612 |
Invalid Config |
650 |
No Resource |
690 |
External Command Execute Failed |
691 |
External Command Fatal |
692 |
External Command Error |
693 |
External Command Warn |
3.Update Speech Recognition Dictionary
Japanese model only
For adding words to the default dictionary.
A dictionary must be registered for each model.
Note that previously added dictionary will be overwritten by this call.
Request
HTTP Endpoint
POST [API Base URL]/asr/v1/speech_words/[ASR Model ID]/upload?domainid=[ASR Domain ID]
Request Header
You need to send a multipart form.
Define a boundary delimiter and indicate it as boundary in your request header.
Key | Description |
---|---|
Content-Type |
multipart/form-data; boundary=<Boundary Delimiter> |
Authorization |
Bearer [Access Token] |
Request Body
Include Speech Recognition Dictionary (Below) in the request body.
Part Type | Required | Name | Content-Type |
---|---|---|---|
Dictionary |
Required |
cascadeword |
text/plain; charset=UTF-8 |
Speech Recognition Dictionary
Write Notation, Horizontal Tab and Reading on each line.
<HYOKI><HT><YOMI> <HYOKI><HT><YOMI> ... <HYOKI><HT><YOMI>
When specifying the weight of word※1, describe it as follows. Weight can be specified for each word.
<HYOKI><HT><YOMI><HT><PROB> <HYOKI><HT><YOMI> ... <HYOKI><HT><YOMI><HT><PROB>
Key | Description | Range | Required |
---|---|---|---|
HYOKI |
Notation※2 |
Character string that does not contain |, /, :, ;, [, ], , " and is not empty |
Required |
YOMI |
Reading※2 |
Full-width katakana(Annexed Table) |
Required |
PROB |
weight of word※1 |
Integer value from 1 to 100(default: 30) |
Optional |
※1 Please ensure that the total of size of the notation and reading in in 251 bytes or less.
※2 Use this when you want to add weight to registered words.
By setting a value greater than 30, you will be setting a weight greater than the default user dictionary.
By setting a value smaller than 30, you will be setting a weight lower than the default user dictionary.
Speech Recognition Dictionary Sample
エヌ・ティ・ティ・コミュニケーションズ株式会社 エヌティティコミュニケーションズカブシキガイシャ COTOHA コトハ 20
Sample Request
HTTP Header
Content-Type: multipart/form-data; boundary=<境界文字列> Authorization: Bearer <Access Token>
HTTP Body
--<境界文字列> Content-Disposition: form-data; name="cascadeword"; filename="sample.tsv" Content-Type: text/plain エヌ・ティ・ティ・コミュニケーションズ株式会社 エヌティティコミュニケーションズカブシキガイシャ COTOHA コトハ 20 --<境界文字列>--
cURL
curl -H "Authorization:Bearer <Access Token>" -X POST -F cascadeword=@<音声認識ユーザ辞書リストを記載したtsvファイル>; [API Base URL]/asr/v1/speech_words/[ASR Model ID]/upload?domainid=[ASR Domain ID]
Response
The specified notation, the specified reading, M(fixed), and weight of word are returned.
M is automatically assigned by the server, so you usually do not need to be concerned about it. If weight of word is not specified, the default value of 30 will be returned.
Response Header
Key | Description |
---|---|
Content-Type |
multipart/form-data; boundary=<Boundary Delimiter> |
Response Sample
--<Boundary Delimiter> Content-Type: text/plain Content-Disposition: form-data; name="status" code : 200 message : OK detail : success --<Boundary Delimiter> Content-Type: text/plain Content-Disposition: form-data; name="cascadeword" エヌ・ティ・ティコミュニケーションズ株式会社 エヌティティコミュニケーションズカブシキガイシャ M 30 COTOHA コトハ M 20 --<Boundary Delimiter>--
Error Code
Please review your request
If the following error occurs, please try your request again after taking the actions indicated. If the error persists, please contact us from Contact Us.
code | message | detail | Solution |
---|---|---|---|
410 |
Invalid Parameter |
Invalid Parameter -> List is null |
Write the notation and the reading. |
410 |
Invalid Parameter |
Invalid Parameter -> List Exceed 5000 lines |
In the speech recognition dictionary, specify additional words in 1000 lines or less. |
410 |
Invalid Parameter |
Surface empty |
Write the notation. |
410 |
Invalid Parameter |
Reading empty |
Write the reading. |
410 |
Invalid Parameter |
Invalid domainid |
Check that ASR Domain id is correct. |
410 |
Invalid Parameter |
Invalid Model Name |
Check that ASR Model id is correct. |
410 |
Invalid Parameter |
Prob illegal |
Specify the weight as an integer between 1 and 100, inclusive. |
410 |
Invalid Parameter |
Surface illegal |
Check that the character string can be set as the notation. |
410 |
Invalid Parameter |
Reading illegal |
Check that the character string can be set as the reading. |
410 |
Invalid Parameter |
Surface too long |
Please specify the total of notation and reading in 251 bytes or less. |
Please contact us
If the following error occurs, please contact us using Contact Us.
code | message | detail |
---|---|---|
410 |
Invalid Parameter |
Upload Error |
410 |
Invalid Parameter |
Download Error |
600 |
Internal Error |
- |
4.Delete Speech Recognition Dictionary
Japanese models only
For deleting registered dictionary.
The registered dictionaries should be deleted individually for each model.
Request
HTTP Endpoint
GET [API Base URL]/asr/v1/speech_words/[ASR Model ID]/clear?domainid=[ASR Domain ID]
Request Header
Key | Description |
---|---|
Authorization |
Bearer [Access Token] |
Sample Request
HTTP Header
Authorization: Bearer <Access Token>
cURL
curl -H "Authorization:Bearer <Access Token>" [API Base URL]/asr/v1/speech_words/[ASR Model ID]/clear?domainid=[ASR Domain ID]
Response
Response Header
Key | Description |
---|---|
Content-Type |
multipart/form-data; boundary=<Boundary Delimiter> |
Response Sample
--<Boundary Delimiter> Content-Type: text/plain Content-Disposition: form-data; name="status" code : 200 message : OK detail : success --<Boundary Delimiter>--
Error Code
Please review your request
If the following error occurs, please try your request again after taking the actions indicated. If the error persists, please contact us from Contact Us.
code | message | detail | Solution |
---|---|---|---|
410 |
Invalid Parameter |
Invalid domainid |
Check that ASR Domain id is correct. |
410 |
Invalid Parameter |
Invalid Model Name |
Check that ASR Model id is correct. |
Please contact us
If the following error occurs, please contact us from Contact Us
code | message | detail |
---|---|---|
410 |
Invalid Parameter |
Upload Error |
410 |
Invalid Parameter |
Download Error |
600 |
Internal Error |
- |
5.Get Speech Recognition Dictionary State
Japanese models only
API for checking if the dictionary data is reflected. For each model, it is possible to obtain whether the user dictionary has been updated.
Request
HTTP Endpoint
GET [API Base URL]/asr/v1/speech_words/[ASR Model ID]/isset?domainid=[ASR Domain ID]
Sample Request
HTTP Header
Authorization: Bearer <Access Token>
cURL
curl -H "Authorization:Bearer <Access Token>" [API Base URL]/asr/v1/speech_words/[ASR Model ID]/isset?domainid=[ASR Domain ID]
Response
If the user dictionary has been updated, true will be returned; if not completed, false will be returned.
Note that the response Content-Type differs depending on whether an error has occurred.
Response Header
Key | Description |
---|---|
Content-Type |
application/json |
Response Body
Key | Range |
---|---|
isSet |
true, false |
Response Sample
{ "isSet" : true }
Error Response
Response Header
Key | Description |
---|---|
Content-Type |
multipart/form-data; boundary=<Boundary Delimiter> |
Response Sample
--<Boundary Delimiter> Content-Type: text/plain Content-Disposition: form-data; name="status" code : 410 message : Invalid Parameter detail : Invalid domainid --<Boundary Delimiter>--
Error Code
Please review your request
If the following error occurs, please try your request again after taking the actions indicated. If the error persists, please contact us from Contact Us.
code | message | detail | Solution |
---|---|---|---|
410 |
Invalid Parameter |
Invalid domainid |
Check that ASR Domain id is correct. |
410 |
Invalid Parameter |
Invalid Model Name |
Check that ASR Model id is correct. |
Please contact us
If the following error occurs, please contact us from Contact Us
code | message | detail |
---|---|---|
410 |
Invalid Parameter |
Upload Error |
410 |
Invalid Parameter |
Download Error |
600 |
Internal Error |
- |
6.Download speech Recognition Dictionary
Japanese models only
API for downloading the last uploaded dictionary. It is possible to download the last uploaded dictionary for each model.
Request
HTTP Endpoint
GET [API Base URL]/asr/v1/speech_words/[ASR Model ID]/download?domainid=[ASR Domain ID]
Request Header
Key | Description |
---|---|
Authorization |
Bearer [Access Token] |
Sample Request
HTTP Header
Authorization: Bearer <Access Token>
cURL
curl -H "Authorization:Bearer <Access Token>" [API Base URL]/asr/v1/speech_words/[ASR Model ID]/download?domainid=[ASR Domain ID]
Response
The words in the last uploaded dictionary will be returned. Each line contains notation, reading, and weight of word.
Response Header
Key | Description |
---|---|
Content-Type |
multipart/form-data; boundary=<Boundary Delimiter> |
Response Sample
--<Boundary Delimiter> Content-Type: text/plain Content-Disposition: form-data; name="status" code : 200 message : OK detail : success --<Boundary Delimiter> Content-Type: text/plain Content-Disposition: form-data; name="cascadeword" エヌ・ティ・ティコミュニケーションズ株式会社 エヌティティコミュニケーションズカブシキガイシャ 30 COTOHA コトハ 30 --<Boundary Delimiter>--
Error Code
Please review your request
If the following error occurs, please try your request again after taking the actions indicated. If the error persists, please contact us from Contact Us.
code | message | detail | Solution |
---|---|---|---|
410 |
Invalid Parameter |
Invalid domainid |
Check that ASR Domain id is correct. |
410 |
Invalid Parameter |
Invalid Model Name |
Check that ASR Model id is correct. |
Please contact us
If the following error occurs, please contact us from Contact Us
code | message | detail |
---|---|---|
410 |
Invalid Parameter |
Upload Error |
410 |
Invalid Parameter |
Download Error |
600 |
Internal Error |
- |
Input/Output Item
List of Models
Model Name | ASR Model id |
---|---|
Japanese General Talk&Free(16kHz) |
ja-gen_tf-16 |
Japanese General Short&Formal(16kHz) |
ja-gen_sf-16 |
Japanese General Talk&Free(8kHz) |
ja-gen_tf-08 |
Japanese Telecommunications(8kHz) |
ja-mdl1_nrw-08 |
Japanese Insurance(8kHz) |
ja-mdl2_nrw-08 |
English General Native Short&Formal(16kHz) |
en_en-gen_sf-16 |
- Difference between Talk&Free and Short&Formal
- Talk&Free: This model is suitable for speech recognition that is freestyle, where you do not have an exact idea of what to say beforehand, where natural speech elements like hesitation and mispronunciations often occur.(e.g. meeting, chat, call center and customer service, etc.)
- Short&Formal: This model is suitable for speech recognition of audio with a single utterance in which you have an idea of what to say and is able to speak relatively clearly.(e.g. search queries, interactions with question and answer systems, etc.)
- Difference between 8kHz and 16kHz
- 8kHz: Recommended for speech over a telephone line.
- 16kHz: Recommended for other speech.
Text to Speech
Text to speech API consisting of 11 APIs methods.
Please note that this API is not available for use with the Developers account.
1.Speech synthesis
API for converting text input into audio data of natural human speech. The audio data is returned in a response.
2.Sequential speech synthesis
API for converting text input into audio data of natural human speech. The audio data is divided into chunks and returned.
3.Pronunciation analysis
API for converting plaintext input into pronunciation text. (Japanese language only)
The above two types of speech synthesis APIs can also use the pronunciation text as input.
Please refer to "Pronunciation text" in "Input/Output items" about pronunciation text.
4.Registering records in the word dictionary
API for registering a record that define how to pronounce the word in the word dictionary. You can use this API when the default pronunciation is unnatural. (Japanese language only)
5.Displaying records in the word dictionary
API for getting a list of records registered in the word dictionary. (Japanese language only)
6.Updating records in the word dictionary
API for updating a record registered in the word dictionary. (Japanese language only)
7.Deleting records in the word dictionary
API for deleting a record registered in the word dictionary. (Japanese language only)
8.Registering records in the sentence dictionary
API for registering a record that define how to pronounce a given sentence in the sentence dictionary. You can use this API when the default pronunciation is unnatural. How to pronounce is defined by pronunciation text. (Japanese language only)
9.Displaying records in the sentence dictionary
API for getting a list of records registered in the sentence dictionary. (Japanese language only)
10.Updating records in the sentence dictionary
API for updating a record registered in the sentence dictionary. (Japanese language only)
11.Deleting records in the sentence dictionary
API for deleting a record registered in the sentence dictionary. (Japanese language only)
Input/Output items (data specifications)
This is a list of specifications for some parameters when using the API.
Sample codes(github)
Sample codes for Java/Python/JavaScript/Node.js are available. Feel free to use them.
Recommendations for various cases?
- Want to convert text to synthetic speech audio.
Both of these APIs can be used.
1.Speech synthesis API
2.Sequential speech synthesis API
- Long texts; Long response times when converting to voice audio data.
You can speed up the response in a pseudo manner by using 2.Sequential speech synthesis API because the audio data is return from completed part.
- Want to know how the text is pronounced by the API.
You can visualize how to pronounce the text by converting the text to pronunciation text using 3. Pronunciation analysis API.
- The pronunciation is unnatural.
You can change the default pronunciation by registering words or sentences using 4. Registering records in the word dictionary API or 8.Registering records in the sentence dictionary API.
For example, when you synthesize “なんでやねん”, “な” has an accent by default. However, if you want to synthesize it in a form close to Kansai dialect, you need to add an accent to “で”. In this case, the settings are as follows.
- When using 4.Registering records in the word dictionary
ナ'ンデヤネン → ナンデ'ヤネン
- When using 8.Registering records in the sentence dictionary
ナンデヤネン[.01] → ナンデヤネン[.03]
- The registered words or sentences is not reflected, or you want to know what words or sentences is registered.
Please confirm the registered words and sentences by using 5.Displaying records in the word dictionary API or 9.Displaying records in the sentence dictionary
- Want to revise or delete the records registered in the dictionary.
You can revise the records by using 6.Updating records in the word dictionary API or 10.Updating records in the sentence dictionary API.
You can also delete the records by using 7.Deleting records in the word dictionary API or 11.Deleting records in the sentence dictionary API.
- Want to know the values that can be specified as a speaker and part of speech or want to know the details of the pronunciation text.
You can check the detailed items and specifications of some parameters in "Input/Output items (data specifications)".
- Want some sample codes to use Text to Speech API.
Here (github) is some sample codes. Please use them.
1.Speech synthesis
An API for converting text input into audio data of natural human speech.
The audio data is returned in a response.
Note: When you want to convert a long text input into audio data but do not want to wait for a long response or the full completely synthesized data, please use 2.Sequential speech synthesis API.
Request
HTTP Endpoint
POST [API Base URL]/tts/v1/tts
Request Header
Key Name | Required | Description |
---|---|---|
Content-Type |
Required |
application/json; charset=UTF-8 |
Authorization |
Required |
Access token |
Accept |
Any |
MIME Type of received data Specify one of the following two. audio/wav: Wave format audio data text/plain: Base64 encoded audio data *When omitted, audio/wav is specified. |
Request Body
When the parameter is omitted, default values are specified for optional parameters.
*Required parameters must be specified.
Key Name | Data Type | Required | Default Value | Description |
---|---|---|---|---|
text |
string |
Required |
- |
Target text Specify the text to be synthesized. 【Limitations】 The maximum number of characters differs for each text type. - plain text:500[characters] - pronunciation text:1200[characters] *If the pronunciation text exceeds 1200 characters, the parameter will be considered as exceeded even if the number of characters in plain text is not exceeded. It is necessary to describe in the format defined for each text type. Please refer to "Target text" in "Input/Output items" about each text type format. |
textType |
string |
Any |
normal |
Text type Specify the text type of the target text - normal:plain text - utterance:pronunciation text 【Limitations】 You can specify utterance only when you use Japanese speakerId. |
speakerId |
string |
Required |
- |
Speaker ID Specify the speaker model id of the speech synthesizer. 【Limitations】 Please refer to "List of speaker IDs" in "Input/Output items" for the speakerId that you can specify. |
speechRate |
number(fraction) |
Any |
1 |
Speed of the synthesized speech - Smaller value:Slower - Lager value:Faster 【Limitations】 - Value range:0.50~2.00 - Step size:0.01 |
powerRate |
number(fraction) |
Any |
1 |
Volume of the synthesized speech - Smaller value:Lower volume - Larger value:Larger volume 【Limitations】 - Value range:0.00~5.00 - Step size:0.01 |
intonation |
number(interger) |
Any |
10 |
Range on the intonation of the synthesized speech - Smaller value:Lower range - Larger value:Higher range 【Limitations】 - Value range:1~20 - Step size:1 |
pitch |
number(interger) |
Any |
12 |
Pitch of the synthesized speech - Smaller value:Lower pitch - Larger value:Higher pitch 【Limitations】 - Value range:1~20 - Step size:1 |
Request sample(cURL)
- With only the required parameters
curl -o result.wav -X POST -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Bearer [access token]" -d '{"text": "今日は晴れです。", "speakerId": "ja_JP-M-S0001-T001-E01-SR0"}' [API Base URL]/tts/v1/tts
- All parameters
curl -o result.wav -X POST -H "Content-Type: application/json;charset=UTF-8" -H "Accept: text/plain" -H "Authorization: Bearer [access token]" -d '{"text": "キョーワ[,01]ハレデス^[.02]", "textType": "utterance", "speakerId": " ja_JP-M-S0001-T001-E01-SR0", "speechRate": "1.25", "powerRate": "2.0", "intonation": 5, "pitch": 15 }' [API Base URL]/tts/v1/tts
Response
The sampling rate of the returned audio data is 22,050Hz.
Response Header
Key Name | Description |
---|---|
Content-Type |
MIME Type of received data Following values are returned depending on the value set in Accept in the request header. - audio/wav:audio/wav - text/plain:text/plain |
Response Body
Data Type | Description |
---|---|
binary or string |
Audio data Following values are returned depending on the value set in Accept in the request header. - audio/wav:Wave format audio binary - text/plain:Base64 encoded text |
Response Sample
音声データ(バイナリorテキスト)
Response on Error
Response Header
Key Name | Description |
---|---|
Content-Type |
MIME Type of received data application/json |
Response Body
Key Name | Data Type | Description |
---|---|---|
code |
string |
Error code Used when making inquiries. |
detail |
string |
Error details Information about the error response. Please refer to here for details. |
HTTP Status Code
Response Code | Description and Solutions |
---|---|
400 Bad Request |
The input parameter is invalid. Please refer to the details of the key pairs in the response body and here. Then, specify the correct parameter. *Examples of invalid input parameters include: - The value of the parameter is out of range. - A single-byte character is used in a parameter that can only use double-byte characters. - A parameter that does not exist is specified. |
401 Unauthorized |
Access Token is invalid(expiration etc.). Please specify a valid Access Token. |
404 Not Found |
The requested resource cannot be found. Please confirm URL and HTTP method. |
406 Not Acceptable |
Accept in the request header is invalid. Please confirm the content of it. |
413 Request Entity Too Large |
Request was rejected because the size of the entire request data exceeded the upper limit. Please confirm the request data. |
415 Unsupported Media Type |
Content-Type is invalid. Please confirm Content-Type in the request header. |
500 internal Server Error |
An error occurred inside the server. Please confirm the content of the request. If the problem persists, please contact us through contact form |
2.Sequential speech synthesis
An API for converting text input into audio data of natural human speech.The audio data is divided into chunks and returned.Since responses are returned in order from the one that has been synthesized, it is convenient when you want to play the audio data by streaming.
Request
HTTP Endpoint
POST [API Base URL]/tts/v1/sequential_tts
Request Header
Key Name | Required | Description |
---|---|---|
Content-Type |
Required |
MIME Type of sent data application/json; charset=UTF-8 |
Authorization |
Required |
Access token Specify in the following format. Bearer [Access Token] |
Accept |
Any |
MIME Type of received data Specify one of the following two. - audio/L16:16bit linear PCM Raw format monaural audio data - text/plain:Base64 encoded audio data *When omitted, audio/L16 is specified. |
Connection |
Required |
Maintaining TCP connection Keep-Alive |
Request Body
When the parameter is omitted, default values are specified for optional parameters.
*Required parameters must be specified.
Key Name | Data Type | Required | Default Value | Description |
---|---|---|---|---|
text |
string |
Required |
- |
target text Specify the text to be synthesized. 【Limitations】 The maximum number of characters differs for each text type. - plain text:500[characters] - pronunciation text:1200[characters] *If the pronunciation text exceeds 1200 characters, the parameter will be considered as exceeded even if the number of characters in plain text is not exceeded. It is necessary to describe in the format defined for each text type. Please refer to "Target text" in "Input/Output items" about each text type format. |
textType |
string |
Any |
normal |
Text type Specify the text type of the target text. - normal:plain text - utterance:pronunciation text 【Limitations】 You can specify utterance only when you use Japanese speakerId. |
speakerId |
string |
Required |
- |
Speaker ID Specify the speaker model id of the speech synthesizer. 【Limitations】 Please refer to "List of speaker IDs" in "Input/Output items" for the speakerId that you can specify. |
speechRate |
number(fraction) |
Any |
1.00 |
Speed of the synthesized speech - Smaller value:Slower - Lager value:Faster 【Limitations】 - Value range:0.50~2.00 - Step size:0.01 |
powerRate |
number(fraction) |
Any |
1.00 |
Volume of the synthesized speech - Smaller value:Lower volume - Larger value:Larger volume 【Limitations】 - Value range:0.00~5.00 - Step size:0.01 |
intonation |
number(interger) |
Any |
10 |
Range on the intonation of the synthesized speech - Smaller value:Lower range - Larger value:Higher range 【Limitations】 - Value range:1~20 - Step size:1 |
pitch |
number(interger) |
Any |
12 |
Pitch of the synthesized speech - Smaller value:Lower pitch - Larger value:Higher pitch 【Limitations】 - Value range:1~20 - Step size:1 |
Request sample(cURL)
- With only the required parameters
curl -o result.raw -X POST -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Bearer [access token]" -d '{"text": "今日は晴れです。", "speakerId": "ja_JP-M-S0001-T001-E01-SR0"}' [API Base URL]/tts/v1/sequential_tts
- All parameters
curl -o result.wav -X POST -H "Content-Type: application/json;charset=UTF-8" -H "Accept: text/plain" -H "Authorization: Bearer [access token]" -d '{"text": "キョーワ[,01]ハレデス^[.02]", "textType": "utterance", "speakerId": " ja_JP-M-S0001-T001-E01-SR0", "speechRate": "1.25", "powerRate": "2.0", "intonation": 5, "pitch": 15 }' [API Base URL]/tts/v1/sequential_tts
Response
The sampling rate of the returned audio data is 22,050Hz.
Response Header
Key Name | Description |
---|---|
Content-Type |
MIME Type of received data Following values are returned depending on the value set in Accept in the request header. - audio/L16:audio/L16 - text/plain:text/plain |
Transfer-Encoding |
Encoding format used for transfer chunked |
Response Body
Key Name | Data Type | Description |
---|---|---|
- |
Number (Integer) |
Audio data size Number of bytes of audio data |
- |
binary or string |
Audio data Following values are returned depending on the value set in Accept in the request header. - audio/L16:16bit linear PCM Raw format monaural audio binary - text/plain:Base64 encoded audio data |
Response Sample
チャンク1の音声データサイズ チャンク1音声データ(バイナリorテキスト) チャンク2の音声データサイズ チャンク2の音声データ(バイナリorテキスト) ・・・ チャンクNの音声データサイズ チャンクNの音声データ(バイナリorテキスト) 0
Response on Error
Response Header
Key Name | Description |
---|---|
Content-Type |
MIME Type of received data application/json |
Response Body
Key Name | Data Type | Description |
---|---|---|
code |
string |
Error code Used when making inquiries. |
detail |
string |
Error details Information about the error response. Please refer to here for details. |
HTTP Status Code
Response Code | Description and Solutions |
---|---|
400 Bad Request |
The input parameter is invalid. Please refer to the details of the key pairs in the response body and here. Then, specify the correct parameter. *Examples of invalid input parameters include: - The value of the parameter is out of range. - A single-byte character is used in a parameter that can only use double-byte characters. - A parameter that does not exist is specified. |
401 Unauthorized |
Access Token is invalid(expiration etc.). Please specify a valid Access Token. |
404 Not Found |
The requested resource cannot be found. Please confirm URL and HTTP method. |
406 Not Acceptable |
Accept in the request header is invalid. Please confirm the content of it. |
413 Request Entity Too Large |
Request was rejected because the size of the entire request data exceeded the upper limit. Please confirm the request data. |
415 Unsupported Media Type |
Content-Type is invalid. Please confirm Content-Type in the request header. |
500 internal Server Error |
An error occurred inside the server. Please confirm the content of the request. If the problem persists, please contact us through contact form |
3.Pronunciation analysis
An API for converting plain text input into pronunciation text. (Japanese language only)
This pronunciation text can also be used as input in 1.Speech synthesis and 2.Sequential speech synthesis.
*For pronunciation text, please check "Pronunciation text" in "Input/Output items".
Request
HTTP Endpoint
POST [API Base URL]/tts/v1/text_analyze
Request Header
Key Name | Required | Description |
---|---|---|
Content-Type |
Required |
MIME Type of sent data application/json; charset=UTF-8 |
Authorization |
Required |
Access token Specify in the following format. Bearer [Access Token] |
Request Body
Key Name | Data Type | Required | Default Value | Description |
---|---|---|---|---|
text |
string |
Required |
- |
Text to be analyzed Specify plain text to be analyzed. 【Limitations】 Maximum number of characters:500[characters] |
lang |
string |
Required |
- |
Language type Specify language type of the text to be analyzed. - ja_JP:Japanese 【Limitations】 Only ja_JP can be specified. |
Request sample(cURL)
curl -X POST -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Bearer [access token]" -d '{"text": "今日は晴れです。", "lang": " ja_JP"}' [API Base URL]/tts/v1/text_analyze
Response
Response Header
Key Name | Description |
---|---|
Content-Type |
MIME Type of received data text/plain |
Response Body
Key Name | Data Type | Description |
---|---|---|
- |
string |
pronunciation text For pronunciation text, please refer to "Pronunciation text" in "Input/Output items". |
Response Sample
キョーワ[,01]ハレデス^[.02]
Response on Error
Response Header
Key Name | Description |
---|---|
Content-Type |
MIME Type of received data application/json |
Response Body
Key Name | Data Type | Description |
---|---|---|
code |
String |
Error code Used when making inquiries. |
detail |
String |
Error details Information about the error response. Please refer to here for details. |
HTTP Status Code
Response Code | Description and Solutions |
---|---|
400 Bad Request |
The input parameter is invalid. Please refer to the details of the key pairs in the response body and here. Then, specify the correct parameter. *Examples of invalid input parameters include: - The value of the parameter is out of range. - A single-byte character is used in a parameter that can only use double-byte characters. - A parameter that does not exist is specified. |
401 Unauthorized |
Access Token is invalid(expiration etc.). Please specify a valid Access Token. |
404 Not Found |
The requested resource cannot be found. Please confirm URL and HTTP method. |
406 Not Acceptable |
Accept in the request header is invalid. Please confirm the content of it. |
413 Request Entity Too Large |
Request was rejected because the size of the entire request data exceeded the upper limit. Please confirm the request data. |
415 Unsupported Media Type |
Content-Type is invalid. Please confirm Content-Type in the request header. |
500 internal Server Error |
An error occurred inside the server. Please confirm the content of the request. If the problem persists, please contact us through contact form |
4.Registering records in the word dictionary
An API for registering a record that defines how the engine should pronounce the word in the word dictionary. (Japanese Language only)
This API is useful when the default pronunciation is unnatural.
*The maximum number of records that can be registered is 5000 records.
Request
HTTP Endpoint
POST [API Base URL]/tts/v1/dicts/word_dicts/{lang}
URI parameter
Key Name | Data Type | Required | Default Value | Description |
---|---|---|---|---|
lang |
string |
Required |
- |
Language type - ja_JP:Japanese |
Request Header
Key Name | Required | Description |
---|---|---|
Content-Type |
Required |
MIME Type of sent data application/json; charset=UTF-8 |
Authorization |
Required |
Access token Specify in the following format. Bearer [Access Token] |
Request Body
Key Name | Data Type | Required | Default Value | Description |
---|---|---|---|---|
target |
string |
Required |
- |
Word Specify the word to be registered in the dictionary. 【Limitations】 Maximum number of characters:45[characters] Please refer to "Word" in "Input/Output items" for the format of the word. Duplicate registration of combinations of notation and parts of speech is not possible. |
partOfSpeech |
string |
Required |
- |
Part of speech of the word Specify the part of speech of the word. 【Limitations】 Please refer to "Part of speech that can be specified" in "Input/Output items" for the part of speech that can be specified. |
pronunciation |
string |
Required |
- |
Pronunciation of the word Specify the pronunciation of the word. 【Limitations】 Maximum number of characters:45[characters] An empty string ("pronunciation":"") can be specified. If an empty string is specified, the speech for the word is not synthesized. Please refer to "Pronunciation and Accent of the word" in "Input/Output items" for the pronunciation of the word. |
Request sample(cURL)
curl -X POST -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Bearer [access token]" -d '{"target": "辞書/データ/1", "partOfSpeech": "普通名詞", "pronunciation": "ジショ/デ'\''ータ/イチ"}' [API Base URL]/tts/v1/dicts/word_dicts/ja_JP
Response
Response Header
Key Name | Description |
---|---|
Content-Type |
MIME Type of received data application/json |
Location |
Created resource path URI for the created record |
Response Body
Key Name | Data Type | Description |
---|---|---|
dictDataId |
number(integer) |
ID of the registered record |
target |
string |
The registered word |
partOfSpeech |
string |
The part of speech of the word |
pronunciation |
string |
The pronunciation of the word |
createdAt |
string |
The created date of the registered word This is expressed in RFC3339 format. |
updatedAt |
string |
The updated date of the registered word This is expressed in RFC3339 format. |
Response Sample
{ "dictDataId": 1, "target": "辞書/データ/1", "partOfSpeech": "普通名詞", "pronunciation": "ジショ/デ'ータ/イチ", "createdAt": "2019-07-01T11:25:49+09:00", "updatedAt": "2019-07-01T11:25:49+09:00" }
Response on Error
Response Header
Key Name | Description |
---|---|
Content-Type |
MIME Type of received data application/json |
Response Body
Key Name | Data Type | Description |
---|---|---|
code |
String |
Error code Used when making inquiries. |
detail |
String |
Error details Information about the error response. Please refer to here for details. |
HTTP Status Code
Response Code | Description and Solutions |
---|---|
400 Bad Request |
The input parameter is invalid. Please refer to the details of the key pairs in the response body and here. Then, specify the correct parameter. *Examples of invalid input parameters include: - The value of the parameter is out of range. - A single-byte character is used in a parameter that can only use double-byte characters. - A parameter that does not exist is specified. |
401 Unauthorized |
Access Token is invalid(expiration etc.). Please specify a valid Access Token. |
404 Not Found |
The requested resource cannot be found. Please confirm URL and HTTP method. |
406 Not Acceptable |
Accept in the request header is invalid. Please confirm the content of it. |
409 Conflict |
The record you are trying to create is in conflict. Please check the contents of the record to be created or the record that has been created. |
413 Request Entity Too Large |
Request was rejected because the size of the entire request data exceeded the upper limit. Please confirm the request data. |
415 Unsupported Media Type |
Content-Type is invalid. Please confirm Content-Type in the request header. |
500 internal Server Error |
An error occurred inside the server. Please confirm the content of the request. If the problem persists, please contact us through contact form |
5.Displaying records in the word dictionary
An API for getting a list of records registered in the word dictionary. (Japanese language only)
Request
HTTP Endpoint
GET [API Base URL]/tts/v1/dicts/word_dicts/{lang}?{target, dictDataId, page, limit, sort}
URI parameter
Key Name | Data Type | Required | Default Value | Description |
---|---|---|---|---|
lang |
string |
Required |
- |
Language type - ja_JP:Japanese |
target |
string |
Any |
- |
Word Specify the word to be acquired Partial match search is possible. 【Limitations】 Maximum number of characters:45[characters] *If an empty string is specified, target is ignored. |
dictDataId |
number(integer) |
Any |
- |
ID of the record Specify the ID of the record to be acquired. If dictDataId is specified, parameters other than the required parameters are ignored. *If an empty string is specified, dictDataId is ignored. If dictDataId that does not have the corresponding record is specified, an empty array is returned. |
page |
number(integer) |
Any |
1 |
Reference page number Specify the page number that you want in the list of the retrieved records. 【Limitations】 Value range:1~5000 *If there are no records in the page, an empty array is returned. |
limit |
number(integer) |
Any |
25 |
Number of acquisitions per page Specify the number of retrieved records per page. 【Limitations】 Value range:1~5000 *If the number of registered records is less than the "limit" value, all records is returned on the first page. |
sort |
string |
Any |
createdAt |
How to sort Specify the sort order of the records to be acquired. Sort items that can be specified are as follows. - target:word - pronunciation:pronuncitaion of the word - createdAt:created date of the record - updatedAt:updated date of the record Although the default is ascending order, you can specify descending order by adding a half-width hyphen (-) before each sort item. When sorting by multiple items, specify them by separating with half-width commas. for example:sort=target,-createdAt |
Request Header
Key Name | Required | Description |
---|---|---|
Content-Type |
Required |
MIME Type of sent data application/json; charset=UTF-8 |
Authorization |
Required |
Access token Specify in the following format. Bearer [Access Token] |
Request sample(cURL)
- With only the required parameters
curl -H "Authorization: Bearer [access token]" [API Base URL]/tts/v1/dicts/word_dicts/ja_JP
- All parameters
curl -H "Authorization: Bearer [access token]" "[API Base URL]/tts/v1/dicts/word_dicts/ja_JP?target=辞書&page=1&limit=20&sort=target,-pronunciation,-createdAt,updatedAt"
Response
Response Header
Key Name | Description |
---|---|
Content-Type |
MIME Type of received data application/json |
X-Total-Count |
The count of the targets that hits the criteria |
Response Body
Key Name | Data Type | Description |
---|---|---|
dictData |
array[object] |
An array of elements containing the following keys |
dictDataId |
number(integer) |
ID of the acquired record |
target |
string |
The acquired word |
partOfSpeech |
string |
The part of speech of the acquired word |
pronunciation |
string |
The pronunciation of the acquired word |
createdAt |
string |
The created date of the acquired word This is expressed in RFC3339 format. |
updatedAt |
string |
The updated date of the acquired word This is expressed in RFC3339 format. |
Response Sample
{ dictData: [ { "dictDataId": 1, "target": "辞書/データ/1", "partOfSpeech": "普通名詞", "pronunciation: "ジショ/デ'ータ/イチ", "createdAt": "2019-07-01T11:25:49+09:00", "updatedAt": "2019-07-01T11:25:49+09:00" }, { "dictDataId": 2, "target": "辞書/データ/2", "partOfSpeech": "固有名詞", "pronunciation: "ジショ/デ'ータ/ニ", "createdAt": "2019-07-01T11:25:50+09:00", "updatedAt": "2019-07-01T11:25:50+09:00" } ] }
Response on Error
Response Header
Key Name | Description |
---|---|
Content-Type |
MIME Type of received data application/json |
Response Body
Key Name | Data Type | Description |
---|---|---|
code |
String |
Error code Used when making inquiries. |
detail |
String |
Error details Information about the error response. Please refer to here for details. |
HTTP Status Code
Response Code | Description and Solutions |
---|---|
400 Bad Request |
The input parameter is invalid. Please refer to the details of the key pairs in the response body and here. Then, specify the correct parameter. *Examples of invalid input parameters include: - The value of the parameter is out of range. - A single-byte character is used in a parameter that can only use double-byte characters. - A parameter that does not exist is specified. |
401 Unauthorized |
Access Token is invalid(expiration etc.). Please specify a valid Access Token. |
404 Not Found |
The requested resource cannot be found. Please confirm URL and HTTP method. |
406 Not Acceptable |
Accept in the request header is invalid. Please confirm the content of it. |
413 Request Entity Too Large |
Request was rejected because the size of the entire request data exceeded the upper limit. Please confirm the request data. |
415 Unsupported Media Type |
Content-Type is invalid. Please confirm Content-Type in the request header. |
500 internal Server Error |
An error occurred inside the server. Please confirm the content of the request. If the problem persists, please contact us through contact form |
6.Updating records in the word dictionary
An API for updating the registered record. (Japanese language only)
Request
HTTP Endpoint
PUT [API Base URL]/tts/v1/dicts/word_dicts/{lang}/{dictDataId}
URI parameter
Key Name | Data Type | Required | Default Value | Description |
---|---|---|---|---|
lang |
string |
Required |
- |
Language type - ja_JP:Japanese |
dictDataId |
number(integer) |
Required |
- |
ID of the record Specify the ID of the record to be updated. |
Request Header
Key Name | Required | Description |
---|---|---|
Content-Type |
Required |
MIME Type of sent data application/json; charset=UTF-8 |
Authorization |
Required |
Access token Specify in the following format. Bearer [Access Token] |
Request Body
Key Name | Data Type | Required | Default Value | Description |
---|---|---|---|---|
target |
string |
Any |
- |
Word Specify the word to be updated. 【Limitations】 Maximum number of characters:45[characters] Please refer to "Word" in "Input/Output items" for the format of the word. Duplicate registration of combinations of notation and parts of speech is not possible. |
partOfSpeech |
string |
Any |
- |
Part of speech of the word Specify the part of speech of the word. 【Limitations】 Please refer to "Part of speech that can be specified" in "Input/Output items" for the part of speech that can be specified. |
pronunciation |
string |
Any |
- |
Pronunciation of the word Specify the pronunciation of the word. 【Limitations】 Maximum number of characters:45[characters] An empty string ("pronunciation":"") can be specified. If an empty string is specified, the speech for the word is not synthesized. Please refer to "Pronunciation and Accent of the word" in "Input/Output items" for the pronunciation of the word. |
*If all keys are omitted, HTTP Status Code "400 Bad Request" is returned.
Request sample(cURL)
- Update only word
curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer [access token]" -d '{"target": "辞書/データ/3"}' [API Base URL]/tts/v1/dicts/word_dicts/ja_JP/1
- Update all contents
curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer [access token]" -d '{"target": "辞書/データ/4", "partOfSpeech": "名", "pronunciation": "ジショ/デ'\''ータ/ヨン"}' [API Base URL]/tts/v1/dicts/word_dicts/ja_JP/1
Response
Response Header
Key Name | Description |
---|---|
Content-Type |
MIME Type of received data application/json |
Response Body
Key Name | Data Type | Description |
---|---|---|
dictDataId |
number(integer) |
ID of the updated record |
target |
string |
The updated word |
partOfSpeech |
string |
The part of speech of the updated word |
pronunciation |
string |
The pronunciation of the updated word |
createdAt |
string |
The created date of the updated word This is expressed in RFC3339 format. |
updatedAt |
string |
The updated date of the updated word This is expressed in RFC3339 format. |
Response Sample
{ "dictDataId": 1, "target": "辞書/データ/3", "partOfSpeech": "名", "pronunciation: "ジショ/デ'ータ/サン", "createdAt": "2019-07-01T11:25:49+09:00", "updatedAt": "2019-07-02T09:30:21+09:00" }
Response on Error
Response Header
Key Name | Description |
---|---|
Content-Type |
MIME Type of received data application/json |
Response Body
Key Name | Data Type | Description |
---|---|---|
code |
string |
Error code Used when making inquiries. |
detail |
string |
Error details Information about the error response. Please refer to here for details. |
HTTP Status Code
Response Code | Description and Solutions |
---|---|
400 Bad Request |
The input parameter is invalid. Please refer to the details of the key pairs in the response body and here. Then, specify the correct parameter. *Examples of invalid input parameters include: - The value of the parameter is out of range. - A single-byte character is used in a parameter that can only use double-byte characters. - A parameter that does not exist is specified. |
401 Unauthorized |
Access Token is invalid(expiration etc.). Please specify a valid Access Token. |
404 Not Found |
The requested resource cannot be found. Please confirm URL and HTTP method. |
406 Not Acceptable |
Accept in the request header is invalid. Please confirm the content of it. |
409 Conflict |
The record you are trying to update is in conflict. Please check the contents of the record to be updated or the record that has been created. |
413 Request Entity Too Large |
Request was rejected because the size of the entire request data exceeded the upper limit. Please confirm the request data. |
415 Unsupported Media Type |
Content-Type is invalid. Please confirm Content-Type in the request header. |
500 internal Server Error |
An error occurred inside the server. Please confirm the content of the request. If the problem persists, please contact us through contact form |
7.Deleting records in the word dictionary
An API for deleting a record registered in the word dictionary. (Japanese language only)
Request
HTTP Endpoint
DELETE [API Base URL]/tts/v1/dicts/word_dicts/{lang}/{dictDataId}
URI parameter
Key Name | Data Type | Required | Default Value | Description |
---|---|---|---|---|
lang |
string |
Required |
- |
Language type - ja_JP:Japanese |
dictDataId |
number(integer) |
Required |
- |
ID of the record Specify the ID of the record to be deleted. |
Request Header
Key Name | Required | Description |
---|---|---|
Content-Type |
Required |
MIME Type of sent data application/json; charset=UTF-8 |
Authorization |
Required |
Access token Specify in the following format. Bearer [Access Token] |
X-HTTP-Method-Override |
Any |
Processing method for the request DELETE Required if the HTTP method is POST. |
Request sample(cURL)
curl -X DELETE -H "Authorization: Bearer [access token]" [API Base URL]/tts/v1/dicts/word_dicts/ja_JP/1
Response
HTTP Status "204 - No Content" is returned.
Response on Error
Response Header
Key Name | Description |
---|---|
Content-Type |
MIME Type of received data application/json |
Response Body
Key Name | Data Type | Description |
---|---|---|
code |
string |
Error code Used when making inquiries. |
detail |
string |
Error details Information about the error response. Please refer to here for details. |
HTTP Status Code
Response Code | Description and Solutions |
---|---|
400 Bad Request |
The input parameter is invalid. Please refer to the details of the key pairs in the response body and here. Then, specify the correct parameter. *Examples of invalid input parameters include: - The value of the parameter is out of range. - A single-byte character is used in a parameter that can only use double-byte characters. - A parameter that does not exist is specified. |
401 Unauthorized |
Access Token is invalid(expiration etc.). Please specify a valid Access Token. |
404 Not Found |
The requested resource cannot be found. Please confirm URL and HTTP method. |
413 Request Entity Too Large |
Request was rejected because the size of the entire request data exceeded the upper limit. Please confirm the request data. |
415 Unsupported Media Type |
Content-Type is invalid. Please confirm Content-Type in the request header. |
500 internal Server Error |
An error occurred inside the server. Please confirm the content of the request. If the problem persists, please contact us through contact form |
8.Registering records in the sentence dictionary
An API for registering a record that defines how the engine should pronounce the sentence in the sentence dictionary. (Japanese Language only)
This API is useful when the default pronunciation is unnatural.
How to pronounce is defined by "Pronunciation text" in "Input/Output items".
*The maximum number of records that can be registered is 5000 records.
Request
HTTP Endpoint
POST [API Base URL]/tts/v1/dicts/sentence_dicts/{lang}
URI parameter
Key Name | Data Type | Required | Default Value | Description |
---|---|---|---|---|
lang |
string |
Required |
- |
Language type - ja_JP:Japanese |
Request Header
Key Name | Required | Description |
---|---|---|
Content-Type |
Required |
MIME Type of sent data application/json; charset=UTF-8 |
Authorization |
Required |
Access token Specify in the following format. Bearer [Access Token] |
Request Body
Key Name | Data Type | Required | Default Value | Description |
---|---|---|---|---|
target |
string |
Required |
- |
Sentence Specify the sentence to be registered in the dictionary using plain text. 【Limitations】 Maximum number of characters:150[characters] You cannot register the same sentence that has already been registered. |
utterance |
string |
Required |
- |
Pronunciation text Specify the pronunciation using pronunciation text. 【Limitations】 Maximum number of characters:360[characters] Please refer to "Pronunciation text" in "Input/Output items" for the format of pronunciation text |
Request sample(cURL)
curl -X POST -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Bearer [access token]" -d '{"target": "これは文辞書データ1です。", "utterance": "コレワ[,00]ブンジショデータ[/05]イチデス^[.02]"}' [API Base URL]/tts/v1/dicts/sentence_dicts/ja_JP
Response
Response Header
Key Name | Description |
---|---|
Content-Type |
MIME Type of received data application/json |
Location |
Created resource path URI for the created record |
Response Body
Key Name | Data Type | Description |
---|---|---|
dictDataId |
number(integer) |
ID of the registered record |
target |
string |
The registered sentence |
utterance |
string |
Registered pronunciation text |
createdAt |
string |
The created date of the registered sentence This is expressed in RFC3339 format. |
updatedAt |
string |
The updated date of the registered sentence This is expressed in RFC3339 format. |
Response Sample
{ "dictDataId": 1, "target": "これは文辞書データ1です。", "utterance": "コレワ[,00]ブンジショデータ[/05]イチデス^[.02]", "createdAt": "2019-07-01T11:25:49+09:00", "updatedAt": "2019-07-01T11:25:49+09:00" }
Response on Error
Response Header
Key Name | Description |
---|---|
Content-Type |
MIME Type of received data application/json |
Response Body
Key Name | Data Type | Description |
---|---|---|
code |
string |
Error code Used when making inquiries. |
detail |
string |
Error details Information about the error response. Please refer to here for details. |
HTTP Status Code
Response Code | Description and Solutions |
---|---|
400 Bad Request |
The input parameter is invalid. Please refer to the details of the key pairs in the response body and here. Then, specify the correct parameter. *Examples of invalid input parameters include: - The value of the parameter is out of range. - A single-byte character is used in a parameter that can only use double-byte characters. - A parameter that does not exist is specified. |
401 Unauthorized |
Access Token is invalid(expiration etc.). Please specify a valid Access Token. |
404 Not Found |
The requested resource cannot be found. Please confirm URL and HTTP method. |
406 Not Acceptable |
Accept in the request header is invalid. Please confirm the content of it. |
409 Conflict |
The record you are trying to create is in conflict. Please check the contents of the record to be created or the record that has been created. |
413 Request Entity Too Large |
Request was rejected because the size of the entire request data exceeded the upper limit. Please confirm the request data. |
415 Unsupported Media Type |
Content-Type is invalid. Please confirm Content-Type in the request header. |
500 internal Server Error |
An error occurred inside the server. Please confirm the content of the request. If the problem persists, please contact us through contact form |
9.Displaying records in the sentence dictionary
An API for getting a list of records registered in the sentence dictionary. (Japanese language only)r
Request
HTTP Endpoint
GET [API Base URL]/tts/v1/dicts/sentence_dicts/{lang}?{target, dictDataId, page, limit, sort}
URI parameter
Key Name | Data Type | Required | Default Value | Description |
---|---|---|---|---|
lang |
string |
Required |
- |
Language type - ja_JP:Japanese |
target |
string |
Any |
- |
Sentence Specify the sentence to be acquired in plain text. Partial match search is possible. 【Limitations】 Maximum number of characters:150[characters] *If an empty string is specified, target is ignored. |
dictDataId |
number(integer) |
Any |
- |
ID of the record Specify the ID of the record to be acquired. If dictDataId is specified, parameters other than the required parameters are ignored. *If an empty string is specified, dictDataId is ignored. If dictDataId that does not have the corresponding record is specified, an empty array is returned. |
page |
number(integer) |
Any |
1 |
Reference page number Specify the page number that you want in the list of the retrieved records. 【Limitations】 Value range:1~5000 *If there are no records in the page, an empty array is returned. |
limit |
number(integer) |
Any |
25 |
Number of acquisitions per page Specify the number of retrieved records per page. 【Limitations】 Value range:1~5000 *If the number of registered records is less than the "limit" value, all records is returned on the first page. |
sort |
string |
Any |
createdAt |
How to sort Specify the sort order of the records to be acquired. Sort items that can be specified are as follows. - target:sentence - utterance:pronunciation text - createdAt:created date of the record - updatedAt:updated date of the record Although the default is ascending order, you can specify descending order by adding a half-width hyphen (-) before each sort item. When sorting by multiple items, specify them by separating with half-width commas. for example:sort=target,-createdAt |
Request Header
Key Name | Required | Description |
---|---|---|
Content-Type |
Required |
MIME Type of sent data application/json; charset=UTF-8 |
Authorization |
Required |
Access token Specify in the following format. Bearer [Access Token] |
Request sample(cURL)
- With only the required parameters
curl -H "Authorization: Bearer [access token]" [API Base URL]/tts/v1/dicts/sentence_dicts/ja_JP
- All parameters
curl -H "Authorization: Bearer [access token]" "[API Base URL]/tts/v1/dicts/sentence_dicts/ja_JP?target=辞書&page=1&limit=20&sort=target,-utterance,-createdAt,updatedAt"
Response
Response Header
Key Name | Description |
---|---|
Content-Type |
MIME Type of received data application/json |
X-Total-Count |
The count of the targets that hits the criteria |
Response Body
Key Name | Data Type | Description |
---|---|---|
dictData |
array[object] |
An array of elements containing the following keys: |
dictDataId |
number(integer) |
ID of the acquired record |
target |
string |
The acquired sentence |
utterance |
string |
Acquired pronunciation text |
createdAt |
string |
The created date of the acquired sentence This is expressed in RFC3339 format. |
updatedAt |
string |
The updated date of the acquired sentence This is expressed in RFC3339 format. |
Response Sample
{ dictData: [ { "dictDataId": 1, "target": "これは文辞書データ1です。", "utterance": "コレワ[,00]ブンジショデータ[/05]イチデス^[.02]", "createdAt": "2019-07-01T11:25:49+09:00", "updatedAt": "2019-07-02T09:30:21+09:00" }, { "dictDataId": 2, "target": "辞書/データ/2", "utterance": "コレワ[,00]ブンジショデータ[/05]ニデス^[.02]", "createdAt": "2019-07-01T11:26:30+09:00", "updatedAt": "2019-07-01T11:26:30+09:00" } ] }
Response on Error
Response Header
Key Name | Description |
---|---|
Content-Type |
MIME Type of received data application/json |
Response Body
Key Name | Data Type | Description |
---|---|---|
code |
string |
Error code Used when making inquiries. |
detail |
string |
Error details Information about the error response. Please refer to here for details. |
HTTP Status Code
Response Code | Description and Solutions |
---|---|
400 Bad Request |
The input parameter is invalid. Please refer to the details of the key pairs in the response body and here. Then, specify the correct parameter. *Examples of invalid input parameters include: - The value of the parameter is out of range. - A single-byte character is used in a parameter that can only use double-byte characters. - A parameter that does not exist is specified. |
401 Unauthorized |
Access Token is invalid(expiration etc.). Please specify a valid Access Token. |
404 Not Found |
The requested resource cannot be found. Please confirm URL and HTTP method. |
406 Not Acceptable |
Accept in the request header is invalid. Please confirm the content of it. |
413 Request Entity Too Large |
Request was rejected because the size of the entire request data exceeded the upper limit. Please confirm the request data. |
415 Unsupported Media Type |
Content-Type is invalid. Please confirm Content-Type in the request header. |
500 internal Server Error |
An error occurred inside the server. Please confirm the content of the request. If the problem persists, please contact us through contact form |
10.Updating records in the sentence dictionary
An API for updating the registered record. (Japanese language only)
Request
HTTP Endpoint
PUT [API Base URL]/tts/v1/dicts/sentence_dicts/{lang}/{dictDataId}
URI parameter
Key Name | Data Type | Required | Default Value | Description |
---|---|---|---|---|
lang |
string |
Required |
- |
Language type - ja_JP:Japanese |
dictDataId |
number(integer) |
Required |
- |
ID of the record Specify the ID of the record to be updated. |
Request Header
Key Name | Required | Description |
---|---|---|
Content-Type |
Required |
MIME Type of sent data application/json;charset=UTF-8 |
Authorization |
Required |
Access token Specify in the following format. Bearer [Access Token] |
X-HTTP-Method-Override |
Any |
Processing method for the request PUT Required if the HTTP method is POST. |
Request Body
Key Name | Data Type | Required | Default Value | Description |
---|---|---|---|---|
target |
string |
Any |
- |
Sentence Specify the sentence to be updated in the dictionary using plain text. 【Limitations】 Maximum number of characters:150[characters] You cannot update the same sentence that has already been registered. |
utterance |
string |
Required |
- |
Pronunciation text Specify the pronunciation using pronunciation text. 【Limitations】 Maximum number of characters:360[characters] Please refer to "Pronunciation text" in "Input/Output items" for the format of pronunciation text. |
*If all keys are omitted, HTTP Status Code "400 Bad Request" is returned.
Request sample(cURL)
- Update only word
curl -X PUT -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Bearer [access token]" -d '{"target": "これは文辞書データ3です。"}' [API Base URL]/tts/v1/dicts/sentence_dicts/ja_JP/1
- Update all contents
curl -X PUT -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Bearer [access token]" -d '{"target": "これは文辞書データ4です。", "utterance": "コレワ[,00]ブンジショデータ[/05]ヨンデス^[.03]"}' [API Base URL]/tts/v1/dicts/sentence_dicts/ja_JP/1
Response
Response Header
Key Name | Description |
---|---|
Content-Type |
MIME Type of received data application/json |
Response Body
Key Name | Data Type | Description |
---|---|---|
dictDataId |
number(integer) |
ID of the updated record |
target |
string |
The updated sentence |
utterance |
string |
Updated pronunciation text |
createdAt |
string |
The created date of the updated sentence This is expressed in RFC3339 format. |
updatedAt |
string |
The updated date of the updated sentence This is expressed in RFC3339 format. |
Response Sample
{ "dictDataId": 1, "target": "これは文辞書データ3です。", "utterance": "コレワ[,00]ブンジショデータ[/05]サンデス^[.03]", "createdAt": "2019-07-01T11:25:49+09:00", "updatedAt": "2019-07-02T09:30:21+09:00" }
Response on Error
Response Header
Key Name | Description |
---|---|
Content-Type |
MIME Type of received data application/json |
Response Body
Key Name | Data Type | Description |
---|---|---|
code |
string |
Error code Used when making inquiries. |
detail |
string |
Error details Information about the error response. Please refer to here for details. |
HTTP Status Code
Response Code | Description and Solutions |
---|---|
400 Bad Request |
The input parameter is invalid. Please refer to the details of the key pairs in the response body and here. Then, specify the correct parameter. *Examples of invalid input parameters include: - The value of the parameter is out of range. - A single-byte character is used in a parameter that can only use double-byte characters. - A parameter that does not exist is specified. |
401 Unauthorized |
Access Token is invalid(expiration etc.). Please specify a valid Access Token. |
404 Not Found |
The requested resource cannot be found. Please confirm URL and HTTP method. |
406 Not Acceptable |
Accept in the request header is invalid. Please confirm the content of it. |
409 Conflict |
The record you are trying to update is in conflict. Please check the contents of the record to be updated or the record that has been created. |
413 Request Entity Too Large |
Request was rejected because the size of the entire request data exceeded the upper limit. Please confirm the request data. |
415 Unsupported Media Type |
Content-Type is invalid. Please confirm Content-Type in the request header. |
500 internal Server Error |
An error occurred inside the server. Please confirm the content of the request. If the problem persists, please contact us through contact form |
11.Deleting records in the sentence dictionary
An API for deleting a record registered in the sentence dictionary. (Japanese language only)
Request
HTTP Endpoint
DELETE [API Base URL]/tts/v1/dicts/sentence_dicts/{lang}/{dictDataId}
URI parameter
Key Name | Data Type | Required | Default Value | Description |
---|---|---|---|---|
lang |
string |
Required |
- |
Language type - ja_JP:Japanese |
dictDataId |
number(integer) |
Required |
- |
ID of the record Specify the ID of the record to be deleted. |
Request Header
Key Name | Required | Description |
---|---|---|
Content-Type |
Required |
MIME Type of sent data application/json;charset=UTF-8 |
Authorization |
Required |
Access token Specify in the following format. Bearer [Access Token] |
X-HTTP-Method-Override |
Any |
Processing method for the request DELETE Required if the HTTP method is POST. |
Request sample(cURL)
curl -X DELETE -H "Authorization: Bearer [access token]" [API Base URL]/tts/v1/dicts/sentence_dicts/ja_JP/1
Response
HTTP Status "204 - No Content" is returned.
Response on Error
Response Header
Key Name | Description |
---|---|
Content-Type |
MIME Type of received data application/json |
Response Body
Key Name | Data Type | Description |
---|---|---|
code |
string |
Error code Used when making inquiries. |
detail |
string |
Error details Information about the error response. Please refer to here for details. |
HTTP Status Code
Response Code | Description and Solutions |
---|---|
400 Bad Request |
The input parameter is invalid. Please refer to the details of the key pairs in the response body and here. Then, specify the correct parameter. *Examples of invalid input parameters include: - The value of the parameter is out of range. - A single-byte character is used in a parameter that can only use double-byte characters. - A parameter that does not exist is specified. |
401 Unauthorized |
Access Token is invalid(expiration etc.). Please specify a valid Access Token. |
404 Not Found |
The requested resource cannot be found. Please confirm URL and HTTP method. |
413 Request Entity Too Large |
Request was rejected because the size of the entire request data exceeded the upper limit. Please confirm the request data. |
415 Unsupported Media Type |
Content-Type is invalid. Please confirm Content-Type in the request header. |
500 internal Server Error |
An error occurred inside the server. Please confirm the content of the request. If the problem persists, please contact us through contact form |
Input/Output items (data specifications)
Target text
Text data to be synthesize. This is used when using 1.Speech synthesis API, 2.Sequential speech synthesis API and 3.Pronunciation analysis API.
Plain text
Plain text data with mixed kanji, hiragana, katakana, and alphabet.
*When using English speakers, only single-byte alphanumeric characters can be specified as plain text.
Structure of plain text
プレーンテキスト
Component of plain text
Items | Description | Data Type [Character type] |
Maximum size | Value range | Omission |
---|---|---|---|---|---|
plain text |
Text that can be expressed in UTF-8 If the character code restrictions shown above are not met, the following results may occur in speech synthesis and pronunciation analysis. - error - Different results than expected |
string |
500[characters] |
- |
impossible |
Sample
今日はいい天気ですね。明日も晴れです。
Pronunciation text
Pronunciation text is a plain text in a unique format that expresses pronunciation, accents, and tone. This defines a different format for each language.
Format of pronunciation text
Pronunciation, accent position and combined type is expressed by double-byte katakana, symbols, and numerical values.
Pronunciation text contains one or more accent phrases, combined types, and a group of accent positions, and is composed as follows.
アクセント句[結合型アクセント位置]…アクセント句[結合型アクセント位置]
Component of pronunciation text
Items | Description | Data Type [Character type] |
Number of Characters | Value Range | Omission |
---|---|---|---|---|---|
group of accent positions |
This is expressed as a concatenation of “Katakana composed of mora units”. Group of accent positions has at most one accent. You can specify up to 99 "Katakana composed of mora units". If you add a half-width hat (^) to the “Katakana composed of mora units”, it will be de-voiced. For example:「シュ^」 An error will occur if you add a de-voicing symbol to a “Katakana composed of mora units” that cannot be de-voiced. It is not possible to connect the de-voicing symbol (^) and the long sound symbol (-). For example: - OK:「ピー」 - NG:「ピ^ー」 Please refer to “Katakana composed of mora units” that can be used for pronunciation text for available “Katakana composed of mora units”. "Katakana composed of mora units" that can be devoted is a gray cell in “Katakana composed of mora units” that can be used for pronunciation text. |
string |
indefinite |
- |
impossible |
combined types |
The following seven types exist. - 「/(half-width slash)」、「*(half-width asterisk)」:Specify the combination method that suppresses the inflection of the immediately following group of accent positions. These cannot be specified at the end of the pronunciation text. - %(half-width percent):Specify the minimal pose. - △(half-width space):Specify the specified size pose (small pose) to be inserted between group of accent positions. - ,(half-width comma):Specify the pose (medium pose) corresponding to “,”. - .(half-width period):Specify the pose (large pose) corresponding to “.”. - ?(half-width question mark):Specify the creation of the question tone of the previous group of accent positions and the pose (large pose). |
string |
1 |
- |
impossible |
accent positions |
Specify the position of the accent by the position from the beginning of group of accent positions (2 digits).If "00" is specified, it means no accent For example:「ワッカナイ[,03]」→The position of the accent is "カ" |
number(integer) |
2 |
00~99 |
impossible |
These are some samples of plain text and their corresponding pronunciation text.
プレーンテキスト1:今日はいい天気です。 読みテキスト1:キョーワ[/01]イー[/01]テンキデス^[.01] プレーンテキスト2:誕生日は10月31日です。 読みテキスト2:タンジョービワ[,03]ジューガツ[/04]サンジュー[*01]イチニチデス^[.04] プレーンテキスト3:出身はどちらですか? 読みテキスト3:シュ^ッシンワ[,00]ドチラデス^カ[?01]
“Katakana composed of mora units” that can be used for pronunciation text
ア | ヴァ | カ | ガ | クァ | サ | ザ | タ | ダ | ツァ | ナ | ハ | バ | パ | ファ | マ | ヤ | ラ |
イ | ヴィ | キ | ギ | クィ | スィ | ズィ | ティ | ディ | ツィ | ニ | ビ | ピ | フィ | ミ | リ | ||
ウ | ヴ | ク | グ | ス | ズ | トゥ | ドゥ | ツ | ヌ | ブ | プ | フ | ム | ユ | ル | ||
エ | ヴェ | ケ | ゲ | クェ | セ | ゼ | テ | デ | ツェ | ネ | ヘ | ベ | ペ | フェ | メ | レ | |
オ | ヴォ | コ | ゴ | クォ | ソ | ゾ | ト | ド | ツォ | ノ | ホ | ボ | ポ | フォ | モ | ヨ | ロ |
ワ | キャ | ギャ | シャ | ジャ | チャ | ヂャ | ヅャ | ニャ | ヒャ | ビャ | ピャ | フャ | ミャ | リャ | ー | ||
ウィ | シ | ジ | チ | ヂ | ヅィ | ヒ | |||||||||||
キュ | ギュ | シュ | ジュ | チュ | ヂュ | ヅ | デュ | デュ | ニュ | ヒュ | ビュ | ピュ | フュ | ミュ | リュ | ッ | |
ウェ | シェ | ジェ | チェ | ヂェ | ヅェ | ヒェ | |||||||||||
ウォ | キョ | ギョ | ショ | ジョ | チョ | ヂョ | ヅォ | ニョ | ヒョ | ビョ | ピョ | フョ | ミョ | リョ | ン |
*Gray cells can be de-voiced.
List of speaker IDs
Category | Speaker Name | Speaker ID(speakerId) | Attribute |
---|---|---|---|
Japanese/male/adult |
Japanese/male/adult/01 |
ja_JP-M-S0001-T001-E01-SR0 |
- |
Japanese/male/adult/02 |
ja_JP-M-S0005-T001-E01-SR0 |
- |
|
Japanese/male/adult/03 |
ja_JP-M-S0010-T001-E01-SR0 |
- |
|
Japanese/male/adult/04 |
ja_JP-M-S0013-T001-E01-SR0 |
- |
|
Japanese/female/adult |
Japanese/female/adult/01 |
ja_JP-F-S0005-T002-E01-SR0 |
- |
Japanese/female/adult/02 |
ja_JP-F-S0008-T001-E01-SR0 |
- |
|
Japanese/female/adult/03 |
ja_JP-F-S0014-T001-E01-SR0 |
- |
|
Japanese/female/adult/04 |
ja_JP-F-S0015-T001-E01-SR0 |
- |
|
Japanese/male/child |
Japanese/male/child/01 |
ja_JP-M-S0004-T001-E01-SR0 |
- |
Japanese/female/child |
Japanese/female/child/01 |
ja_JP-F-S0006-T001-E01-SR0 |
- |
Japanese/male/character |
Japanese/male/character/01 |
ja_JP-M-S0002-T002-E01-SR0 |
butler |
Japanese/male/character/02 |
ja_JP-M-S0139-T001-E01-SR0 |
announcer |
|
Japanese/female/character |
Japanese/male/character/01 |
ja_JP-F-S0001-T003-E01-SR0 |
anime style |
Japanese/female/character/02 |
ja_JP-F-S0140-T001-E01-SR0 |
announcer |
|
English/male/adult |
English/male/adult/01 |
en_US-M-S0001-T001-E01-SR0 |
- |
English/female/adult |
English/female/adult/01 |
en_US-F-S0001-T001-E01-SR0 |
- |
About the word dictionary
Word
Specify the word to register with double-byte characters (including spaces).
Multiple words can be separated by half-width slash (/) and specified as one word.
By specifying the accent positions for each of the multiple words to be combined, you can specify multiple accent positions for one word.
In this case, subsequent pronunciation must be separated by half-width slash as well.
For example:
- word:東京都/水道局
- pronunciation:トーキョ'ート/スイド'ーキョク
Pronunciation and Accent of the word
Specify pronunciation of the word to register with "Katakana composed of mora units".
By inserting a half-width apostrophe (') immediately after "Katakana composed of mora units", you can specify the accent positions for the corresponding "Katakana composed of mora units". You can specify up to one accent positions per word.
If you add a half-width hat (^) to the “Katakana composed of mora units”, it will be de-voiced.
For example:「シュ^」
An error will occur if you add a de-voicing symbol to a “Katakana composed of mora units” that cannot be de-voiced.
It is not possible to connect both the de-voicing symbol (^) and the long sound symbol (-).(i.e you cannot use them together)
For example:
- OK:「ピー」
- NG:「ピ^ー」
Please refer to “Katakana composed of mora units” that can be used for pronunciation text for available “Katakana composed of mora units”.
"Katakana composed of mora units" that can be devoted is a gray cell in “Katakana composed of mora units” that can be used for pronunciation text.
If half-width slash is used in the word, the same number of half-width slash and pronunciation must be specified. In this case, you can specify the accent positions for each pronunciation.
Half-width slash cannot be specified consecutively or at the beginning or end position.
For example:
- OK:「ヨミ/テキスト」
- NG:「/ヨミテキスト」, 「ヨミテキスト/」, 「ヨミ//テキスト」
Part of speech that can be specified
Part of Speech | Description | For example |
---|---|---|
普通名詞 |
Common noun |
うぐいす、アート、花火、学校 |
固有名詞 |
Proper noun |
WINDOWS |
姓 |
This is a noun used for the surname of a person's name. |
鈴木、山田 |
名 |
It is a noun used for the name of a person. |
ひろし、一郎 |
地名 |
Place name |
東京、横浜 |
組織名 |
Name of the organization. |
NTT |
サ変名詞 |
This is a noun that become a verb by appending "do". |
学習、カット、発展 |
Detail list and solutions for errors
Detail | Solution | Remarks |
---|---|---|
invalid Content-Type |
Content-Type in the request header is invalid. |
- |
invalid Accept header value |
Accept in the request header is invalid. |
- |
X-HTTP-Method-Override not exist |
X-HTTP-Method-Override was omissioned in the API that requires X-HTTP-Method-Override header. |
- |
Company-ID is invalid |
Invalid Company-ID is specified. |
- |
specified URL not exist |
A URL that does not exist was specified. |
- |
enter correct URL |
The specified resource does not exist. |
- |
there is no item to delete |
The specified resource does not exist and could not delete. |
- |
warn.invalidUrl |
A URL that does not exist was specified. |
- |
Cannot parse parameter dictDataId as Long: For input string: {value} |
A URL for dictDataId that does not exist was specified. |
{value}:value |
Cannot parse parameter id as Long: For input string: {value} |
A URL for dictDataId that does not exist was specified. |
{value}:value |
Error decoding json body: null |
Request Body JSON is not specified. |
- |
request containing invalid parameters |
Failed to parse Request Body JSON. |
- |
{key} : invalid type({type}) |
An invalid variable type value was specified for {key}. |
{key}:key |
{key} : invalid key was specified. |
An invalid {key} was specified. |
{key}:key |
{key} : must not be blank |
The {key} that cannot be omitted has been omitted. |
{key}:key |
{key} : must not be null |
Null was specified for the value of {key}. |
{key}:key |
{key} : must not be empty |
An empty value was specified for {key}. |
{key}:key |
{key} : {value} is invalid |
An invalid {value} was specified for {key}. |
{key}:key |
{key} : Invalid value |
An invalid value was specified for {key}. |
{key}:key |
{key} : invalid format |
The value for {key} was specified in an invalid format. |
{key}:key |
{key} : must match "{regexp}" |
A value that does not match the expression of {regexp} was specified. |
Specify a value according to the expression of {regexp}. |
{key} : must be greater than or equal to {value} |
A value smaller than {value} was specified. |
{key}:key |
{key} : must be less than or equal to {value} |
A value greater than {value} was specified. |
{key}:key |
{key} : must be less than {value} character |
A number of characters longer than {value} was specified for {key}. |
{key}:key |
{key} : empty list is not acceptable |
An empty array was specified for the value of {key}. |
{key}:key |
{key} : must be between {min} and {max} |
A value outside the range of {min} to {max} was specified for {key}. |
{key}:key |
{key} : size must be between {min} and {max} |
A string length outside the range of {min} to {max} was specified for {key}. |
{key}:key |
text : required input item |
As a result of pronunciation analysis processing, the text to be read is empty. |
- |
text : Utterance Text NG. |
An invalid pronunciation text was specified. |
- |
text : text analyzed result will be more than 1,200 characters |
As a result of pronunciation analysis processing, the pronunciation text exceeded 1,200 characters. |
- |
update field is not exist |
No value is specified in the Body part of the update API. |
- |
specified item not exist in the dictionary linked to the dict_id |
A dictDataID that does not exist was specified. |
- |
the request could not be completed due to a conflict {key}: |
{value} for {key} duplicated existing data. |
{key}:key |
the request could not be completed due to a conflict with the current state of the resource |
The specified data was duplicated with existing data. |
- |
error ocurred when Speech Synthesis({content}) |
As a result of pronunciation analysis processing, the pronunciation text was invalid. |
{content}:contents |
error ocurred when Text Analyzing({content}) |
Pronunciation analysis processing failed. |
{content}:contents |
server encountered an internal error which prevented it from fulfilling this request |
Please contact us from contact form. |
*System internal error occurred |
dict {dictType} is not found. |
Dictionary does not exist. |
{dictType}:dictionary type |
could not parse response body |
Please contact us from contact form. |
*Unknown error returned from speech synthesis server. |
Summarization
Japanese and English Models
The summarization API receives sentences written in Japanese and English as input and returns a summary sentence according to the specified number of characters or sentences at the time of input.
Request
HTTP Endpoint
POST [API Base URL]/nlp/v1/summary
Request Header
Key Name | Required | Description |
---|---|---|
Content-Type |
Required |
application/json;charset=UTF-8 |
Authorization |
Required |
Bearer [Access Token] |
Request Body
Key Name | Data Type | Required | Description |
---|---|---|---|
document |
string |
Required |
Input text of 10 to 5000 characters |
mode |
string |
Required |
Specified summarization methods |
sent_len |
number(integer) |
Optional |
Specified number of sentences (1-100) |
char_len |
number(integer) |
Optional |
Specified number of characters specified (10-2500) |
lang |
string |
Optional |
Specified summary language |
percentage |
number(integer) |
Optional |
Compression ratio (percentage) (1-99) |
keywords |
string |
Optional |
Keywords |
Request example (cURL)
curl -X POST -H 'Content-Type:application/json;charset=UTF-8' -H 'Authorization:Bearer [Access Token]' -d '{"document":"The front is stationary over the Pacific Ocean. On the other hand, there is a high pressure in the sea near Chishima, which gently covers from northern Japan to eastern Japan. The Kanto area is sunny, sometimes cloudy, and partly rainy. Tokyo will be sunny and cloudy with rain at night due to the influence of humid air and the front.","mode":"extract","sent_len":1,"lang":"en"}' [API Base URL]/nlp/v1/summary
Responses
Response
Key Name | Data Type | Description |
---|---|---|
result |
string |
Summarization result |
status |
number(integer) |
Status Code 0:OK, >0: error |
message |
string |
Error message |
Response example
{ "result": "The front is stationary over the Pacific Ocean.", "status": 0, "message": "ok" }
Call Center Model
This function receives a response record sentence written in Japanese as input and returns a summary sentence corresponding to the specified number of characters or sentences at the time of input.
Request
HTTP Endpoint
POST [API Base URL]/nlp/v1/summary
Request Header
Key Name | Required | Description |
---|---|---|
Content-Type |
Required |
application/json;charset=UTF-8 |
Authorization |
Required |
Bearer [Access Token] |
Request Body
Key Name | Data Type | Required | Description |
---|---|---|---|
document |
string |
Required |
Input text of 10 to 5000 characters |
mode |
string |
Required |
Specified summarization methods |
sent_len |
number(integer) |
Optional |
Specified number of sentences (1-100) |
char_len |
number(integer) |
Optional |
Specified number of characters specified (10-2500) |
lang |
string |
Not Required |
Not Required if using call center model |
percentage |
number(integer) |
Optional |
Compression ratio (percentage) (1-99) |
keywords |
string |
Optional |
Keywords |
Request example (cURL)
curl -X POST -H 'Content-Type:application/json;charset=UTF-8' -H 'Authorization:Bearer [Access Token]' -d '{"document":"お待たせ致しました。お問い合わせ頂き有難うございます。Aがお伺い致します。昨日の夕方、ウェブから御社の商品を申込みしました。そのあと、もう1つあったほうがよいと考えてウェブを見たところ、同じものがセットになった商品があることに気がつきました。そちらを申し込めば良かったのですが、その時点で問い合わせ時間が過ぎていたため、今電話しました。セット商品に変更していただくことはできるでしょうか。弊社商品をお申込み頂き有難うございます。お申し込み後のキャンセルや変更の手続きはウェブページからも行って頂くことができます。昨日の申込みということなら、お客様ご自身でウェブページで手続きされた方が簡単です。こちらの窓口で変更する場合は、本人様の確認のための作業を必要とするため、お手続きに時間がかかってしまいます。ウェブページで変更の申込みを実施いただけますでしょうか。ということはウェブから通常の手続きということですね。いつまでならお手続き可能でしょうか。本日中なら変更可能となりますので、本日中にお手続きください。わかりました。ありがとうございました。","mode":"extract-cc","sent_len":"5"}' [API Base URL]/nlp/v1/summary
Input text to summarize call records
Create the best text to summarize from the call record text you want to summarize.
Example of a response record
Operator : お待たせ致しました。お問い合わせ頂き有難うございます。Aがお伺い致します。 Customer : 昨日の夕方、ウェブから御社の商品を申込みしました。そのあと、もう1つあったほうがよいと考えてウェブを見たところ、同じものがセットになった商品があることに気がつきました。そちらを申し込めば良かったのですが、その時点で問い合わせ時間が過ぎていたため、今電話しました。セット商品に変更していただくことはできるでしょうか。 Operator : 弊社商品をお申込み頂き有難うございます。お申し込み後のキャンセルや変更の手続きはウェブページからも行って頂くことができます。昨日の申込みということなら、お客様ご自身でウェブページで手続きされた方が簡単です。こちらの窓口で変更する場合は、本人様の確認のための作業を必要とするため、お手続きに時間がかかってしまいます。ウェブページで変更の申込みを実施いただけますでしょうか。 Customer : ということはウェブから通常の手続きということですね。いつまでならお手続き可能でしょうか。 Operator : 本日中なら変更可能となりますので、本日中にお手続きください。 Customer : わかりました。ありがとうございました。
If you want to summarize the above response records, you can create a sentence by removing the speaker identifier and then connecting the sentences to a chronological sequence.
Example of input sentences to summarize
お待たせ致しました。お問い合わせ頂き有難うございます。Aがお伺い致します。昨日の夕方、ウェブから御社の商品を申込みしました。そのあと、もう1つあったほうがよいと考えてウェブを見たところ、同じものがセットになった商品があることに気がつきました。そちらを申し込めば良かったのですが、その時点で問い合わせ時間が過ぎていたため、今電話しました。セット商品に変更していただくことはできるでしょうか。弊社商品をお申込み頂き有難うございます。お申し込み後のキャンセルや変更の手続きはウェブページからも行って頂くことができます。昨日の申込みということなら、お客様ご自身でウェブページで手続きされた方が簡単です。こちらの窓口で変更する場合は、本人様の確認のための作業を必要とするため、お手続きに時間がかかってしまいます。ウェブページで変更の申込みを実施いただけますでしょうか。ということはウェブから通常の手続きということですね。いつまでならお手続き可能でしょうか。本日中なら変更可能となりますので、本日中にお手続きください。わかりました。ありがとうございました。
Responses
Response
Key Name | Data Type | Description |
---|---|---|
result |
string |
Summarization result |
status |
number(integer) |
Status Code 0:OK, >0: error |
message |
string |
Error message |
Response example
{ "result": "セット商品に変更していただくことはできるでしょうか。お申し込み後のキャンセルや変更の手続きウェブページからも行って頂くことができます。ウェブページで変更の申し込みを実施いただけますでしょうか。いつまでならお手続き可能でしょうか。本日中なら変更可能となりますので、本日中にお手続きください。", "status": 0, "message": "ok" }
Input/Output Item
List of Error Code
Response Code | Error Code | Description |
---|---|---|
200 |
0 |
Successful processing |
400 |
17001 |
・Request data is not in JSON format ・validation check error |
401~4xx 5xx |
17xxx |
System internal error |
Text Classification API
There are following five APIs.
Please note that these APIs are not available for developer accounts.
・Learn API
A RESTful API for learning model to classify a text.
・Classify API
A RESTful API for classifying a text into pre-learned classes.
・Model list API
A RESTful API for listing models.
・Model status API
A RESTful API for checking the status of model.
・Delete API
A RESTful API for deleting model.
Learn API
Request
HTTP Request
POST [API Base URL]/nlp/v1/classifier/models
Request Header
Key Name | Description |
---|---|
Content-Type |
multipart/form-data |
Authorization |
Bearer [Access Token] |
Request Body
Key Name | Data Type | Required | Description |
---|---|---|---|
dataset |
FILE |
Required |
Csv file path 【Limitations】 Maximum file size: 10MB Maximum lines: 10,000 Maximum number of class characters: 128 Maximum number of text characters: 3,000 Minimum number of classes: 2 Minimum number of class data: 6 |
type |
string |
Optional |
default - for a sentence kuzure - for a collapsed sentence |
Request Sample(cURL)
$ curl -H "Content-Type: multipart/form-data" -H "Authorization:Bearer [Access Token]" -X POST -F "dataset=@input.csv;type=text/csv" -F "type=default" [API Base URL]/nlp/v1/classifier/models
FILE Sample
Check,契約している保険の内容を確認したいです。 Check,契約している保険の内容確認を依頼したい。 Check,契約中の保険内容見せてもらえる? Check,保険の加入時期って確認できますか。 Check,加入者の名義って誰になっていますか? Check,"契約中の電話番号が""090-1234-5678""なんですが、契約内容を調べてもらえますか" Check,"契約状況を教えて下さい。 契約番号はN00000000です。" Estimate,保険の見積もりお願いしていいですか。 Estimate,保険の見積もりをしてほしいです。 Estimate,結婚したので、保険を見積もってほしい。 Estimate,保険の見積をお願いします。 Estimate,保険を検討しているので、金額を比較したい。 Estimate,保険でいくらくらいかかるか知りたい。 Estimate,クレジットカードで払いたいのですが、詳細な見積もりをしてもらえますか?
Response
Key Name | Data Type | Description |
---|---|---|
result |
object |
|
status |
integer |
Status Code 0:OK, >0:error |
message |
string |
Error message |
Model Info object
Key Name | Data Type | Description |
---|---|---|
model_id |
string |
Model ID |
Responses example
{ "result": { "model_id": "bdcee0bc-0f7d-4ee9-b195-a8c7da920cc2" }, "status": 0, "message": "OK" }
Classify API
Request
HTTP Request
POST [API Base URL]/nlp/v1/classifier/models/<model_id>/classify
Request Header
Key Name | Description |
---|---|
Content-Type |
application/json;charset=UTF-8 |
Authorization |
Bearer [Access Token] |
Request Body
Key Name | Data Type | Required | Description |
---|---|---|---|
text |
string |
required |
Input text |
Request Sample(cURL)
$ curl -H "Content-Type: application/json;charset=UTF-8" -H "Authorization:Bearer [Access Token]" -X POST -d '{"text":"契約してる保険の内容を確認したい"}' [API Base URL]/nlp/v1/classifier/models/bdcee0bc-0f7d-4ee9-b195-a8c7da920cc2/classify
Response
Key Name | Data Type | Description |
---|---|---|
result |
array(object) |
|
status |
integer |
Status Code 0:OK, >0:error |
message |
string |
Error message |
Array of classified class and score
Key Name | Data Type | Description |
---|---|---|
class |
string |
Classified class |
score |
float |
Classified score (0.0-1.0) |
Responses example
{ "result": [ { "class": "Check", "score": 0.85 }, ... { "class": "Contract", "score": 0 } ], "status": 0, "message": "OK" }
Model list API
Request
HTTP Request
GET [API Base URL]/nlp/v1/classifier/models
Request Header
Key Name | Description |
---|---|
Authorization |
Bearer [Access Token] |
Request Sample(cURL)
$ curl -H "Authorization:Bearer [Access Token]" -X GET [API Base URL]/nlp/v1/classifier/models
Response
Key Name | Data Type | Description |
---|---|---|
result |
array(object) |
※ You can save up to 10 models per account. |
status |
integer |
Status Code 0:OK, >0:error |
message |
string |
Error message |
Model list object
Key Name | Data Type | Description |
---|---|---|
model_id |
string |
Model ID |
model_status |
string |
Model status processing /completed /failed |
created_at |
string |
Creation date |
Responses example
{ "result": [ { "model_id": "31cbb5d6-6aa7-4ec1-a2af-d8cd9c14a92d", "model_status": "completed", "created_at": "2020-04-01T20:17:47+09:00" }, ... { "model_id": "bdcee0bc-0f7d-4ee9-b195-a8c7da920cc2", "model_status": "completed", "created_at": "2020-04-01T19:14:03+09:00" } ], "status": 0, "message": "OK" }
Model status API
Request
HTTP Request
GET [API Base URL]/nlp/v1/classifier/models/<model_id>
Request Header
Key Name | Description |
---|---|
Authorization |
Bearer [Access Token] |
Request Sample(cURL)
$ curl -H "Authorization:Bearer [Access Token]" -X GET [API Base URL]/nlp/v1/classifier/models/bdcee0bc-0f7d-4ee9-b195-a8c7da920cc2
Response
Key Name | Data Type | Description |
---|---|---|
result |
object |
|
status |
integer |
Status Code 0:OK, >0:error |
message |
string |
Error message |
Model status object
Key Name | Data Type | Description |
---|---|---|
model_status |
string |
Model status processing /completed /failed |
report |
object |
Model accuracy report |
Responses example
{ "result": { "model_status": "completed", "report": { "Check": { "precision": 0.8, "recall": 0.8, "f1-score": 0.8, "support": 20 }, ... "Contract": { "precision": 0.62, "recall": 0.75, "f1-score": 0.68, "support": 20 }, "accuracy": 0.77, "macro avg": { "precision": 0.78, "recall": 0.77, "f1-score": 0.76, "support": 180 }, "weighted avg": { "precision": 0.78, "recall": 0.77, "f1-score": 0.76, "support": 180 } } }, "status": 0, "message": "OK" }
Delete API
Request
HTTP Request
DELETE [API Base URL]/nlp/v1/classifier/models/<model_id>
Request Header
Key Name | Description |
---|---|
Authorization |
Bearer [Access Token] |
Request Sample(cURL)
$ curl -H "Authorization:Bearer [Access Token]" -X DELETE [API Base URL]/nlp/v1/classifier/models/bdcee0bc-0f7d-4ee9-b195-a8c7da920cc2
Response
Key Name | Data Type | Description |
---|---|---|
status |
integer |
Status Code 0:OK, >0:error |
message |
string |
Error message |
Responses example
{ "status": 0, "message": "OK" }
List of Error Code
The following is a list of typical error codes output by the COTOHA API.
Error Code | Description | Solution |
---|---|---|
99993 |
Invalid version |
Verify your request path. |
99995 |
The preset usage limit has been reached.(only for Enterprise user) |
Please change the usage limit from the account page. |
99996 |
Reached the usage limit.(only for Developers user) |
The limit on the number of times that can be used within 24 hours has been reached. Please use it again later. |
99997 |
A large number of requests were made in a short time, so the request was temporarily blocked. |
We temporarily blocked the request because we detected a large amount of access in a very short time. Please adjust the request frequency and try again. |
99998 |
Authentication Error |
Invalid credentials. Please check the credentials used to obtain the access token again. |
6103 |
Invalid Json format of parsing API |
Please check the format of Json. |