Reference

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

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

Request Sample (cURL)

$ curl -X POST -H "Content-Type:application/json;charset=UTF-8" -H "Authorization:Bearer [Access Token]" -d '{"sentence":"犬は歩く。","type": "default"}' "[API Base URL]/nlp/v1/parse"

Response

Response

Key Name Data Type Description

result

array(object)

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

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

「6月」、「去年」

時間

A noun that used to represent time

「23時」、「15分」

動詞語幹

A

Ru-verbs (Ichidan-verb)

「食べる」の「食べ」

K

U-verbs (Godan-verb) with 「く」ending

「書く」の「書」

G

U-verbs (Godan-verb) with 「ぐ」ending

「泳ぐ」の「泳」

S

U-verbs (Godan-verb) with 「す」ending

「話す」の「話」

T

U-verbs (Godan-verb) with 「つ」ending

「打つ」の「打」

N

U-verbs (Godan-verb) with 「ぬ」ending

「死ぬ」の「死」

B

U-verbs (Godan-verb) with 「ぶ」ending

「飛ぶ」の「飛」

M

U-verbs (Godan-verb) with 「む」ending

「積む」の「積」

R

U-verbs (Godan-verb) with 「る」ending

「変わる」の「変わ」

W

U-verbs (Godan-verb) with 「う」ending

「失う」の「失」

KURU

Irregular conjugation with 「くる」ending:「来る」「くる」only

「来る」の「来」

SURU

Irregular conjugation with 「する」ending:「する」only

「する」の「す」

SX

Irregular conjugation of s-stem verbs with 「する」ending

「供する」の「供」

RX

Irregular conjugation of a limited number of verbs ending in「る」(special):「いらっしゃる」「おっしゃる」「くださる」「ござる」「なさる」only

「下さる」の「下さ」

IKU

Irregular conjugation of a limited number of verbs ending in 「く」(special):「行く」「いく」only

「行く」の「行」

ZX

Irregular conjugation of the verb ending in 「ず」

「信ずる」の「信」

Lて連用

Auxiliary verb

「聞いてみる」の「み」

形容詞語幹

アウオ段

Adjective that word before conjugational suffix turns into 'アウオ段'

「暖かい」の「暖か」

イ段

Adjective that word before conjugational suffix turns into 'イ段'

「美しい」の「美し」

Lて連用

Auxiliary adjective

「買ってほしい」の「ほし」

名詞接尾辞

名詞

Adding a suffix to a noun to form a noun

「家族ぐるみ」の「ぐるみ」

動作

You can attach「する」to a noun after adding a suffix to it

「日陰干しする」の「干し」

形容

Adding a suffix to a noun to modify a noun that works the same as noun’s description

「野菜嫌い」の「嫌い」

動詞語幹

Adding a suffix to a noun to form a verb

「勇気づける」の「づけ」

形容詞語幹

Adding a suffix to a noun to form an adjective

「パリ近くで発見」の「近」

動詞接尾辞

命令

The inflection changes the meaning of words into imperative mood

「よく、考えろ!」の「ろ」

名詞

Adding a suffix to a verb to form a noun

「使いっぱなしはよくない」の「っぱなし」

動詞語幹

Adding a suffix to a verb to form a verb

「両立させる」の「せ」

形容詞語幹

Adding a suffix to a verb to form an adjective

「動きたくない」の「な」

形容詞接尾辞

名詞

Adding a suffix to adjective to form a noun

「かわいさ」の「さ」

動詞語幹

Adding a suffix to adjective to form a verb

「寒がる」の「が」

形容詞語幹

Adding a suffix to adjective to form an adjective

「美しかあない」の「かあな」

接続接尾辞

動詞語幹

Works as verb when adding a suffix to suffix

「行くに違いありません」の「に違いあ」

形容詞語幹

Works as adjective when adding a suffix to a suffix

「取り込めるらしい」の「らし」

判定詞

名詞

Works as noun when suffixing to noun

「本物かどうかを見極める」の「かどうか」

形容詞語幹

Works as adjectives when adding to noun

「大人っぽい」の「っぽい」

括弧

開括弧

"(", "{" etc.

「]」

閉括弧

")" applies after "("

「)」

句点

疑問符

「?」

感嘆符

「!」

Semantic Role Label List

Here is the list of Semantic role label.

Semantic Label Name Details Example

agent

An entity that causes intentional act

うどん食べる

agentnonvoluntary

Agent that causes non intentional act

が自然の大切さを教えてくれた

coagent

Subject that acts together with agent

太郎花子結婚した

aobject

Object that has an attribute

きれい

object

Object affected by action and change

うどん食べる

implement

Means and instruments used for intentional act

バットたたく

source

Subject of the event or first position of object

プレゼント友達からもらった

material

Material or component

ビーズアクセサリー作る

goal

Subject of the event or last position of object

東京行く

beneficiary

Destination of benefit and disadvantage

友達プレゼントあげる

place

Place where the event happens

公園遊ぶ

scene

Scene where event happens

ドラマ演じる

manner

How to act and change

和やかする

time

Time when the event occurs

起きる

timefrom

Time when the event starts

からまで働く

timeto

Time when the event ends

からまで働く

basis

Standard crtiteria

アメリカ比べ

unit

Unit

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

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_Other

Event/Other

Event

Occasion

Occasion

Entertainment or social event

Occasion_Other

Entertainment or social event/Other

Religious_Festival

Religious festival

Game

Competition

Conference

Conference

Accident/Incident

Incident

Accident or incident

Incident_Other

Accident or incident/Other

War

War

Natural Disaster

Natural_Phenomenon

Natural disaster

Natural_Phenomenon_Other

Natural phenomenon/Other

Natural_Disaster

Natural disaster

Earthquake

Earthquake

Natural Object

Natural_Object

Natural object

Natural_Object_Other

Natural object/Other

Element

Element

Compound

Compound

Mineral

Mineral

Natural Object

Living Thing

Living_Thing

Living thing

Living_Thing_Other

Living thing/Other

Fungus

Fungus

Mollusc_Arthropod

Mollusk or arthropod

Insect

Insect

Fish

Fish

Amphibia

Amphibian

Reptile

Reptile

Bird

Bird

Mammal

Mammal

Flora

Flora

Part of a Living Thing

Living_Thing_Part

Part of a living thing

Living_Thing_Part_Other

Part of a living thing/Other

Animal_Part

Part of an animal

Flora_Part

Part of a plant

Disease

Disease

Disease

Disease_Other

Disease/Other

Animal_Disease

Animal disease

Color

Color

Color

Color_Other

Color/Other

Nature_Color

Natural color

Time Expression

Time_Top

Time expression

Time_Top_Other

Time expression/Other

Time
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

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.

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

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

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

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

Responses example

{
  "result" : {
    "modality" : "interrogative",
    "dialog_act" : [ "information-seeking" ]
  },
  "status" : 0,
  "message" : ""
}

Input/Output Item

Speech act list

Here is the list of speech act.

Name Details

greeting

Greeting

information-providing

Information-providing

feedback

Feedback (giving responses to the other party)

information-seeking

Information-seeking

agreement

Agreement

feedbackElicitation

Feedback elicitation

commissive

Commitment

acceptOffer

Accepting

selfCorrection

Self-correction

thanking

Gratitude

apology

Apology

stalling

Stalling (time filler)

directive

Directive

goodbye

Farewell message

declineOffer

Decline

turnAssign

Turn assign

pausing

Pausing

acceptApology

Accept apologies

acceptThanking

Accept thanks

User Attribute Estimation (β)

User attribute estimation API receives sentence written in Japanese as an input, estimates and outputs the attributes of people such as age, gender, hobby, occupation, etc.
This API is provided in Beta Version.

Request

HTTP Endpoint

POST [API Base URL]/nlp/beta/user_attribute

Request Header

Key Name Description

Content-Type

application/json;charset=UTF-8

Authorization

Bearer [Access Token]

Request Body

Key Name Data Type Required Description

document

string / array(string)

Required

You can choose from the following

string - sentence to be analyzed

array(string) - sentences to be analyzed

type

string

Optional

You can choose one from the following (default:default)

default - default sentence

kuzure - sentence contains word lengthening often found in SNSs

do_segment

boolean

Optional

You can choose whether to segment the sentences (default:false)

true - if the type of document is string, the document will be segmented.

false - the document will not be segmented.

#if the type of document is array(string), do_segment will be ignored.

Request example (cURL)

$ curl -X POST -H "Content-Type:application/json;charset=UTF-8" -H "Authorization:Bearer [Access Token]" -d '{"document":"私は昨日田町駅で飲みに行ったら奥さんに怒られた。", "type": "default","do_segment":true}' "[API Base URL]/nlp/beta/user_attribute"

Responses

Response

Key Name Data Type Description

result

object

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

Request Sample (cURL)

$ curl -X POST -H "Content-Type:application/json;charset=UTF-8" -H "Authorization:Bearer [Access Token]" -d '{"text":"えーーっと、あの、今日の打ち合わせでしたっけ。すみません、ちょっと、急用が入ってしまって。","do_segment":true}' "[API Base URL]/nlp/beta/remove_filler"

Response

Response

Key Name Data Type Description

result

array(object)

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

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

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.

By setting a value greater than 30, you will be setting a weight greater than the default user dictionary.
By setting a value smaller than 30, you will be setting a weight lower than the default user dictionary.

Speech Recognition Dictionary Sample
エヌ・ティ・ティ・コミュニケーションズ株式会社 エヌティティコミュニケーションズカブシキガイシャ
COTOHA  コトハ  20
Sample Request
HTTP Header
Content-Type: multipart/form-data; boundary=<境界文字列>
Authorization: Bearer <Access Token>
HTTP Body
--<境界文字列>
Content-Disposition: form-data; name="cascadeword"; filename="sample.tsv"
Content-Type: text/plain

エヌ・ティ・ティ・コミュニケーションズ株式会社 エヌティティコミュニケーションズカブシキガイシャ
COTOHA  コトハ  20

--<境界文字列>--
cURL
curl -H "Authorization:Bearer  <Access Token>" -X POST -F cascadeword=@<音声認識ユーザ辞書リストを記載したtsvファイル>; [API Base URL]/asr/v1/speech_words/[ASR Model ID]/upload?domainid=[ASR Domain ID]

Response

The specified notation, the specified reading, M(fixed), and weight of word are returned.
M is automatically assigned by the server, so you usually do not need to be concerned about it. If weight of word is not specified, the default value of 30 will be returned.

Response Header

Key Description

Content-Type

multipart/form-data; boundary=<Boundary Delimiter>

Response Sample

--<Boundary Delimiter>
Content-Type: text/plain
Content-Disposition: form-data; name="status"

code : 200
message : OK
detail : success

--<Boundary Delimiter>
Content-Type: text/plain
Content-Disposition: form-data; name="cascadeword"

エヌ・ティ・ティコミュニケーションズ株式会社	エヌティティコミュニケーションズカブシキガイシャ	M	30
COTOHA	コトハ	M	20

--<Boundary Delimiter>--

Error Code

Please review your request

If the following error occurs, please try your request again after taking the actions indicated. If the error persists, please contact us from Contact Us.

code message detail Solution

410

Invalid Parameter

Invalid Parameter -> List is null

Write the notation and the reading.

410

Invalid Parameter

Invalid Parameter -> List Exceed 5000 lines

In the speech recognition dictionary, specify additional words in 1000 lines or less.

410

Invalid Parameter

Surface empty

Write the notation.

410

Invalid Parameter

Reading empty

Write the reading.

410

Invalid Parameter

Invalid domainid

Check that ASR Domain id is correct.

410

Invalid Parameter

Invalid Model Name

Check that ASR Model id is correct.

410

Invalid Parameter

Prob illegal

Specify the weight as an integer between 1 and 100, inclusive.

410

Invalid Parameter

Surface illegal

Check that the character string can be set as the notation.

410

Invalid Parameter

Reading illegal

Check that the character string can be set as the reading.

410

Invalid Parameter

Surface too long

Please specify the total of notation and reading in 251 bytes or less.

Please contact us

If the following error occurs, please contact us using Contact Us.

code message detail

410

Invalid Parameter

Upload Error

410

Invalid Parameter

Download Error

600

Internal Error

-

4.Delete Speech Recognition Dictionary

Japanese models only

For deleting registered dictionary.

The registered dictionaries should be deleted individually for each model.

Request

HTTP Endpoint
GET [API Base URL]/asr/v1/speech_words/[ASR Model ID]/clear?domainid=[ASR Domain ID]

Request Header

Key Description

Authorization

Bearer [Access Token]

Sample Request

HTTP Header
Authorization: Bearer <Access Token>
cURL
curl -H "Authorization:Bearer  <Access Token>" [API Base URL]/asr/v1/speech_words/[ASR Model ID]/clear?domainid=[ASR Domain ID]

Response

Response Header

Key Description

Content-Type

multipart/form-data; boundary=<Boundary Delimiter>

Response Sample

--<Boundary Delimiter>
Content-Type: text/plain
Content-Disposition: form-data; name="status"

code : 200
message : OK
detail : success

--<Boundary Delimiter>--

Error Code

Please review your request

If the following error occurs, please try your request again after taking the actions indicated. If the error persists, please contact us from Contact Us.

code message detail Solution

410

Invalid Parameter

Invalid domainid

Check that ASR Domain id is correct.

410

Invalid Parameter

Invalid Model Name

Check that ASR Model id is correct.

Please contact us

If the following error occurs, please contact us from Contact Us

code message detail

410

Invalid Parameter

Upload Error

410

Invalid Parameter

Download Error

600

Internal Error

-

5.Get Speech Recognition Dictionary State

Japanese models only

API for checking if the dictionary data is reflected. For each model, it is possible to obtain whether the user dictionary has been updated.

Request

HTTP Endpoint
GET [API Base URL]/asr/v1/speech_words/[ASR Model ID]/isset?domainid=[ASR Domain ID]

Sample Request

HTTP Header
Authorization: Bearer <Access Token>
cURL
curl -H "Authorization:Bearer  <Access Token>" [API Base URL]/asr/v1/speech_words/[ASR Model ID]/isset?domainid=[ASR Domain ID]

Response

If the user dictionary has been updated, true will be returned; if not completed, false will be returned.
Note that the response Content-Type differs depending on whether an error has occurred.

Response Header

Key Description

Content-Type

application/json

Response Body
Key Range

isSet

true, false

Response Sample

{
  "isSet" : true
}

Error Response

Response Header

Key Description

Content-Type

multipart/form-data; boundary=<Boundary Delimiter>

Response Sample

--<Boundary Delimiter>
Content-Type: text/plain
Content-Disposition: form-data; name="status"

code : 410
message : Invalid Parameter
detail : Invalid domainid

--<Boundary Delimiter>--

Error Code

Please review your request

If the following error occurs, please try your request again after taking the actions indicated. If the error persists, please contact us from Contact Us.

code message detail Solution

410

Invalid Parameter

Invalid domainid

Check that ASR Domain id is correct.

410

Invalid Parameter

Invalid Model Name

Check that ASR Model id is correct.

Please contact us

If the following error occurs, please contact us from Contact Us

code message detail

410

Invalid Parameter

Upload Error

410

Invalid Parameter

Download Error

600

Internal Error

-

6.Download speech Recognition Dictionary

Japanese models only

API for downloading the last uploaded dictionary. It is possible to download the last uploaded dictionary for each model.

Request

HTTP Endpoint
GET [API Base URL]/asr/v1/speech_words/[ASR Model ID]/download?domainid=[ASR Domain ID]

Request Header

Key Description

Authorization

Bearer [Access Token]

Sample Request

HTTP Header
Authorization: Bearer <Access Token>
cURL
curl -H "Authorization:Bearer  <Access Token>" [API Base URL]/asr/v1/speech_words/[ASR Model ID]/download?domainid=[ASR Domain ID]

Response

The words in the last uploaded dictionary will be returned. Each line contains notation, reading, and weight of word.

Response Header

Key Description

Content-Type

multipart/form-data; boundary=<Boundary Delimiter>

Response Sample

--<Boundary Delimiter>
Content-Type: text/plain
Content-Disposition: form-data; name="status"

code : 200
message : OK
detail : success

--<Boundary Delimiter>
Content-Type: text/plain
Content-Disposition: form-data; name="cascadeword"

エヌ・ティ・ティコミュニケーションズ株式会社	エヌティティコミュニケーションズカブシキガイシャ	30
COTOHA	コトハ	30

--<Boundary Delimiter>--

Error Code

Please review your request

If the following error occurs, please try your request again after taking the actions indicated. If the error persists, please contact us from Contact Us.

code message detail Solution

410

Invalid Parameter

Invalid domainid

Check that ASR Domain id is correct.

410

Invalid Parameter

Invalid Model Name

Check that ASR Model id is correct.

Please contact us

If the following error occurs, please contact us from Contact Us

code message detail

410

Invalid Parameter

Upload Error

410

Invalid Parameter

Download Error

600

Internal Error

-

Input/Output Item

List of Models

Model Name ASR Model id

Japanese General Talk&Free(16kHz)

ja-gen_tf-16

Japanese General Short&Formal(16kHz)

ja-gen_sf-16

Japanese General Talk&Free(8kHz)

ja-gen_tf-08

Japanese Telecommunications(8kHz)

ja-mdl1_nrw-08

Japanese Insurance(8kHz)

ja-mdl2_nrw-08

English General Native Short&Formal(16kHz)

en_en-gen_sf-16

- Difference between Talk&Free and Short&Formal
 - Talk&Free: This model is suitable for speech recognition that is freestyle, where you do not have an exact idea of what to say beforehand, where natural speech elements like hesitation and mispronunciations often occur.(e.g. meeting, chat, call center and customer service, etc.)
 - Short&Formal: This model is suitable for speech recognition of audio with a single utterance in which you have an idea of what to say and is able to speak relatively clearly.(e.g. search queries, interactions with question and answer systems, etc.)

- Difference between 8kHz and 16kHz
 - 8kHz: Recommended for speech over a telephone line.
 - 16kHz: Recommended for other speech.

Text to Speech

Text to speech API consisting of 11 APIs methods.
Please note that this API is not available for use with the Developers account.

1.Speech synthesis
API for converting text input into audio data of natural human speech. The audio data is returned in a response.

2.Sequential speech synthesis
API for converting text input into audio data of natural human speech. The audio data is divided into chunks and returned.

3.Pronunciation analysis
API for converting plaintext input into pronunciation text. (Japanese language only)
The above two types of speech synthesis APIs can also use the pronunciation text as input.
Please refer to "Pronunciation text" in "Input/Output items" about pronunciation text.

4.Registering records in the word dictionary
API for registering a record that define how to pronounce the word in the word dictionary. You can use this API when the default pronunciation is unnatural. (Japanese language only)

5.Displaying records in the word dictionary
API for getting a list of records registered in the word dictionary. (Japanese language only)

6.Updating records in the word dictionary
API for updating a record registered in the word dictionary. (Japanese language only)

7.Deleting records in the word dictionary
API for deleting a record registered in the word dictionary. (Japanese language only)

8.Registering records in the sentence dictionary
API for registering a record that define how to pronounce a given sentence in the sentence dictionary. You can use this API when the default pronunciation is unnatural. How to pronounce is defined by pronunciation text. (Japanese language only)

9.Displaying records in the sentence dictionary
API for getting a list of records registered in the sentence dictionary. (Japanese language only)

10.Updating records in the sentence dictionary
API for updating a record registered in the sentence dictionary. (Japanese language only)

11.Deleting records in the sentence dictionary
API for deleting a record registered in the sentence dictionary. (Japanese language only)

Input/Output items (data specifications)
This is a list of specifications for some parameters when using the API.

Sample codes(github)
Sample codes for Java/Python/JavaScript/Node.js are available. Feel free to use them.

Recommendations for various cases?

- Want to convert text to synthetic speech audio.
Both of these APIs can be used.
1.Speech synthesis API
2.Sequential speech synthesis API

- Long texts; Long response times when converting to voice audio data.
You can speed up the response in a pseudo manner by using 2.Sequential speech synthesis API because the audio data is return from completed part.

- Want to know how the text is pronounced by the API.
You can visualize how to pronounce the text by converting the text to pronunciation text using 3. Pronunciation analysis API.

- The pronunciation is unnatural.
You can change the default pronunciation by registering words or sentences using 4. Registering records in the word dictionary API or 8.Registering records in the sentence dictionary API.
For example, when you synthesize “なんでやねん”, “な” has an accent by default. However, if you want to synthesize it in a form close to Kansai dialect, you need to add an accent to “で”. In this case, the settings are as follows.
- When using 4.Registering records in the word dictionary
ナ'ンデヤネン → ナンデ'ヤネン
- When using 8.Registering records in the sentence dictionary
ナンデヤネン[.01] → ナンデヤネン[.03]

- The registered words or sentences is not reflected, or you want to know what words or sentences is registered.
Please confirm the registered words and sentences by using 5.Displaying records in the word dictionary API or 9.Displaying records in the sentence dictionary

- Want to revise or delete the records registered in the dictionary.
You can revise the records by using 6.Updating records in the word dictionary API or 10.Updating records in the sentence dictionary API.
You can also delete the records by using 7.Deleting records in the word dictionary API or 11.Deleting records in the sentence dictionary API.

- Want to know the values that can be specified as a speaker and part of speech or want to know the details of the pronunciation text.
You can check the detailed items and specifications of some parameters in "Input/Output items (data specifications)".

- Want some sample codes to use Text to Speech API.
Here (github) is some sample codes. Please use them.

1.Speech synthesis

An API for converting text input into audio data of natural human speech.
The audio data is returned in a response.
Note: When you want to convert a long text input into audio data but do not want to wait for a long response or the full completely synthesized data, please use 2.Sequential speech synthesis API.

Request

HTTP Endpoint
POST [API Base URL]/tts/v1/tts
Request Header

Key Name Required Description

Content-Type

Required

application/json; charset=UTF-8

Authorization

Required

Access token
Specify in the following format.
Bearer [Access Token]

Accept

Any

MIME Type of received data

Specify one of the following two.

audio/wav: Wave format audio data

text/plain: Base64 encoded audio data

*When omitted, audio/wav is specified.

Request Body

When the parameter is omitted, default values are specified for optional parameters.
*Required parameters must be specified.

Key Name Data Type Required Default Value Description

text

string

Required

-

Target text

Specify the text to be synthesized.

【Limitations】

The maximum number of characters differs for each text type.

- plain text:500[characters]

- pronunciation text:1200[characters]

*If the pronunciation text exceeds 1200 characters, the parameter will be considered as exceeded even if the number of characters in plain text is not exceeded.

It is necessary to describe in the format defined for each text type. Please refer to "Target text" in "Input/Output items" about each text type format.

textType

string

Any

normal

Text type

Specify the text type of the target text

- normal:plain text

- utterance:pronunciation text

【Limitations】

You can specify utterance only when you use Japanese speakerId.

speakerId

string

Required

-

Speaker ID

Specify the speaker model id of the speech synthesizer.

【Limitations】

Please refer to "List of speaker IDs" in "Input/Output items" for the speakerId that you can specify.

speechRate

number(fraction)

Any

1

Speed of the synthesized speech

- Smaller value:Slower

- Lager value:Faster

【Limitations】

- Value range:0.50~2.00

- Step size:0.01

powerRate

number(fraction)

Any

1

Volume of the synthesized speech

- Smaller value:Lower volume

- Larger value:Larger volume

【Limitations】

- Value range:0.00~5.00

- Step size:0.01

intonation

number(interger)

Any

10

Range on the intonation of the synthesized speech

- Smaller value:Lower range

- Larger value:Higher range

【Limitations】

- Value range:1~20

- Step size:1

pitch

number(interger)

Any

12

Pitch of the synthesized speech

- Smaller value:Lower pitch

- Larger value:Higher pitch

【Limitations】

- Value range:1~20

- Step size:1

Request sample(cURL)

- With only the required parameters

curl -o result.wav -X POST -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Bearer [access token]" -d '{"text": "今日は晴れです。", "speakerId": "ja_JP-M-S0001-T001-E01-SR0"}' [API Base URL]/tts/v1/tts

- All parameters

curl -o result.wav -X POST -H "Content-Type: application/json;charset=UTF-8" -H "Accept: text/plain" -H "Authorization: Bearer [access token]" -d '{"text": "キョーワ[,01]ハレデス^[.02]", "textType": "utterance", "speakerId": " ja_JP-M-S0001-T001-E01-SR0", "speechRate": "1.25", "powerRate": "2.0", "intonation": 5, "pitch": 15 }' [API Base URL]/tts/v1/tts

Response

The sampling rate of the returned audio data is 22,050Hz.

Response Header
Key Name Description

Content-Type

MIME Type of received data

Following values are returned depending on the value set in Accept in the request header.

- audio/wavaudio/wav

- text/plaintext/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/wavaudio/wav

- text/plaintext/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": "辞書/データ/1", "partOfSpeech": "普通名詞", "pronunciation": "ジショ/デ'\''ータ/イチ"}' [API Base URL]/tts/v1/dicts/word_dicts/ja_JP

Response

Response Header
Key Name Description

Content-Type

MIME Type of received data

application/json

Location

Created resource path

URI for the created record

Response Body
Key Name Data Type Description

dictDataId

number(integer)

ID of the registered record

target

string

The registered word

partOfSpeech

string

The part of speech of the word

pronunciation

string

The pronunciation of the word

createdAt

string

The created date of the registered word

This is expressed in RFC3339 format.

updatedAt

string

The updated date of the registered word

This is expressed in RFC3339 format.

Response Sample
{
  "dictDataId": 1,
  "target": "辞書/データ/1",
  "partOfSpeech": "普通名詞",
  "pronunciation": "ジショ/デ'ータ/イチ",
  "createdAt": "2019-07-01T11:25:49+09:00",
  "updatedAt": "2019-07-01T11:25:49+09:00"
}

Response on Error

Response Header
Key Name Description

Content-Type

MIME Type of received data

application/json

Response Body
Key Name Data Type Description

code

String

Error code

Used when making inquiries.

detail

String

Error details

Information about the error response. Please refer to here for details.

HTTP Status Code
Response Code Description and Solutions

400 Bad Request

The input parameter is invalid.

Please refer to the details of the key pairs in the response body and here. Then, specify the correct parameter.

*Examples of invalid input parameters include:

- The value of the parameter is out of range.

- A single-byte character is used in a parameter that can only use double-byte characters.

- A parameter that does not exist is specified.

401 Unauthorized

Access Token is invalid(expiration etc.).

Please specify a valid Access Token.

404 Not Found

The requested resource cannot be found.

Please confirm URL and HTTP method.

406 Not Acceptable

Accept in the request header is invalid.

Please confirm the content of it.

409 Conflict

The record you are trying to create is in conflict.

Please check the contents of the record to be created or the record that has been created.

413 Request Entity Too Large

Request was rejected because the size of the entire request data exceeded the upper limit.

Please confirm the request data.

415 Unsupported Media Type

Content-Type is invalid.

Please confirm Content-Type in the request header.

500 internal Server Error

An error occurred inside the server.

Please confirm the content of the request. If the problem persists, please contact us through contact form

5.Displaying records in the word dictionary

An API for getting a list of records registered in the word dictionary. (Japanese language only)

Request

HTTP Endpoint
GET [API Base URL]/tts/v1/dicts/word_dicts/{lang}?{target, dictDataId, page, limit, sort}
URI parameter
Key Name Data Type Required Default Value Description

lang

string

Required

-

Language type

- ja_JP:Japanese

target

string

Any

-

Word

Specify the word to be acquired

Partial match search is possible.

【Limitations】

Maximum number of characters:45[characters]

*If an empty string is specified, target is ignored.

dictDataId

number(integer)

Any

-

ID of the record

Specify the ID of the record to be acquired.

If dictDataId is specified, parameters other than the required parameters are ignored.

*If an empty string is specified, dictDataId is ignored.

If dictDataId that does not have the corresponding record is specified, an empty array is returned.

page

number(integer)

Any

1

Reference page number

Specify the page number that you want in the list of the retrieved records.

【Limitations】

Value range:1~5000

*If there are no records in the page, an empty array is returned.

limit

number(integer)

Any

25

Number of acquisitions per page

Specify the number of retrieved records per page.

【Limitations】

Value range:1~5000

*If the number of registered records is less than the "limit" value, all records is returned on the first page.

sort

string

Any

createdAt

How to sort

Specify the sort order of the records to be acquired.

Sort items that can be specified are as follows.

- target:word

- pronunciation:pronuncitaion of the word

- createdAt:created date of the record

- updatedAt:updated date of the record

Although the default is ascending order, you can specify descending order by adding a half-width hyphen (-) before each sort item.

When sorting by multiple items, specify them by separating with half-width commas.

for example:sort=target,-createdAt

Request Header
Key Name Required Description

Content-Type

Required

MIME Type of sent data

application/json; charset=UTF-8

Authorization

Required

Access token

Specify in the following format.

Bearer [Access Token]

Request sample(cURL)

- With only the required parameters

curl -H "Authorization: Bearer [access token]" [API Base URL]/tts/v1/dicts/word_dicts/ja_JP

- All parameters

curl -H "Authorization: Bearer [access token]" "[API Base URL]/tts/v1/dicts/word_dicts/ja_JP?target=辞書&page=1&limit=20&sort=target,-pronunciation,-createdAt,updatedAt"

Response

Response Header
Key Name Description

Content-Type

MIME Type of received data

application/json

X-Total-Count

The count of the targets that hits the criteria

Response Body
Key Name Data Type Description

dictData

array[object]

An array of elements containing the following keys

dictDataId

number(integer)

ID of the acquired record

target

string

The acquired word

partOfSpeech

string

The part of speech of the acquired word

pronunciation

string

The pronunciation of the acquired word

createdAt

string

The created date of the acquired word

This is expressed in RFC3339 format.

updatedAt

string

The updated date of the acquired word

This is expressed in RFC3339 format.

Response Sample
{
  dictData: [
    {
      "dictDataId": 1,
      "target": "辞書/データ/1",
      "partOfSpeech": "普通名詞",
      "pronunciation: "ジショ/デ'ータ/イチ",
      "createdAt": "2019-07-01T11:25:49+09:00",
      "updatedAt": "2019-07-01T11:25:49+09:00"
    },
    {
      "dictDataId": 2,
      "target": "辞書/データ/2",
      "partOfSpeech": "固有名詞",
      "pronunciation: "ジショ/デ'ータ/ニ",
      "createdAt": "2019-07-01T11:25:50+09:00",
      "updatedAt": "2019-07-01T11:25:50+09:00"
    }
  ]
}

Response on Error

Response Header
Key Name Description

Content-Type

MIME Type of received data

application/json

Response Body
Key Name Data Type Description

code

String

Error code

Used when making inquiries.

detail

String

Error details

Information about the error response. Please refer to here for details.

HTTP Status Code
Response Code Description and Solutions

400 Bad Request

The input parameter is invalid.

Please refer to the details of the key pairs in the response body and here. Then, specify the correct parameter.

*Examples of invalid input parameters include:

- The value of the parameter is out of range.

- A single-byte character is used in a parameter that can only use double-byte characters.

- A parameter that does not exist is specified.

401 Unauthorized

Access Token is invalid(expiration etc.).

Please specify a valid Access Token.

404 Not Found

The requested resource cannot be found.

Please confirm URL and HTTP method.

406 Not Acceptable

Accept in the request header is invalid.

Please confirm the content of it.

413 Request Entity Too Large

Request was rejected because the size of the entire request data exceeded the upper limit.

Please confirm the request data.

415 Unsupported Media Type

Content-Type is invalid.

Please confirm Content-Type in the request header.

500 internal Server Error

An error occurred inside the server.

Please confirm the content of the request. If the problem persists, please contact us through contact form

6.Updating records in the word dictionary

An API for updating the registered record. (Japanese language only)

Request

HTTP Endpoint
PUT [API Base URL]/tts/v1/dicts/word_dicts/{lang}/{dictDataId}
URI parameter
Key Name Data Type Required Default Value Description

lang

string

Required

-

Language type

- ja_JP:Japanese

dictDataId

number(integer)

Required

-

ID of the record

Specify the ID of the record to be updated.

Request Header
Key Name Required Description

Content-Type

Required

MIME Type of sent data

application/json; charset=UTF-8

Authorization

Required

Access token

Specify in the following format.

Bearer [Access Token]

Request Body
Key Name Data Type Required Default Value Description

target

string

Any

-

Word

Specify the word to be updated.

【Limitations】

Maximum number of characters:45[characters]

Please refer to "Word" in "Input/Output items" for the format of the word.

Duplicate registration of combinations of notation and parts of speech is not possible.

partOfSpeech

string

Any

-

Part of speech of the word

Specify the part of speech of the word.

【Limitations】

Please refer to "Part of speech that can be specified" in "Input/Output items" for the part of speech that can be specified.

pronunciation

string

Any

-

Pronunciation of the word

Specify the pronunciation of the word.

【Limitations】

Maximum number of characters:45[characters]

An empty string ("pronunciation":"") can be specified.

If an empty string is specified, the speech for the word is not synthesized.

Please refer to "Pronunciation and Accent of the word" in "Input/Output items" for the pronunciation of the word.

*If all keys are omitted, HTTP Status Code "400 Bad Request" is returned.

Request sample(cURL)

- Update only word

curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer [access token]" -d '{"target": "辞書/データ/3"}' [API Base URL]/tts/v1/dicts/word_dicts/ja_JP/1

- Update all contents

curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer [access token]" -d '{"target": "辞書/データ/4", "partOfSpeech": "名", "pronunciation": "ジショ/デ'\''ータ/ヨン"}' [API Base URL]/tts/v1/dicts/word_dicts/ja_JP/1

Response

Response Header
Key Name Description

Content-Type

MIME Type of received data

application/json

Response Body
Key Name Data Type Description

dictDataId

number(integer)

ID of the updated record

target

string

The updated word

partOfSpeech

string

The part of speech of the updated word

pronunciation

string

The pronunciation of the updated word

createdAt

string

The created date of the updated word

This is expressed in RFC3339 format.

updatedAt

string

The updated date of the updated word

This is expressed in RFC3339 format.

Response Sample
{
  "dictDataId": 1,
  "target": "辞書/データ/3",
  "partOfSpeech": "名",
  "pronunciation: "ジショ/デ'ータ/サン",
  "createdAt": "2019-07-01T11:25:49+09:00",
  "updatedAt": "2019-07-02T09:30:21+09:00"
}

Response on Error

Response Header
Key Name Description

Content-Type

MIME Type of received data

application/json

Response Body
Key Name Data Type Description

code

string

Error code

Used when making inquiries.

detail

string

Error details

Information about the error response. Please refer to here for details.

HTTP Status Code
Response Code Description and Solutions

400 Bad Request

The input parameter is invalid.

Please refer to the details of the key pairs in the response body and here. Then, specify the correct parameter.

*Examples of invalid input parameters include:

- The value of the parameter is out of range.

- A single-byte character is used in a parameter that can only use double-byte characters.

- A parameter that does not exist is specified.

401 Unauthorized

Access Token is invalid(expiration etc.).

Please specify a valid Access Token.

404 Not Found

The requested resource cannot be found.

Please confirm URL and HTTP method.

406 Not Acceptable

Accept in the request header is invalid.

Please confirm the content of it.

409 Conflict

The record you are trying to update is in conflict.

Please check the contents of the record to be updated or the record that has been created.

413 Request Entity Too Large

Request was rejected because the size of the entire request data exceeded the upper limit.

Please confirm the request data.

415 Unsupported Media Type

Content-Type is invalid.

Please confirm Content-Type in the request header.

500 internal Server Error

An error occurred inside the server.

Please confirm the content of the request. If the problem persists, please contact us through contact form

7.Deleting records in the word dictionary

An API for deleting a record registered in the word dictionary. (Japanese language only)

Request

HTTP Endpoint
DELETE [API Base URL]/tts/v1/dicts/word_dicts/{lang}/{dictDataId}
URI parameter
Key Name Data Type Required Default Value Description

lang

string

Required

-

Language type

- ja_JP:Japanese

dictDataId

number(integer)

Required

-

ID of the record

Specify the ID of the record to be deleted.

Request Header
Key Name Required Description

Content-Type

Required

MIME Type of sent data

application/json; charset=UTF-8

Authorization

Required

Access token

Specify in the following format.

Bearer [Access Token]

X-HTTP-Method-Override

Any

Processing method for the request

DELETE

Required if the HTTP method is POST.

Request sample(cURL)
curl -X DELETE -H "Authorization: Bearer [access token]" [API Base URL]/tts/v1/dicts/word_dicts/ja_JP/1

Response

HTTP Status "204 - No Content" is returned.

Response on Error

Response Header
Key Name Description

Content-Type

MIME Type of received data

application/json

Response Body
Key Name Data Type Description

code

string

Error code

Used when making inquiries.

detail

string

Error details

Information about the error response. Please refer to here for details.

HTTP Status Code
Response Code Description and Solutions

400 Bad Request

The input parameter is invalid.

Please refer to the details of the key pairs in the response body and here. Then, specify the correct parameter.

*Examples of invalid input parameters include:

- The value of the parameter is out of range.

- A single-byte character is used in a parameter that can only use double-byte characters.

- A parameter that does not exist is specified.

401 Unauthorized

Access Token is invalid(expiration etc.).

Please specify a valid Access Token.

404 Not Found

The requested resource cannot be found.

Please confirm URL and HTTP method.

413 Request Entity Too Large

Request was rejected because the size of the entire request data exceeded the upper limit.

Please confirm the request data.

415 Unsupported Media Type

Content-Type is invalid.

Please confirm Content-Type in the request header.

500 internal Server Error

An error occurred inside the server.

Please confirm the content of the request. If the problem persists, please contact us through contact form

8.Registering records in the sentence dictionary

An API for registering a record that defines how the engine should pronounce the sentence in the sentence dictionary. (Japanese Language only)
This API is useful when the default pronunciation is unnatural.
How to pronounce is defined by "Pronunciation text" in "Input/Output items".
*The maximum number of records that can be registered is 5000 records.

Request

HTTP Endpoint
POST [API Base URL]/tts/v1/dicts/sentence_dicts/{lang}
URI parameter
Key Name Data Type Required Default Value Description

lang

string

Required

-

Language type

- ja_JP:Japanese

Request Header
Key Name Required Description

Content-Type

Required

MIME Type of sent data

application/json; charset=UTF-8

Authorization

Required

Access token

Specify in the following format.

Bearer [Access Token]

Request Body
Key Name Data Type Required Default Value Description

target

string

Required

-

Sentence

Specify the sentence to be registered in the dictionary using plain text.

【Limitations】

Maximum number of characters:150[characters]

You cannot register the same sentence that has already been registered.

utterance

string

Required

-

Pronunciation text

Specify the pronunciation using pronunciation text.

【Limitations】

Maximum number of characters:360[characters]

Please refer to "Pronunciation text" in "Input/Output items" for the format of pronunciation text

Request sample(cURL)
curl -X POST -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Bearer [access token]" -d '{"target": "これは文辞書データ1です。", "utterance": "コレワ[,00]ブンジショデータ[/05]イチデス^[.02]"}' [API Base URL]/tts/v1/dicts/sentence_dicts/ja_JP

Response

Response Header
Key Name Description

Content-Type

MIME Type of received data

application/json

Location

Created resource path

URI for the created record

Response Body
Key Name Data Type Description

dictDataId

number(integer)

ID of the registered record

target

string

The registered sentence

utterance

string

Registered pronunciation text

createdAt

string

The created date of the registered sentence

This is expressed in RFC3339 format.

updatedAt

string

The updated date of the registered sentence

This is expressed in RFC3339 format.

Response Sample
{
  "dictDataId": 1,
  "target": "これは文辞書データ1です。",
  "utterance": "コレワ[,00]ブンジショデータ[/05]イチデス^[.02]",
  "createdAt": "2019-07-01T11:25:49+09:00",
  "updatedAt": "2019-07-01T11:25:49+09:00"
}

Response on Error

Response Header
Key Name Description

Content-Type

MIME Type of received data

application/json

Response Body
Key Name Data Type Description

code

string

Error code

Used when making inquiries.

detail

string

Error details

Information about the error response. Please refer to here for details.

HTTP Status Code
Response Code Description and Solutions

400 Bad Request

The input parameter is invalid.

Please refer to the details of the key pairs in the response body and here. Then, specify the correct parameter.

*Examples of invalid input parameters include:

- The value of the parameter is out of range.

- A single-byte character is used in a parameter that can only use double-byte characters.

- A parameter that does not exist is specified.

401 Unauthorized

Access Token is invalid(expiration etc.).

Please specify a valid Access Token.

404 Not Found

The requested resource cannot be found.

Please confirm URL and HTTP method.

406 Not Acceptable

Accept in the request header is invalid.

Please confirm the content of it.

409 Conflict

The record you are trying to create is in conflict.

Please check the contents of the record to be created or the record that has been created.

413 Request Entity Too Large

Request was rejected because the size of the entire request data exceeded the upper limit.

Please confirm the request data.

415 Unsupported Media Type

Content-Type is invalid.

Please confirm Content-Type in the request header.

500 internal Server Error

An error occurred inside the server.

Please confirm the content of the request. If the problem persists, please contact us through contact form

9.Displaying records in the sentence dictionary

An API for getting a list of records registered in the sentence dictionary. (Japanese language only)r

Request

HTTP Endpoint
GET [API Base URL]/tts/v1/dicts/sentence_dicts/{lang}?{target, dictDataId, page, limit, sort}
URI parameter
Key Name Data Type Required Default Value Description

lang

string

Required

-

Language type

- ja_JP:Japanese

target

string

Any

-

Sentence

Specify the sentence to be acquired in plain text.

Partial match search is possible.

【Limitations】

Maximum number of characters:150[characters]

*If an empty string is specified, target is ignored.

dictDataId

number(integer)

Any

-

ID of the record

Specify the ID of the record to be acquired.

If dictDataId is specified, parameters other than the required parameters are ignored.

*If an empty string is specified, dictDataId is ignored.

If dictDataId that does not have the corresponding record is specified, an empty array is returned.

page

number(integer)

Any

1

Reference page number

Specify the page number that you want in the list of the retrieved records.

【Limitations】

Value range:1~5000

*If there are no records in the page, an empty array is returned.

limit

number(integer)

Any

25

Number of acquisitions per page

Specify the number of retrieved records per page.

【Limitations】

Value range:1~5000

*If the number of registered records is less than the "limit" value, all records is returned on the first page.

sort

string

Any

createdAt

How to sort

Specify the sort order of the records to be acquired.

Sort items that can be specified are as follows.

- target:sentence

- utterance:pronunciation text

- createdAt:created date of the record

- updatedAt:updated date of the record

Although the default is ascending order, you can specify descending order by adding a half-width hyphen (-) before each sort item.

When sorting by multiple items, specify them by separating with half-width commas.

for example:sort=target,-createdAt

Request Header
Key Name Required Description

Content-Type

Required

MIME Type of sent data

application/json; charset=UTF-8

Authorization

Required

Access token

Specify in the following format.

Bearer [Access Token]

Request sample(cURL)

- With only the required parameters

curl -H "Authorization: Bearer [access token]" [API Base URL]/tts/v1/dicts/sentence_dicts/ja_JP

- All parameters

curl -H "Authorization: Bearer [access token]" "[API Base URL]/tts/v1/dicts/sentence_dicts/ja_JP?target=辞書&page=1&limit=20&sort=target,-utterance,-createdAt,updatedAt"

Response

Response Header
Key Name Description

Content-Type

MIME Type of received data

application/json

X-Total-Count

The count of the targets that hits the criteria

Response Body
Key Name Data Type Description

dictData

array[object]

An array of elements containing the following keys:

dictDataId

number(integer)

ID of the acquired record

target

string

The acquired sentence

utterance

string

Acquired pronunciation text

createdAt

string

The created date of the acquired sentence

This is expressed in RFC3339 format.

updatedAt

string

The updated date of the acquired sentence

This is expressed in RFC3339 format.

Response Sample
{
  dictData: [
    {
      "dictDataId": 1,
      "target": "これは文辞書データ1です。",
      "utterance": "コレワ[,00]ブンジショデータ[/05]イチデス^[.02]",
      "createdAt": "2019-07-01T11:25:49+09:00",
      "updatedAt": "2019-07-02T09:30:21+09:00"
    },
    {
      "dictDataId": 2,
      "target": "辞書/データ/2",
      "utterance": "コレワ[,00]ブンジショデータ[/05]ニデス^[.02]",
      "createdAt": "2019-07-01T11:26:30+09:00",
      "updatedAt": "2019-07-01T11:26:30+09:00"
    }
  ]
}

Response on Error

Response Header
Key Name Description

Content-Type

MIME Type of received data

application/json

Response Body
Key Name Data Type Description

code

string

Error code

Used when making inquiries.

detail

string

Error details

Information about the error response. Please refer to here for details.

HTTP Status Code
Response Code Description and Solutions

400 Bad Request

The input parameter is invalid.

Please refer to the details of the key pairs in the response body and here. Then, specify the correct parameter.

*Examples of invalid input parameters include:

- The value of the parameter is out of range.

- A single-byte character is used in a parameter that can only use double-byte characters.

- A parameter that does not exist is specified.

401 Unauthorized

Access Token is invalid(expiration etc.).

Please specify a valid Access Token.

404 Not Found

The requested resource cannot be found.

Please confirm URL and HTTP method.

406 Not Acceptable

Accept in the request header is invalid.

Please confirm the content of it.

413 Request Entity Too Large

Request was rejected because the size of the entire request data exceeded the upper limit.

Please confirm the request data.

415 Unsupported Media Type

Content-Type is invalid.

Please confirm Content-Type in the request header.

500 internal Server Error

An error occurred inside the server.

Please confirm the content of the request. If the problem persists, please contact us through contact form

10.Updating records in the sentence dictionary

An API for updating the registered record. (Japanese language only)

Request

HTTP Endpoint
PUT [API Base URL]/tts/v1/dicts/sentence_dicts/{lang}/{dictDataId}
URI parameter
Key Name Data Type Required Default Value Description

lang

string

Required

-

Language type

- ja_JP:Japanese

dictDataId

number(integer)

Required

-

ID of the record

Specify the ID of the record to be updated.

Request Header
Key Name Required Description

Content-Type

Required

MIME Type of sent data

application/json;charset=UTF-8

Authorization

Required

Access token

Specify in the following format.

Bearer [Access Token]

X-HTTP-Method-Override

Any

Processing method for the request

PUT

Required if the HTTP method is POST.

Request Body
Key Name Data Type Required Default Value Description

target

string

Any

-

Sentence

Specify the sentence to be updated in the dictionary using plain text.

【Limitations】

Maximum number of characters:150[characters]

You cannot update the same sentence that has already been registered.

utterance

string

Required

-

Pronunciation text

Specify the pronunciation using pronunciation text.

【Limitations】

Maximum number of characters:360[characters]

Please refer to "Pronunciation text" in "Input/Output items" for the format of pronunciation text.

*If all keys are omitted, HTTP Status Code "400 Bad Request" is returned.

Request sample(cURL)

- Update only word

curl -X PUT -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Bearer [access token]" -d '{"target": "これは文辞書データ3です。"}' [API Base URL]/tts/v1/dicts/sentence_dicts/ja_JP/1

- Update all contents

curl -X PUT -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Bearer [access token]" -d '{"target": "これは文辞書データ4です。", "utterance": "コレワ[,00]ブンジショデータ[/05]ヨンデス^[.03]"}' [API Base URL]/tts/v1/dicts/sentence_dicts/ja_JP/1

Response

Response Header
Key Name Description

Content-Type

MIME Type of received data

application/json

Response Body
Key Name Data Type Description

dictDataId

number(integer)

ID of the updated record

target

string

The updated sentence

utterance

string

Updated pronunciation text

createdAt

string

The created date of the updated sentence

This is expressed in RFC3339 format.

updatedAt

string

The updated date of the updated sentence

This is expressed in RFC3339 format.

Response Sample
{
  "dictDataId": 1,
  "target": "これは文辞書データ3です。",
  "utterance": "コレワ[,00]ブンジショデータ[/05]サンデス^[.03]",
  "createdAt": "2019-07-01T11:25:49+09:00",
  "updatedAt": "2019-07-02T09:30:21+09:00"
}

Response on Error

Response Header
Key Name Description

Content-Type

MIME Type of received data

application/json

Response Body
Key Name Data Type Description

code

string

Error code

Used when making inquiries.

detail

string

Error details

Information about the error response. Please refer to here for details.

HTTP Status Code
Response Code Description and Solutions

400 Bad Request

The input parameter is invalid.

Please refer to the details of the key pairs in the response body and here. Then, specify the correct parameter.

*Examples of invalid input parameters include:

- The value of the parameter is out of range.

- A single-byte character is used in a parameter that can only use double-byte characters.

- A parameter that does not exist is specified.

401 Unauthorized

Access Token is invalid(expiration etc.).

Please specify a valid Access Token.

404 Not Found

The requested resource cannot be found.

Please confirm URL and HTTP method.

406 Not Acceptable

Accept in the request header is invalid.

Please confirm the content of it.

409 Conflict

The record you are trying to update is in conflict.

Please check the contents of the record to be updated or the record that has been created.

413 Request Entity Too Large

Request was rejected because the size of the entire request data exceeded the upper limit.

Please confirm the request data.

415 Unsupported Media Type

Content-Type is invalid.

Please confirm Content-Type in the request header.

500 internal Server Error

An error occurred inside the server.

Please confirm the content of the request. If the problem persists, please contact us through contact form

11.Deleting records in the sentence dictionary

An API for deleting a record registered in the sentence dictionary. (Japanese language only)

Request

HTTP Endpoint
DELETE [API Base URL]/tts/v1/dicts/sentence_dicts/{lang}/{dictDataId}
URI parameter
Key Name Data Type Required Default Value Description

lang

string

Required

-

Language type

- ja_JP:Japanese

dictDataId

number(integer)

Required

-

ID of the record

Specify the ID of the record to be deleted.

Request Header
Key Name Required Description

Content-Type

Required

MIME Type of sent data

application/json;charset=UTF-8

Authorization

Required

Access token

Specify in the following format.

Bearer [Access Token]

X-HTTP-Method-Override

Any

Processing method for the request

DELETE

Required if the HTTP method is POST.

Request sample(cURL)
curl -X DELETE -H "Authorization: Bearer [access token]" [API Base URL]/tts/v1/dicts/sentence_dicts/ja_JP/1

Response

HTTP Status "204 - No Content" is returned.

Response on Error

Response Header
Key Name Description

Content-Type

MIME Type of received data

application/json

Response Body
Key Name Data Type Description

code

string

Error code

Used when making inquiries.

detail

string

Error details

Information about the error response. Please refer to here for details.

HTTP Status Code
Response Code Description and Solutions

400 Bad Request

The input parameter is invalid.

Please refer to the details of the key pairs in the response body and here. Then, specify the correct parameter.

*Examples of invalid input parameters include:

- The value of the parameter is out of range.

- A single-byte character is used in a parameter that can only use double-byte characters.

- A parameter that does not exist is specified.

401 Unauthorized

Access Token is invalid(expiration etc.).

Please specify a valid Access Token.

404 Not Found

The requested resource cannot be found.

Please confirm URL and HTTP method.

413 Request Entity Too Large

Request was rejected because the size of the entire request data exceeded the upper limit.

Please confirm the request data.

415 Unsupported Media Type

Content-Type is invalid.

Please confirm Content-Type in the request header.

500 internal Server Error

An error occurred inside the server.

Please confirm the content of the request. If the problem persists, please contact us through contact form

Input/Output items (data specifications)

Target text

Text data to be synthesize. This is used when using 1.Speech synthesis API, 2.Sequential speech synthesis API and 3.Pronunciation analysis API.

Plain text

Plain text data with mixed kanji, hiragana, katakana, and alphabet.
*When using English speakers, only single-byte alphanumeric characters can be specified as plain text.

Structure of plain text
プレーンテキスト
Component of plain text
Items Description Data Type
[Character type]
Maximum size Value range Omission

plain text

Text that can be expressed in UTF-8

If the character code restrictions shown above are not met, the following results may occur in speech synthesis and pronunciation analysis.

- error

- Different results than expected

string
[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]

1

-

impossible

accent positions

Specify the position of the accent by the position from the beginning of group of accent positions (2 digits).If "00" is specified, it means no accent

For example:「ワッカナイ[,03]」→The position of the accent is "カ"

number(integer)
[half-width numbers]

2

00~99

impossible

These are some samples of plain text and their corresponding pronunciation text.

プレーンテキスト1:今日はいい天気です。
読みテキスト1:キョーワ[/01]イー[/01]テンキデス^[.01]

プレーンテキスト2:誕生日は10月31日です。
読みテキスト2:タンジョービワ[,03]ジューガツ[/04]サンジュー[*01]イチニチデス^[.04]

プレーンテキスト3:出身はどちらですか?
読みテキスト3:シュ^ッシンワ[,00]ドチラデス^カ[?01]
“Katakana composed of mora units” that can be used for pronunciation text
ヴァ クァ ツァ ファ
ヴィ クィ スィ ズィ ティ ディ ツィ フィ
トゥ ドゥ
ヴェ クェ ツェ フェ
ヴォ クォ ツォ フォ
キャ ギャ シャ ジャ チャ ヂャ ヅャ ニャ ヒャ ピャ ビャ フャ ミャ リャ
ウィ ヅィ
キュ ギュ シュ ジュ チュ ヂュ デュ デュ ニュ ヒュ ピュ ビュ フュ ミュ リュ
ウェ シェ ジェ チェ ヂェ ヅェ ヒェ ピェ
ウォ キョ ギョ ショ ジョ チョ ヂョ ヅォ ニョ ヒョ ピョ ビョ フョ ミョ リョ

*Gray cells can be de-voiced.

List of speaker IDs

Category Speaker Name Speaker ID(speakerId) Attribute

Japanese/male/adult

Japanese/male/adult/01

ja_JP-M-S0001-T001-E01-SR0

-

Japanese/male/adult/02

ja_JP-M-S0005-T001-E01-SR0

-

Japanese/male/adult/03

ja_JP-M-S0010-T001-E01-SR0

-

Japanese/male/adult/04

ja_JP-M-S0013-T001-E01-SR0

-

Japanese/female/adult

Japanese/female/adult/01

ja_JP-F-S0005-T002-E01-SR0

-

Japanese/female/adult/02

ja_JP-F-S0008-T001-E01-SR0

-

Japanese/female/adult/03

ja_JP-F-S0014-T001-E01-SR0

-

Japanese/female/adult/04

ja_JP-F-S0015-T001-E01-SR0

-

Japanese/male/child

Japanese/male/child/01

ja_JP-M-S0004-T001-E01-SR0

-

Japanese/female/child

Japanese/female/child/01

ja_JP-F-S0006-T001-E01-SR0

-

Japanese/male/character

Japanese/male/character/01

ja_JP-M-S0002-T002-E01-SR0

butler

Japanese/male/character/02

ja_JP-M-S0139-T001-E01-SR0

announcer

Japanese/female/character

Japanese/male/character/01

ja_JP-F-S0001-T003-E01-SR0

anime style

Japanese/female/character/02

ja_JP-F-S0140-T001-E01-SR0

announcer

English/male/adult

English/male/adult/01

en_US-M-S0001-T001-E01-SR0

-

English/female/adult

English/female/adult/01

en_US-F-S0001-T001-E01-SR0

-

About the word dictionary

Word

Specify the word to register with double-byte characters (including spaces).
Multiple words can be separated by half-width slash (/) and specified as one word.
By specifying the accent positions for each of the multiple words to be combined, you can specify multiple accent positions for one word.
In this case, subsequent pronunciation must be separated by half-width slash as well.

For example:
- word:東京都/水道局
- pronunciation:トーキョ'ート/スイド'ーキョク

Pronunciation and Accent of the word

Specify pronunciation of the word to register with "Katakana composed of mora units".
By inserting a half-width apostrophe (') immediately after "Katakana composed of mora units", you can specify the accent positions for the corresponding "Katakana composed of mora units". You can specify up to one accent positions per word.
If you add a half-width hat (^) to the “Katakana composed of mora units”, it will be de-voiced.
For example:「シュ^」
An error will occur if you add a de-voicing symbol to a “Katakana composed of mora units” that cannot be de-voiced.
It is not possible to connect both the de-voicing symbol (^) and the long sound symbol (-).(i.e you cannot use them together)

For example:
- OK:「ピー」
- NG:「ピ^ー」

Please refer to “Katakana composed of mora units” that can be used for pronunciation text for available “Katakana composed of mora units”.
"Katakana composed of mora units" that can be devoted is a gray cell in “Katakana composed of mora units” that can be used for pronunciation text.

If half-width slash is used in the word, the same number of half-width slash and pronunciation must be specified. In this case, you can specify the accent positions for each pronunciation.
Half-width slash cannot be specified consecutively or at the beginning or end position.

For example:
- OK:「ヨミ/テキスト」
- NG:「/ヨミテキスト」, 「ヨミテキスト/」, 「ヨミ//テキスト」

Part of speech that can be specified
Part of Speech Description For example

普通名詞

Common noun

うぐいす、アート、花火、学校

固有名詞

Proper noun

WINDOWS

This is a noun used for the surname of a person's name.

鈴木、山田

It is a noun used for the name of a person.

ひろし、一郎

地名

Place name

東京、横浜

組織名

Name of the organization.

NTT

サ変名詞

This is a noun that become a verb by appending "do".

学習、カット、発展

Detail list and solutions for errors

Detail Solution Remarks

invalid Content-Type

Content-Type in the request header is invalid.
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

0

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.