手書文字列認識
API リファレンス
第 1.0 版
2018 年 8 月 2 日 富士通株式会社
変更履歴
版数 修正日 修正箇所 修正内容
はじめに
本書の目的 本書は、Zinrai プラットフォームサービスが提供する API について説明しています。 本書の対象読者 本書は、Zinrai プラットフォームサービスでアプリケーションやサービスを開発・運用する方を対象に記述します。 本書を読むためには、以下の知識が必要です。 ・インターネットに関する基本的な知識 ・使用するオペレーティングシステムに関する基本的な知識 ・WebAPI に関する基本的な知識 お願い ・本書で使用している画面イメージ、実行例などは、最新環境のものとは異なることがあります。 ・本書は、予告なしに変更されることがあります。 ・本書を無断で他に転用しないようお願いします。 ・本書に記載されたデータの使用に起因する第三者の特許権およびその他の権利の侵害については、当社 はその責を負いません。 輸出管理規制について 本ドキュメントを輸出または第三者へ提供する場合は、お客様が居住する国および米国輸出管理関連法 規等の規制をご確認のうえ、必要な手続きをおとりください。 登録商標について 本書に記載されている会社名および製品名は、それぞれ各社の商標または登録商標である場合があります。 なお、本書では、会社名および製品名に付記される登録表示((TM)または(R))は省略しています。目次
第 1 章 API 概要 ... 5 1.1 基本利用方法 ... 5 1.2 API 一覧 ... 5 第 2 章 共通仕様 ... 6 2.1 エンドポイント ... 6 2.2 プロトコル ... 6 2.3 文字コード ... 6 2.4 HTTP ヘッダ ... 6 2.5 HTTP ステータスコード ... 7 2.6 エラー形式 ... 7 2.6.1 共通ヘッダ関連のエラー ... 9 第 3 章 API 詳細 ... 10 3.1 手書文字列認識 ... 10 3.1.1 リクエスト ... 10 3.1.2 レスポンス ... 12 3.1.3 実行例 ... 14 3.2 認識結果取得 ... 15 3.2.1 リクエスト ... 15 3.2.2 レスポンス ... 16 3.2.3 実行例 ... 18 3.3 結果削除 ... 20 3.3.1 リクエスト ... 20 3.3.2 レスポンス ... 20 3.3.3 実行例 ... 21 3.4 処理一覧取得 ... 22 3.4.1 リクエスト ... 22 3.4.2 レスポンス ... 22 3.4.3 実行例 ... 23 3.5 モデル一覧取得 ... 24 3.5.1 リクエスト ... 24 3.5.2 レスポンス ... 24 3.5.3 実行例 ... 25 付録 A パラメータ仕様 ... 26 付録 B モデル組み合わせ一覧 ... 27 付録 C 認識可能な記号文字 ... 27第1章 API 概要
手書文字列認識では、お客様が入力した画像データの文字列を解析します。1.1 基本利用方法
本 API の基本的な利用方法は以下の通りです。 1. 手書文字列認識 API により、画像データ(注)に記述された１行の文字列を解析し、結果をテキスト として取得することができます。 (注)手書文字列認識 API へ入力するデータは、画像データを指定のエンコード形式(base64 など) でエンコードしたデータとなります。1.2 API 一覧
提供する API 一覧は、以下の通りです。 概要 URI メソッド 参照 手書文字列認識 /HandwrittenTextLineRecognition/v1/re cognitions POST 3.1 認識結果取得 /HandwrittenTextLineRecognition/v1/rec ognitions/{act_id} GET 3.2 結果削除 /HandwrittenTextLineRecognition/v1/rec ognitions/{act_id} DELETE 3.3 処理一覧取得 /HandwrittenTextLineRecognition/v1/rec ognitions GET 3.4 モデル一覧取得 /HandwrittenTextLineRecognition/v1/mo dels GET 3.5第2章 共通仕様
本章では、本 API の共通仕様を説明します。2.1 エンドポイント
zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com2.2 プロトコル
HTTPS ※暗号化プロトコルは TLS1.2 のみサポートしています。2.3 文字コード
UTF-82.4 HTTP ヘッダ
ヘッダ項目名 値 値の説明 X-Access-Token 例: 5f744f66-56d9-4c8c-87b2-c8 70f3b82817 本サービスでは K5 の API 認証を利用した アクセス制限を行っております。 API 利用者は本サービスの API をコールす る前に K5 認証よりアクセストークンを取得 し、本ヘッダの値にアクセストークンを設定し て API をコールしてください。 ※アクセストークンの取得方法等について は、こちらのリファレンスをご参照ください。 X-Service-Code “サービスコード[10 桁]”-“API 番号 [5 桁]” 例: FJAI000016-00001 K5 PaaS Portal で各サービスに割り振ら れたコード（10 桁）と、各サービスの各 API が持つ固有の番号（5 桁）をハイフ ンで繋ぎ合わせた文字列です。実際の値 は、「第 3 章 API 詳細」のリクエストヘッダ 仕様をご参照ください。2.5 HTTP ステータスコード
ステータスコード 意味 説明 200 OK リクエストは正常に処理されました。 201 Created リクエストは正常に処理され、新規リソースが作成さ れました。 202 Accepted リクエストを正常に受け付けました。 400 Bad Request リクエストの内容に誤りがあります。 401 Unauthorized 認証に失敗しました。 404 Not Found リソースが見つからなかった。 408 Request Timeout リクエストタイムアウトが発生しました。 再度、API の実行をお願いします。 415 Unsupported Media Type リクエストヘッダの Content-Type がサポート対象外 です。 500 Internal Server Error サーバ内部にエラーが発生しました。 503 Service Unavailable ・サービスを一時的に利用できません。 ・予期しないエラーが発生しました。2.6 エラー形式
JSON で以下の情報を返します。 1) リクエストパラメータの誤りや処理に関連するエラーの場合 ※第 3 章 API 詳細に記載するエラー情報は本エラー形式となります。 名前 説明 error エラー情報のオブジェクト code エラーコード title エラータイトル(英語) message エラーメッセージ(英語) レスポンス例 { "error": {"message": "Parameter error", "code": 400,
"title": "BAD_REQUEST" }
2) リクエストヘッダやボディの構造に誤りがある場合 名前 説明 timestamp 時刻情報 status HTTP ステータスコード error エラータイトル message エラーメッセージ path パス情報 レスポンス例 { "timestamp":"2018-05-08T06:13:26.150+0000", "status":400,
"error": "Bad Request",
"message":"Required request body is missing:…",
"path": "/HandwrittenTextLineRecognition/v1/recognitions" }
2.6.1 共通ヘッダ関連のエラー
コード タイトル メッセージ
400 Bad Request You have requested incorrect parameters. (XXXXXXXX) 上記のエラーが返却された場合、以下を確認してください。 ・リクエストに X-Access-Token ヘッダが無い ・X-Access-Token ヘッダの値が正しくない ・リクエストに X-Service-Code ヘッダが無い ・X-Service-Code ヘッダの値のフォーマットが正しくない コード タイトル メッセージ
401 Unauthorized This server could not verify your authorization to access. (XXXXXXXX)
上記のエラーが返却された場合、以下を確認してください。 ・X-Access-Token ヘッダの値が正しくない
コード タイトル メッセージ
404 Not Found We could not find the resource you requested. (XXXXXXXX) 上記のエラーが返却された場合、以下を確認してください。 ・X-Service-Code ヘッダの値が正しくない ・HTTP メソッドまたは URL が誤っている コード タイトル メッセージ 500 Internal Server Error
The server encountered an internal error. (XXXXXXXX) 上記のエラーが返却された場合、以下を確認してください。
・X-Access-Token ヘッダの値が正しくない
第3章 API 詳細
本章では、各 API の詳細仕様を説明します。パラメータの表記については、「付録 A パラメータ仕様」をご 参照ください。3.1 手書文字列認識
手書き文字の画像データの認識処理を受け付けます。 認識可能な画像形式は”jpeg”, “png”, “bmp”の 3 種です。 リクエストデータには、画像データを指定のエンコード形式でエンコードしたデータを指定します。 リクエストデータに含まれるエンコードされたデータの総サイズは最大 50MB です。 処理結果の保有数の上限は 5,000 件です。 認識処理中でも新たな認識要求の受け付けができますが、サーバリソースの状況に因り、エラーレスポンスを 返却する場合が有ります。 認識結果の保持期間は、認識完了後 24 時間です。保持期間を超えた場合、認識結果は削除されま す。 URI /HandwrittenTextLineRecognition/v1/recognitions HTTP メソッド POST 3.1.1 リクエスト ヘッダ 名前 値 補足 X-Service-Code FJAI000016-00001 - Content-Type application/json;charset=UTF-8 - パラメータ なし メッセージボディ 形式：JSON 名前 説明 型 必須 既定値 singleImage 一行のイメージの情報 object(singleImage) ○ - singleImage 名前 説明 型 必須 既定値 recognitionObjects 認識対象の情報 object(recognitio ○ -認識対象数:1～100 nObjects)[] recognitionObjects 名前 説明 型 必 須 既定 値 name フィールド名 (仕様) string ○ - lineObject 一行の情報 object(lineObject) ○ - option オプション情報 object(option) - name 仕様 文字数は 1～120 文字で、文字には半角英数字、半角ハイフン(-)、半角アンダーバー(_)が 使用できます。 lineObject 名前 説明 型 必 須 既定 値 encodeImage エンコードされたイメージデータ (仕様) string ○ - encodeType エンコード形式 ※以下の形式を指定できます。 “base64string” string ○ - encodeImage 仕様 ・ 画像データを encodeType に指定する形式でエンコードしたデータ（文字列）を指定します。 ・ 1 フ ィ ー ル ド の バ イ ト 数 の 最 大 は 、 20,000,160 バ イ ト で す 。 但 し 、 1 リ ク エ ス ト の encodeImage の総バイト数は、52,428,800 バイトまでとなります。 ・ 元のイメージの寸法(幅×高さ)の範囲は、10px × 10px ～ 5,000px × 1,000px で す。 ・ 元イメージには、最大 24bit 色(フルカラー) のイメージまで使用できます.。 ・ イメージの形式が bmp 形式の場合、ファイルサイズが大きく、サーバへのイメージ転送に時間を要 するため、jpeg 形式、あるいは png 形式を推奨します。 ・ 文字色よりも背景色が濃いイメージは、文字を認識できない場合があります。 option 名前 説明 型 必須 既定 値 characterModel 文字種モデル string ※1 fieldModel フィールドモデル string ※1
correction 認識結果補正の利用有無 false: 補正しない true: 補正する boolean false option 仕様 ・ 認識結果補正を行うことで認識結果が向上するケースが有ります。 ・ 選択可能な characterModel、fieldModel、correction の組み合わせは付録 B モデル組み 合わせ一覧を参照ください。尚、組み合わせ一覧は、モデル一覧取得により取得できます。 ・ (※1)characterModel と fieldModel が共に指定が無い場合は、characterModel=全文
字種、fieldModel=日本語一版として処理します。
・ characterModel あるいは、fieldModel の一方のみ指定された場合は、Bad Request を返 却します。
・ characterModel と fieldModel の組み合わせが選択不可の場合、Bad Request を返却し ます。
・ characterModel と fieldModel の組み合わせで、結果補正未対応の場合は、correction の 指定は無視されます。 3.1.2 レスポンス ヘッダ 名前 値 補足 Content-Type application/json X-Asynchronous-CallId 任意 非同期処理用の ID メッセージボディ 形式：JSON 名前 説明 型 act_id 処理受付 ID string エラー情報 コード タイトル メッセージ
400 BAD_REQUEST Field size is out of range.
※フィールド数が許容範囲外の場合に本メッセー ジが出力されます。
400 BAD_REQUEST Request parameter error.
が出力されます。
400 BAD_REQUEST {name} is request parameter error. ※フィールド内のリクエストパラメータが不正の場合 に本メッセージが出力されます。
400 BAD_REQUEST {フィールド名} is name character max size over.
※フィールド名の文字数が上限を超えている場合 に本メッセージが出力されます。
400 BAD_REQUEST {name} is unsupported name.
※フィールド名に使用禁止文字が含まれている場 合に本メッセージが出力されます。
400 BAD_REQUEST {name} is base64 character max size over
※base64string の文字数が許容範囲外の場 合に本メッセージが出力されます。
400 BAD_REQUEST {name} is unsupported image format. ※イメージ形式がサポート外である場合に本メッセ ージが出力されます。
400 BAD_REQUEST {name} is unsupported encode type. ※エンコードタイプがサポート対象外ある場合に本 メッセージが出力されます。
400 BAD_REQUEST {name} is request option parameter error.
※option パラメータの指定に誤りがある場合に本 メッセージが出力されます。
400 BAD_REQUEST Request parameter data size over. ※base64string の文字数の合計が上限を超え ている場合に本メッセージが出力されます。 400 BAD_REQUEST The number of acceptances is the
maximum.
※処理受付保有数が上限値に達している場合に 本メッセージが出力されます。
503 SERVICE_UNAVAILABLE Service temporarily unavailable.
※一時的に処理受付ができない場合に本メッセ ージが出力されます。
3.1.3 実行例 リクエスト
curl -X POST "https://zinrai-pf.jp-east-1.paas.cloud.global.fujit su.com/HandwrittenTextLineRecognition/v1/recognitions" -H "X-Acce ss-Token: 000000000000000000000000000000000000" -H "X-Service-Cod e: FJAI000016-00001" -H "Content-Type: application/json;charset=UT F-8" -d '{"singleImage":{"recognitionObjects":[{"name":"image001" ,"lineObject":{"encodeImage":"base64stringImage","encodeType":"ba se64string"},"option":{"characterModel":"all", "fieldModel":"gen_ all", "correction":false}},{"name":"image002","lineObject":{"enco deImage":"base64stringImage","encodeType":"base64string"},"option ":{"characterModel":"all", "fieldModel":"gen_all", "correction":t rue}}]}}' ※base64stringImage には各イメージの base64 文字列が入ります。 レスポンス { "act_id": "100022_20180402123456789" }
3.2 認識結果取得
非同期で処理中の手書文字列認識処理の結果、あるいは処理状態を取得します。 URI /HandwrittenTextLineRecognition/v1/recognitions/{act_id} HTTP メソッド GET 結果は以下のような構造で返します。 3.2.1 リクエスト ヘッダ 名前 値 補足 X-Service-Code FJAI000016-00006 - X-Asynchronous-CallId 手書文字列認識 API のレスポンスヘッダ の X-Asynchronous-CallId または、レスポンスボディの act_id 非同期処理用の ID パラメータ 名前 説明 種別 必須 既定値 act_id 処理受付 ID path 〇 - option オプション指定 delete: 完了・エラーの状態取得 後に結果を削除 query 指定無し 結果 画像 データ 手書文字列 認識結果 エラー情報 状態 フィールド [配列] ラインオブジェクト フィールド名 補正後の結果 文字情報 [配列] 文字 スコア 認識結果 処理状態 メッセージボディ なし 3.2.2 レスポンス ヘッダ 名前 値 補足 Content-Type application/json;charset=UTF-8 メッセージボディ 形式：JSON 名前 説明 型 status 処理状態 以下の 4 種類のいずれかが設定されます。 "ready" : 準備中 "processing" : 処理中 "completed" : 完了 "error" : エラー終了 string results 結果情報 status が”completed”の場合に有効です。 object(results) errorinfo エラー情報 status が"error"の場合に有効です。 string results 名前 説明 型 fields 認識対象フィールドの結果の配列 object(fields) [] fields 名前 説明 型 name フィールド名 string status 処理状態 以下の 1 種類が設定されます。 "ready" : 準備中 "processing" : 処理中 "completed" : 完了 "error" : エラー終了 string lineObject 認識対象の 1 行フィールドの結果情報 status が”completed”の場合に有効です。 object(lineObject)
errorinfo エラー情報 status が”error”の場合に有効 string lineObject 名前 説明 型 text 補正処理実施後の認識結果 (全角文字) 補正無しの場合は”textRaw”と同一になり ます。 string textRaw 認識結果 (全角文字) string characters 各文字のスコアを含むオブジェクトの配列 object(characters)[] characters 名前 説明 型 character 一文字 string score 信頼度のスコア (範囲: 0.0～1.0) 1.0 に近いほど信頼度が高いことを示しま す。 number(浮動小数点) エラー情報 コード タイトル メッセージ
404 NOT_FOUND act_id does not exist.
※{act_id}が存在しない場合に本メッセージ が出力されます。
3.2.3 実行例 リクエスト 例) オプション未指定の場合 curl -X GET "https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/Handwr ittenTextLineRecognition/v1/recognitions/100022_20180601123456789 " -H "X-Access-Token: 000000000000000000000000000000000000" -H "X-Service-Code: FJAI000016-00006" -H "X-Asynchronous-CallId": "100022_20180601123456789" 例) オプション(delete)指定の場合 curl -X GET "https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/Handwr ittenTextLineRecognition/v1/recognitions/100022_20180601123456789 ?option=delete" -H "X-Access-Token: 000000000000000000000000000000000000" -H "X-Service-Code: FJAI000016-00006" -H "X-Asynchronous-CallId": "100022_20180601123456789" レスポンス 手書文字列認識準備中の場合 { "status": "ready" } 手書文字列認識処理中の場合 { "status": "processing" }
手書文字列認識処理完了の場合 { "status": "completed", "results": { "fields": [ { "name": "img001", "status": "completed", "lineObject": { "text": "結果", "textRaw”: "結果", "characters": [ { "character": "結", "score": 0.997 }, { "character": "果", "score": 0.996 } ] } }, { "name": "img002", "status": "completed", "lineObject": { :: (省略) } } ] } } 手書文字列認識処理エラーの場合 { "status": "error",
"errorinfo": "error information" }
3.3 結果削除
手書文字列認識処理結果を削除します。 但し、処理状態が処理中である場合は、削除できません。 URI /HandwrittenTextLineRecognition/v1/recognitions/{act_id} HTTP メソッド DELETE 3.3.1 リクエスト ヘッダ 名前 値 補足 X-Service-Code FJAI000016-00008 - X-Asynchronous-CallId 手書文字列認識 API のレスポンスヘッダの X-Asynchronous-CallId または、レスポンスボディの act_id 非同期処理用の ID パラメータ 名前 説明 種別 必須 既定値 act_id 処理受付 ID path 〇 - メッセージボディ なし 3.3.2 レスポンス ヘッダ なし メッセージボディ なし エラー情報 コード タイトル メッセージ404 NOT_FOUND act_id does not exist.
※{act_id}が存在しない場合に本メッセー ジが出力されます。
409 CONFLICT act_id is in use.
が出力されます。 3.3.3 実行例
リクエスト
curl -X DELETE "https://zinrai-pf.jp-east-1.paas.cloud.global.fuj itsu.com/HandwrittenTextLineRecognition/v1/recognitions/100022_20 170703123456789" -H "X-Access-Token: 0000000000000000000000000000 00000000" -H "X-Service-Code: FJAI000016-00008" -H "X-Asynchronous -CallId":"100022_20180601123456789"
レスポンス
3.4 処理一覧取得
手書文字列認識の処理受付 ID 一覧を取得します。 受付 ID 保有数が多い場合、レスポンスが遅くなります。 URI /HandwrittenTextLineRecognition/v1/recognitions HTTP メソッド GET 3.4.1 リクエスト ヘッダ 名前 値 補足 X-Service-Code FJAI000016-00002 - パラメータ なし メッセージボディ なし 3.4.2 レスポンス ヘッダ 名前 値 補足 Content-Type application/json メッセージボディ 形式：JSON 名前 説明 型 act_ids 処理受付 ID 一覧 object(act_ids) [] act_ids 名前 説明 型 act_id 処理受付 ID stringstatus 処理状態 以下の 4 種類のいずれかが設定されます。 “ready”: 準備中 “processing”: 処理中 “completed”: 完了 “error”: エラー終了 string エラー情報 なし 3.4.3 実行例 リクエスト
curl -X GET "https://zinrai-pf.jp-east-1.paas.cloud.global.fujits u.com/HandwrittenTextLineRecognition/v1/recognitions" -H "X-Acces s-Token: 000000000000000000000000000000000000" -H "X-Service-Code : FJAI000016-000XX" レスポンス { "act_ids":[ { "act_id", "100022_20180601123456789", "status": "processing" }, :: (省略) ] }
3.5 モデル一覧取得
使用できる文字種モデルとフィールドモデルの組み合わせ一覧を取得します。 モデルの組み合わせについては、付録 B モデル組み合わせ一覧を参照ください。 URI /HandwrittenTextLineRecognition/v1/models HTTP メソッド GET 3.5.1 リクエスト ヘッダ 名前 値 補足 X-Service-Code FJAI000016-00102 - パラメータ なし メッセージボディ なし 3.5.2 レスポンス ヘッダ 名前 値 補足 Content-Type application/json メッセージボディ 形式：JSON 名前 説明 型 models モデルのリスト object(models) [] models 名前 説明 型 characterModel 文字種モデル名 string description 文字種モデルの説明 string fielldModels 文字種モデルで使用できるフィールドモデ ルの情報 object(fielldModels) [] fielldModels 名前 説明 型 fieldModel フィールドモデル名 string description フィールドモデルの説明 string correction 結果補正の利用可否 false: 利用不可 true: 利用可 boolean エラー情報 なし 3.5.3 実行例 リクエスト
curl -X GET "https://zinrai-pf.jp-east-1.paas.cloud.global.fujits u.com/HandwrittenTextLineRecognition/v1/models" -H "X-Access-Toke n: 000000000000000000000000000000000000" -H "X-Service-Code: FJAI0 00016-00102" レスポンス { "models": [ { "characterModel": "all", "description": "全文字種", "fielldModels": [ { "fieldModel": "gen_all", "description": "日本語一般", "correction": true }, :: (省略) ] }, :: (省略) ] }
付録A パラメータ仕様
本書では、API 毎にパラメータを以下のように種別分けしています。 種別 説明 path URI の中で、クエリ文字列以外（リソース名など）で指定する。 値のみで、パラメータ名は記述されない。 例：/Sample/v1/samp_file/0001 query URI の中で、クエリ文字列で指定する 例：/Sample/v1/samp_file/0001?param1=AAA本 API におけるリクエスト／レスポンスボディの形式は、JSON を基本とします。JSON の場合、本書では、 型について、以下のように表記します。
型 説明
string ダブルクォーテーションで括った文字列
number 数値（整数、浮動小数点数）
boolean 真偽値（true と false）
array ※[]表記 配列
