1. TOP
  2. PRODUCT
  3. Text Suggest API

Recurrent Neural NetworkやLSTMと呼ばれる構造の言語モデルを利用した、文章の自動生成および入力補助を実現するAPIです。膨大な原稿を学習することで、その中の文章の言い回しや表現を機械が学習し、ユーザが入力した単語や文章の後に続く文章を生成する機能を提供します。
このAPIを利用することによって、既に学習した原稿のような自然な日本語の文章を自動で生成したり、文章の入力機能に組み込むことによるテキスト入力支援ツールなどを簡単に作成することができます。

DETAIL

Text Suggest APIはディープラーニングの技術を活用して生まれた、テキストの自動生成や入力補助を行うAPIです。
リクルートが持つサービスの多くは、ウェブサービスや雑誌などに原稿を掲載することで、利用者と企業とを結ぶメディアを展開しています。飲食店の料理情報や求人の募集要項、美容室の紹介などの多種多様な原稿が日々作られていくなかで、なんとか原稿を作る時間を短縮できないか、より多くの原稿を限られた時間内で書くことができないか、そういった要望から生まれたのがこのText Suggest APIです。決められた内容をもとに原稿を自動作成したり、原稿作成者のテキスト入力を補助する形で自動作成したテキストをサジェストすることで、そうした原稿作成の現場をサポートしています。
このAPIでは、選択した言語モデルを元にして、与えられたテキストの後に続く単語やフレーズ、センテンスを取得することができます。このテキストは、日本語の文章や和歌、プログラミングのソースコードなど、あらかじめ作成した言語モデルから自動で生成されます。言語モデル内部ではRecurrent Neural NetworkやLSTMといった技術により確率的に計算されてテキストを構築していくので、学習元の膨大なテキストの雰囲気を残しつつも、オリジナルな要素を加えた新しいテキストとして生成し、活用することができます。

NOTES

他人の名称・メールアドレス・住所・電話番号など個人を特定しうる情報はアップロードしないでください。

VERSION

Text Sugget API Version 2

利用者が用意したデータセットをアップロードすることで、モデルを学習し利用できるようにする機能を追加しました。

変更点
・suggest APIにユーザー独自モデルを選択できる機能を追加しました
・dataset_URL APIを追加しました
・create_model APIを追加しました
・model_status APIを追加しました



Version 1のリファレンスは こちら

REFERENCE

  • suggest
  • dataset_URL
  • create_model
  • model_status

Text Suggest API (classify)

文生成用のAPIです。
入力されたテキストに続くテキストを自動生成します。
生成文として幾つかの候補を返します。


生成文の種類は次の4つから選択できます。

現代文
・・・・日常の情景を記述した日本語文を出力します。
和歌
・・・・和歌で歌われるような文章や単語をすべて平仮名で出力します。
プログラミング言語(Go)
・・・・Go言語の実装に使用されているソースコードを出力します。
ユーザー独自モデル
・・・・ユーザーが用意した学習データで作成したモデルを使って日本語文を出力します。

エンドポイント

URL:
https://api.a3rt.recruit-tech.co.jp/text_suggest/v2/predict
メソッド:
GET

リクエストパラメータ

No. パラメータ名 説明 値サンプル 制約 必須
1 apikey APIキーを指定します AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 半角英数字
2 callback コールバックを指定します jQuery18308453692126555485_1471946187158 レスポンス ContentType は
callback 未指定時:application/json
callback 指定時:applocation/javascript
-
3 previous_description 文を生成するための入力文を指定します UTF-8
4 style 生成する文の種類を指定します。現代文/和歌/プログラミング言語(Go)/ユーザー独自モデル の4種類から選べます。 0 <ユーザー独自モデルの場合>
model APIのレスポンスで受けたmodel_idを指定。

<ユーザー独自モデル以外の場合>
半角英数字で以下のいずれかを指定。
0: 現代文
1: 和歌
2: プログラミング言語(Go)

※未指定時は現代文
-
5 separation 生成する文の長さを指定します。単語/フレーズ/センテンスの3種類から選べます。 0 半角数字で以下のいずれかを指定。
0: 単語
1: フレーズ
2: センテンス
※未指定時はセンテンス
-

レスポンスフィールド

 
No. 説明 値サンプル 返却条件 複数
項目
1 status 処理ステータス 0 int 常に返却 -
2 message メッセージ sentence is OK. string 常に返却 -
3 suggestion 生成文を格納した配列 [ "がいます", "が草を", "が一頭います" ] list 常に返却 -

ステータスコード / メッセージ

No. status HTTP
status
message 返却条件
1 0 200 ok 正常応答
2 1000 400 apikey is null APIキー未指定
3 1001 400 apikey not found APIキーが見つからない
4 1002 400 deleted account 退会済み
5 1003 400 temporary account アカウント未承認
6 1010 400 server not found サーバが見つからない
7 1011 400 server parameter error サーバ設定エラー
8 1030 403 access deny アクセス拒否
9 1400 400 bad request リクエストパラメータが不正
10 1404 404 not found 指定したオブジェクト見つからない
11 1405 405 method not allowed メソッドが正しくない
12 1413 413 request entity too long リクエストパラメータの値が長すぎる
13 1500 500 internal server error API処理で異常が発生しました

制限事項

パラメータ長さに関する制限事項

previous_description で送信できる文字列は500文字までです。

Text Suggest API (dataset)

ユーザー独自モデル作成用のAPIです。
datasetではモデル作成に使う学習データを配置するパスを返却します。

エンドポイント

URL:
https://api.a3rt.recruit-tech.co.jp/text_suggest/v2/dataset
メソッド:
POST
No. エンドポイント 説明
1 dataset 所定のファイル配置場所とdataset_idを返却します。

リクエストパラメータ

No. パラメータ名 説明 値サンプル 制約 必須
1 apikey APIキーを指定します AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 半角英数字
2 callback コールバックを指定します jQuery18308453692126555485_1471946187158 レスポンス ContentType は
callback 未指定時:application/json
callback 指定時:applocation/javascript
-

レスポンスフィールド

No. フィールド名 説明 値サンプル 返却条件 複数項目
1 status 処理ステータス 0 int 常に返却 -
2 message メッセージ ok string 常に返却 -
3 dataset_id データセットID xxxxxxxxxxx string 常に返却 -
4 dataset_url データセットURL 配置先URL string 常に返却 -

ステータスコード / メッセージ

No. status HTTP
status
message 返却条件
1 0 200 ok 正常応答
2 1000 400 apikey is null APIキー未指定
3 1001 400 apikey not found APIキーが見つからない
4 1002 400 deleted account 退会済み
5 1003 400 temporary account アカウント未承認
6 1010 400 server not found サーバが見つからない
7 1011 400 server parameter error サーバ設定エラー
8 1030 403 access deny アクセス拒否
9 1400 400 bad request リクエストパラメータが不正
10 1405 405 method not allowed メソッドが正しくない
11 1500 500 internal server error API処理で異常が発生しました

制限事項

アップロードするファイルに関する制限事項

データサイズ:5MB以下
データ行数:100行以上、1万行以内

ファイルフォーマット

学習データ(アップロードファイル)

文字コード:UTF-8
日本語の文章が書かれたテキストファイル
適度に改行されていること
単語単位での分かち書きは不要

例)
暗くされた部屋の中で、テーブルに置かれたノートパソコンのモニター画面が壁の大きなスクリーンに映し出されています。プロジェクターにパソコンの画像が映し出されています。
スクリーンにパソコンの画面が映し出されています。会議室には大きなスクリーンがあり、パソコンの画面が投影されています。
室内のプロジェクターに、パソコンの画面が映されています。スケボーに興じる一人の男性がいます。帽子をかぶった男性がスケートボードをしています。
男性がスケートボードに乗っています。スケートボードで滑って遊んでいます。
白いランニングを着た男性がスケートボードをしています。
親子象が並んで草原を歩いています。大きさが異なる3頭のゾウがいて、草が茂っている所を連なって歩いています。
低層の草木が茂る草むらをゾウが歩いています。草原の中を、3頭の象が縦に並んで歩いています。草原に大小の三頭の象がいる様子です。
...

Text Suggest API (create model)

ユーザー独自モデル作成用のAPIです。
modelでは配置済みのデータセットに対して学習を起動させます。

エンドポイント

URL:
https://api.a3rt.recruit-tech.co.jp/text_suggest/v2/model
メソッド:
POST
No. エンドポイント 説明
1 model パラメータとして指定されたデータセットに対してユーザー独自モデルを作成します。

リクエストパラメータ

No. パラメータ名 説明 値サンプル 制約 必須
1 apikey APIキーを指定します AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 半角英数字
2 dataset_id データセットIDを指定します
(datasetでレスポンスとして受けたもの)
xxxxxxxxxxx 半角英数字・ハイフン
3 callback コールバックを指定します jQuery18308453692126555485_1471946187158 レスポンス ContentType は
callback 未指定時:application/json
callback 指定時:applocation/javascript

レスポンスフィールド

No. フィールド名 説明 値サンプル 返却条件 複数項目
1 status 処理ステータス 0 int 常に返却 -
2 message メッセージ ok string 常に返却 -
3 model_id モデルID xxxxxxxxxx string 常に返却 -

ステータスコード / メッセージ

No. status HTTP
status
message 返却条件
1 0 200 ok 正常応答
2 1000 400 apikey is null APIキー未指定
3 1001 400 apikey not found APIキーが見つからない
4 1002 400 deleted account 退会済み
5 1003 400 temporary account アカウント未承認
6 1010 400 server not found サーバが見つからない
7 1011 400 server parameter error サーバ設定エラー
8 1030 403 access deny アクセス拒否
9 1400 400 bad request リクエストパラメータが不正
10 1400 400 train data file not found 学習データファイルが見つからない
11 1400 400 bad train data file 学習データファイルの中身が形式が不正
12 1400 400 train data file size exceeds the size limit 学習データサイズが大きすぎるか小さすぎる
13 1403 403 order is already exist すでに順番待ちしています
14 1404 404 not found 指定したオブジェクト見つからない
15 1405 405 method not allowed メソッドが正しくない
16 1413 413 request entity too long リクエストパラメータの値が長すぎる
17 1500 500 internal server error API処理で異常が発生しました

制限事項

API実行に関する制限事項

同一 API Key で一度に学習できるモデルは一つまでです
同一datasetに対して作れるモデルは1つだけです。modelが失敗した場合など、同じ学習データでモデルを作り直したいときはdataset の呼出しと学習データのアップロードからやり直してください。


モデル作成インスタンスに関する制限事項

バージョンv2では、最大3並列までとなります
3並列すべてのインスタンスにリクエストがきている場合は、いずれかの学習が完了次第順次割り当てになります。モデル作成に時間がかかることもありますがご了承ください。

Text Suggest API (get model status)

ユーザー独自モデル作成用のAPIです。
check_statusではmodelで作成を開始したモデルの状況を確認することができます。

エンドポイント

URL:
https://api.a3rt.recruit-tech.co.jp/text_suggest/v2/check_status
メソッド:
GET
No. エンドポイント 説明
1 check_status パラメータとして指定されたモデルのステータスを返却します。

リクエストパラメータ

No. パラメータ名 説明 値サンプル 制約 必須
1 apikey APIキーを指定します AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 半角英数字
2 model_id モデルIDを指定します
(modelでレスポンスとして受けたもの)
xxxxxxxxxx 半角英数字・ハイフン
3 callback コールバックを指定します jQuery18308453692126555485_1471946187158 レスポンス ContentType は
callback 未指定時:application/json
callback 指定時:applocation/javascript
-

レスポンスフィールド

No. フィールド名 説明 値サンプル 返却条件 複数項目
1 status 処理ステータス 0 int 常に返却 -
2 message メッセージ ok string 常に返却 -
3 model_status モデルステータス
pending: 学習が予約されている状態
running: 学習中の状態
finish: 学習が完了し、suggest できる状態
failure: 学習が失敗した状態

finishの状態になればそのmodel_idをsuggestで指定することができます
running string 常に返却 -

ステータスコード / メッセージ

No. status HTTP
status
message 返却条件
1 0 200 ok 正常応答
2 1000 400 apikey is null APIキー未指定
3 1001 400 apikey not found APIキーが見つからない
4 1002 400 deleted account 退会済み
5 1003 400 temporary account アカウント未承認
6 1010 400 server not found サーバが見つからない
7 1011 400 server parameter error サーバ設定エラー
8 1030 403 access deny アクセス拒否
9 1400 400 bad request リクエストパラメータが不正
10 1404 404 not found 指定したオブジェクト見つからない
11 1405 405 method not allowed メソッドが正しくない
12 1500 500 internal server error サーバ処理中に想定外のエラーが発生

制限事項

なし

SAMPLE REQUEST

  • suggest
  • dataset_URL
  • create_model
  • model_status

1. 正常時(callback指定なし)

リクエスト https://api.a3rt.recruit-tech.co.jp/text_suggest/v2/predict?apikey=AAAAAAAAAAAAAAAA&previous_description=馬
レスポンス

{						
	"status": 0,							
	"message": "ok",							
	"suggestion":[
		"の横に、2人の男性がいます。", 
		"が二頭と猫が一匹います。",
		"に乗っています。"
    ]					
}						

							             				

2. 正常時(callback パラメータ指定)

リクエスト https://api.a3rt.recruit-tech.co.jp/text_suggest/v2/predict?apikey=AAAAAAAAAAAAAAAA&previous_description=馬&callback=jQuery18308453692126555485_1471946187158
レスポンス

jQuery18308453692126555485_1471946187158(						
	{
		“status”:0,
		“message”:”ok”,
		"suggestion":["の横に、2人の男性がいます。", 
		"が二頭と猫が一匹います。", 
		"に乗っています。"]
	}					
)

								             			

3. 正常時(styleに和歌を指定)

リクエスト https://api.a3rt.recruit-tech.co.jp/text_suggest/v2/predict?apikey=AAAAAAAAAAAAAAAA&previous_description=あき&style=1
レスポンス

{
	“status”:0,						
	“message”:”ok”,
	"suggestion":[
		"かせの こまくはにほふ なきのあれの やまかせしもの ゆふみにもしる",
		"かせの みやみをあへて ゆきけれは かかるやまたに すすみかたひに",
		"のよは たまつくもゐの はてやなき いとのまつらの なみそなくなり"
	]
}						

								             			

4. 正常時(styleにプログラミング言語(Go)を指定)

リクエスト https://api.a3rt.recruit-tech.co.jp/text_suggest/v2/predict?apikey=AAAAAAAAAAAAAAAA&previous_description=func&style=2
レスポンス

{
	“status”:0,					
	“message”:”ok”,
	"suggestion": [ 
		"(e []string) int {\n return fmt.Errorf(\" of 1 in to name in is value of not a the file is no in in \" + name,", 
		"() {\n if err != nil {\n return t, nil\n }",
 		"(op string) Type {\n if v := len(v.List); _, ok := buf.(*ast.Ident); ok {\n return nil\n }"
 	]
}						

								             			

5. 正常時(styleにユーザー独自モデルのmodel_idを指定)

リクエスト https://api.a3rt.recruit-tech.co.jp/text_suggest/v2/predict?apikey=AAAAAAAAAAAAAAAA&previous_description=今日は&style=xxxxxxxxxxx
レスポンス

{
	“status”:0,					
	“message”:”ok”,
	"suggestion":[
		"晴れるでしょう。",
		"良い天気です。"
	]
}						

								             			

6. 異常時(callback パラメータ未指定)

リクエスト https://api.a3rt.recruit-tech.co.jp/text_suggest/v2/predict?apikey=AAAAAAAAAAAAAAAA
レスポンス

{						
	status: 1400,
	message: "bad request",
}				

								             			

7. 異常時(callback パラメータ指定)

リクエスト https://api.a3rt.recruit-tech.co.jp/text_suggest/v2/predict?apikey=AAAAAAAAAAAAAAAA&callback=jQuery18308453692126555485_1471946187158
レスポンス

jQuery18308453692126555485_1471946187158({						
	status: 1400,
	message: "bad request",
})

								             			

ライセンス

  • ・現代文の生成モデルにはMS COCOの画像データに対して日本語のキャプションを付与したデータセットである「YJ Captions Dataset」を利用しております。
      https://github.com/yahoojapan/YJCaptions
  • ・和歌の生成モデルには新古今和歌集のテキストデータを利用しております。
  • ・Go言語の生成モデルにはGo言語のソースコードを利用しております。
      Copyright (c) 2009 The Go Authors. All rights reserved.
      https://github.com/golang/go/blob/master/LICENSE

前提条件:
  APIキーを事前に取得している
  curlコマンドが実行できる環境がある

1. ファイル配置のURLとデータセットIDを取得する

リクエスト curl -X POST https://api.a3rt.recruit-tech.co.jp/text_suggest/v2/dataset \
-d apikey=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
レスポンス

{							
	"status": 0,
	"message": "ok",
	“dataset_id”: “xxxxxxxxxxx”,
	“dataset_url”: “https://・・・”
}

							             			

2. ローカルにあるファイルをdataset_urlに配置する

リクエスト curl -D - -X PUT --upload-file <filepath> '<dataset_url>'
レスポンス

HTTP/1.1 200 OK
x-amz-id-2: JoZeEY2C95dJJUMo1ebTG2B+BWvmv4EYn4pAzOPXvMILRYmTzOSyKxcZR4+lec7oHOjC2Gv8AP4=
x-amz-request-id: C11436677B8AEE17
Date: Mon, 20 Feb 2017 10:22:46 GMT
ETag: "892d7981b3f8bdf7de55f3d00f7cf0a3"
Content-Length: 0
Server: AmazonS3											

									             	

前提条件:
  APIキーを事前に取得している
  curlコマンドが実行できる環境がある
  dataset APIを用いてdataset_idを取得済み
  学習用データをアップロード済み

1. 配置したデータセットに対して学習を開始する

リクエスト curl -X POST https://api.a3rt.recruit-tech.co.jp/text_suggest/v2/model \
-d apikey=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA \
-d dataset_id=xxxxxxxxxxx
レスポンス

{							
	"status": 0,
	"message": "ok",
	“model_id”: “xxxxxxxxxx”
}													

						               				

前提条件:
  APIキーを事前に取得している
  curlコマンドが実行できる環境がある
  model APIを使用してmodel_idを取得済み

1. 学習しているモデルのステータスを確認する

リクエスト curl -X GET 'https://api.a3rt.recruit-tech.co.jp/text_suggest/v2/check_status?apikey=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA&model_id=xxxxxxxxxx'
レスポンス

{							
	"status": 0,
	"message": "ok",
	“model_status”: “finish”
}