Reference

I/O specifications of each API of COTOHA API are described.

Get an Access Token
API Reference
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

POST [API Base URL]/nlp/v1/parse

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

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

Key Name	Data Type	Description
result	array(object)	Array of parsing result object
status	integer	Status Code 0:OK, >0:error
message	string	Error message

Parsing result object

Key Name	Data Type	Description
chunk_info	object	Clause object
tokens	array(object)	Array of morpheme 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)	Array of modifier
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	Semantic role label

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	Part of Speech
features	array(string)	Array of features
dependency_labels	array(object)	Array of morpheme info of the destination
attributes	object	Attributes information

Array of morpheme info of the destination

Key Name	Data Type	Description
token_id	integer	Dependant morpheme number
label	string	Dependency label

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	「６月」、「去年」
	時間	A noun that used to represent time	「２３時」、「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	7時に起きる。
timefrom	Time when the event starts	朝から晩まで働く。
timeto	Time when the event ends	朝から晩まで働く。
basis	Standard crtiteria	アメリカと比べて
unit	Unit	100グラム単位で売っている。
fromto	Range	4巻まで発売されています。
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

POST [API Base URL]/nlp/v1/ne

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

Key Name	Data Type	Description
result	array(object)	Array of named entity extraction result objects
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	Named entity class
extended_class	string	Extended named entity class
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" : ""
    }, {
    "begin_pos" : 3,
    "end_pos" : 6,
    "form" : "東京駅",
    "std_form" : "東京駅",
    "class" : "LOC",
    "extended_class" : "",
    "info" : ""
    } ],
  "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 Organization	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 Organization	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 Object	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
		Email	E-mail
		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		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 Expression		Time_Top_Other	Time expression/Other
Time Expression	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

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

Key Name	Data Type	Description
result	array(object)	Array of Company name normalization result objects
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)	Array of corrected company name information objects

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.

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	Result of reference resolution 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)	Array of reference resolution 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

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

Key Name	Data Type	Description
result	array(object)	Array of extracted keyword objects
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

Key Name	Data Type	Description
result	object	Similarity 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

Key Name	Data Type	Description
result	object	Sentence type 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

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.

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	Result of User's attribute estimation
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) default - delimit the sentence kuzure - not delimit the sentence

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)

default - delimit the sentence

kuzure - 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

Key Name	Data Type	Description
result	array(object)	Object Result of Filler Removal
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

Key Name	Data Type	Description
result	object	Detected misrecognition 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	Array of detected misrecognition objects
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

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

Key Name	Data Type	Description
result	object	Object result of sentiment analysis
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 array

Sentiment phrase object

Key Name	Data Type	Description
form	string	Notation
emotion	string	Emotional labels

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.） - GCLB（A unique set of strings for each speech recognition sequence. Set as the GCLB received in Speech Recognition Ready 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.） - GCLB（A unique set of strings for each speech recognition sequence. Set as the GCLB received in Speech Recognition Ready 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.） - GCLB（A unique set of strings for each speech recognition sequence. Set as the GCLB received in Speech Recognition Ready 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
Speech Recognition Ready Response	started	response to Speech Recognition Start Request
Detect Speech Start Response	speechStartDetected	response to request after detection of speech start
Detect Speech End Response	speechEndDetected	response to request after detection of speech end
Speech Recognition Result Response	recognized	speech recognition results
Speech Recognition End Response	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. ） - GCLB（A unique set of strings for each speech recognition sequence. ）

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 - Detection Speech End - Request to Stop Speech Recognition
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 - STOP - CANCEL - ERROR - END DETECTION※
errorinfo
code	error code
message	error message
level	error level	one of the following - WARN - ERROR - FATAL - END DETECTION※
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.

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
Specify in the following format.
Bearer [Access Token]

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 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/wav：audio/wav

- 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/wav：Wave format 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": "辞書/データ/１", "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": "辞書/データ/１",
  "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": "辞書/データ/１",
      "partOfSpeech": "普通名詞",
      "pronunciation: "ジショ/デ'ータ/イチ",
      "createdAt": "2019-07-01T11:25:49+09:00",
      "updatedAt": "2019-07-01T11:25:49+09:00"
    },
    {
      "dictDataId": 2,
      "target": "辞書/データ/２",
      "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": "辞書/データ/３"}' [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": "辞書/データ/４", "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": "辞書/データ/３",
  "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": "これは文辞書データ１です。", "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": "これは文辞書データ１です。",
  "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": "これは文辞書データ１です。",
      "utterance": "コレワ[,00]ブンジショデータ[/05]イチデス^[.02]",
      "createdAt": "2019-07-01T11:25:49+09:00",
      "updatedAt": "2019-07-02T09:30:21+09:00"
    },
    {
      "dictDataId": 2,
      "target": "辞書/データ/２",
      "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": "これは文辞書データ３です。"}' [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": "これは文辞書データ４です。", "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": "これは文辞書データ３です。",
  "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
[Full-width, half-width]

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
[Full-width half-width]

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
[half-width symbol]

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)
[half-width numbers]

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	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	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	ＷＩＮＤＯＷＳ
姓	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.	ＮＴＴ
サ変名詞	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. Please specify the appropriate Content-Type.	-
invalid Accept header value	Accept in the request header is invalid. Please specify the appropriate Accept.	-
X-HTTP-Method-Override not exist	X-HTTP-Method-Override was omissioned in the API that requires X-HTTP-Method-Override header. Please specify the appropriate X-HTTP-Method-Override.	-
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. Specify an existing resource.	-
there is no item to delete	The specified resource does not exist and could not delete. Specify an existing resource.	-
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. Please specify the correct JSON format.	-
request containing invalid parameters	Failed to parse Request Body JSON. Please specify the correct JSON format.	-
{key} : invalid type({type})	An invalid variable type value was specified for {key}. Please specify an appropriate variable type value.	{key}：key {type}：variable type
{key} : invalid key was specified.	An invalid {key} was specified. Please check the content of the Request Body and specify the correct content.	{key}：key
{key} : must not be blank	The {key} that cannot be omitted has been omitted. Please specify a value for {key}.	{key}：key
{key} : must not be null	Null was specified for the value of {key}. Please specify a non-null value.	{key}：key
{key} : must not be empty	An empty value was specified for {key}. Please specify a non-empty value.	{key}：key
{key} : {value} is invalid	An invalid {value} was specified for {key}. Please specify a correct value.	{key}：key {value}：value
{key} : Invalid value	An invalid value was specified for {key}. Please specify a correct value.	{key}：key
{key} : invalid format	The value for {key} was specified in an invalid format. Please specify in the correct 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. Please specify a value greater than or equal to {value}.	{key}：key {value}：numeric
{key} : must be less than or equal to {value}	A value greater than {value} was specified. Please specify a value below {value}.	{key}：key {value}：numeric
{key} : must be less than {value} character	A number of characters longer than {value} was specified for {key}. Please specify the number of characters below {value}.	{key}：key {value}：value
{key} : empty list is not acceptable	An empty array was specified for the value of {key}. Please specify a non-empty array for the {key} value.	{key}：key
{key} : must be between {min} and {max}	A value outside the range of {min} to {max} was specified for {key}. Please specify a number between {min} and {max}.	{key}：key {min}：minimum value {max}：maximum value
{key} : size must be between {min} and {max}	A string length outside the range of {min} to {max} was specified for {key}. Please specify a length between {min} and {max}.	{key}：key {min}：minimum value {max}：maximum value
text : Utterance Text NG.	An invalid pronunciation text was specified. Please specify the correct pronunciation text.	-
text : text analyzed result will be more than 1,200 characters	As a result of pronunciation analysis processing, the number of characters exceeded 1,200. Please divide the text contents and execute the speech synthesis process.	-
update field is not exist	No value is specified in the Body part of the update API. Please specify the key and value to be updated.	-
specified item not exist in the dictionary linked to the dict_id	A dictDataID that does not exist was specified. Please check the existence of the dictDataID and specify the existing one.	-
the request could not be completed due to a conflict {key}:	{value} for {key} duplicated existing data. Please specify data that does not duplicate existing data.	{key}：key {value}：value
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. Please specify data that does not duplicate existing data.	-
error ocurred when Text Analyzing({content})	Pronunciation analysis processing failed. Please review the requested text according to {content}.	{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. Please contact us from contact form.	{dictType}：dictionary type
could not parse response body	Please contact us from contact form.	*Unknown error returned from speech synthesis server.

Summarization

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	Size	Required	Description
document	string	5～5000	Required	input sentence
mode	string	7～8	Required	Specified summarization methods extract: extractive summarization generate: abstractive summarization
sent_len	number(integer)	1～100	Required (*1)	Specified number of sentences *1 For extractive Summarization
char_len	number(integer)	5～300	Required (*2)	Specified number of characters specified *2 For abstractive Summarization
lang	string	2	Required	Specified summary language ja: Japanese en: English

Request example (cURL)

curl -X POST -H 'Content-Type:application/json;charset=UTF-8' -H 'Authorization:Bearer [Access Token]' -d '{"document":"前線が太平洋上に停滞しています。一方、高気圧が千島近海にあって、北日本から東日本をゆるやかに覆っています。関東地方は、晴れ時々曇り、ところにより雨となっています。東京は、湿った空気や前線の影響により、晴れ後曇りで、夜は雨となるでしょう。","mode":"extract","sent_len":"1","lang":"ja"}' [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":"東京は、湿った空気や前線の影響により、晴れ後曇りで、夜は雨となるでしょう。",
"status":0,
"message":"ok"
}

Input/Output Item

List of Error Code

Response Code

Error Code

Description

200

Successful processing

400

17001

・Request data is not in Jason 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

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,"契約中の電話番号が""090-1234-5678""なんですが、契約内容を調べてもらえますか"
Check,"契約状況を教えて下さい。
契約番号はN00000000です。"

Response

Key Name	Data Type	Description
result	object	Model Info 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)	Array of classified classes and scores
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)	Array of Model list object
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	Model status 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.