変更履歴 版数修正日修正箇所修正内容 /8/2 初版 2 / 27

Transcription

1 手書文字列認識 API リファレンス 第 1.0 版 2018 年 8 月 2 日 富士通株式会社 1 / 27

2 変更履歴 版数修正日修正箇所修正内容 /8/2 初版 2 / 27

3 はじめに 本書の目的 本書は Zinrai プラットフォームサービスが提供する API について説明しています 本書の対象読者本書は Zinrai プラットフォームサービスでアプリケーションやサービスを開発 運用する方を対象に記述します 本書を読むためには 以下の知識が必要です インターネットに関する基本的な知識 使用するオペレーティングシステムに関する基本的な知識 WebAPI に関する基本的な知識 お願い 本書で使用している画面イメージ 実行例などは 最新環境のものとは異なることがあります 本書は 予告なしに変更されることがあります 本書を無断で他に転用しないようお願いします 本書に記載されたデータの使用に起因する第三者の特許権およびその他の権利の侵害については 当社はその責を負いません 輸出管理規制について 本ドキュメントを輸出または第三者へ提供する場合は お客様が居住する国および米国輸出管理関連法 規等の規制をご確認のうえ 必要な手続きをおとりください 登録商標について 本書に記載されている会社名および製品名は それぞれ各社の商標または登録商標である場合があります なお 本書では 会社名および製品名に付記される登録表示 ((TM) または (R)) は省略しています 3 / 27

4 目次 第 1 章 API 概要 基本利用方法 API 一覧... 5 第 2 章共通仕様 エンドポイント プロトコル 文字コード HTTP ヘッダ HTTP ステータスコード エラー形式 共通ヘッダ関連のエラー... 9 第 3 章 API 詳細 手書文字列認識 リクエスト レスポンス 実行例 認識結果取得 リクエスト レスポンス 実行例 結果削除 リクエスト レスポンス 実行例 処理一覧取得 リクエスト レスポンス 実行例 モデル一覧取得 リクエスト レスポンス 実行例 付録 A パラメータ仕様 付録 B モデル組み合わせ一覧 付録 C 認識可能な記号文字 / 27

5 第 1 章 API 概要 手書文字列認識では お客様が入力した画像データの文字列を解析します 1.1 基本利用方法本 API の基本的な利用方法は以下の通りです 1. 手書文字列認識 API により 画像データ ( 注 ) に記述された1 行の文字列を解析し 結果をテキストとして取得することができます ( 注 ) 手書文字列認識 API へ入力するデータは 画像データを指定のエンコード形式 (base64 など ) でエンコードしたデータとなります 1.2 API 一覧提供する API 一覧は 以下の通りです 概要 URI メソッド 参照 手書文字列認識 /HandwrittenTextLineRecognition/v1/re POST 3.1 cognitions 認識結果取得 /HandwrittenTextLineRecognition/v1/rec GET 3.2 ognitions/act_id 結果削除 /HandwrittenTextLineRecognition/v1/rec DELETE 3.3 ognitions/act_id 処理一覧取得 /HandwrittenTextLineRecognition/v1/rec GET 3.4 ognitions モデル一覧取得 /HandwrittenTextLineRecognition/v1/mo dels GET / 27

6 第 2 章共通仕様 本章では 本 API の共通仕様を説明します 2.1 エンドポイント zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com 2.2 プロトコル HTTPS 暗号化プロトコルは TLS1.2 のみサポートしています 2.3 文字コード UTF HTTP ヘッダ ヘッダ項目名 値 値の説明 X-Access-Token 例 : 5f744f66-56d9-4c8c-87b2-c8 70f3b82817 本サービスでは K5 の API 認証を利用したアクセス制限を行っております API 利用者は本サービスの API をコールする前に K5 認証よりアクセストークンを取得し 本ヘッダの値にアクセストークンを設定して API をコールしてください アクセストークンの取得方法等については こちらのリファレンスをご参照ください X-Service-Code サービスコード [10 桁 ] - API 番号 [5 桁 ] 例 : FJAI K5 PaaS Portal で各サービスに割り振られたコード (10 桁 ) と 各サービスの各 API が持つ固有の番号 (5 桁 ) をハイフンで繋ぎ合わせた文字列です 実際の値は 第 3 章 API 詳細 のリクエストヘッダ 仕様をご参照ください 6 / 27

7 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" 7 / 27

8 2) リクエストヘッダやボディの構造に誤りがある場合名前説明 timestamp 時刻情報 status HTTP ステータスコード error エラータイトル message エラーメッセージ path パス情報レスポンス例 "timestamp":" t06:13: ", "status":400, "error": "Bad Request", "message":"required request body is missing: ", "path": "/HandwrittenTextLineRecognition/v1/recognitions" 8 / 27

9 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 ヘッダの値が正しくない XXXXXXXX には任意の文字列が入ります 9 / 27

10 第 3 章 API 詳細 本章では 各 API の詳細仕様を説明します パラメータの表記については 付録 A パラメータ仕様 をご 参照ください 3.1 手書文字列認識手書き文字の画像データの認識処理を受け付けます 認識可能な画像形式は jpeg, png, bmp の 3 種です リクエストデータには 画像データを指定のエンコード形式でエンコードしたデータを指定します リクエストデータに含まれるエンコードされたデータの総サイズは最大 50MB です 処理結果の保有数の上限は 5,000 件です 認識処理中でも新たな認識要求の受け付けができますが サーバリソースの状況に因り エラーレスポンスを返却する場合が有ります 認識結果の保持期間は 認識完了後 24 時間です 保持期間を超えた場合 認識結果は削除されます URI HTTP メソッド /HandwrittenTextLineRecognition/v1/recognitions POST リクエスト ヘッダ 名前 値 補足 X-Service-Code FJAI Content-Type application/json;charset=utf-8 - パラメータ なし メッセージボディ 形式 :JSON 名前 説明 型 必須 既定値 singleimage 一行のイメージの情報 object(singleimage) - singleimage 名前説明型必須既定値 recognitionobjects 認識対象の情報 object(recognitio - 10 / 27

11 認識対象数 :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 11 / 27

12 correction 認識結果補正の利用有無 boolean false false: 補正しない true: 補正する option 仕様 認識結果補正を行うことで認識結果が向上するケースが有ります 選択可能な charactermodel fieldmodel correction の組み合わせは付録 B モデル組み合わせ一覧を参照ください 尚 組み合わせ一覧は モデル一覧取得により取得できます ( 1)characterModel と fieldmodel が共に指定が無い場合は charactermodel= 全文字種 fieldmodel= 日本語一版として処理します charactermodel あるいは fieldmodel の一方のみ指定された場合は Bad Request を返却します charactermodel と fieldmodel の組み合わせが選択不可の場合 Bad Request を返却します charactermodel と fieldmodel の組み合わせで 結果補正未対応の場合は correction の指定は無視されます レスポンス ヘッダ 名前 値 補足 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. リクエストパラメータが不正の場合に本メッセージ 12 / 27

13 が出力されます 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. 一時的に処理受付ができない場合に本メッセ ージが出力されます 13 / 27

14 3.1.3 実行例 リクエスト curl -X POST " su.com/handwrittentextlinerecognition/v1/recognitions" -H "X-Acce ss-token: " -H "X-Service-Cod e: FJAI " -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_ " 14 / 27

15 3.2 認識結果取得 非同期で処理中の手書文字列認識処理の結果 あるいは処理状態を取得します URI HTTP メソッド /HandwrittenTextLineRecognition/v1/recognitions/act_id GET 結果は以下のような構造で返します 画像 データ 手書文字列認識結果 状態結果フィールド [ 配列 ] フィールド名処理状態ラインオブジェクト補正後の結果認識結果文字情報 [ 配列 ] 文字スコアエラー情報 リクエスト ヘッダ 名前 値 補足 X-Service-Code FJAI X-Asynchronous- CallId 手書文字列認識 API のレスポンスヘッダの X-Asynchronous-CallId または レスポンスボディの act_id 非同期処理用の ID パラメータ名前 説明 種別 必須 既定値 act_id 処理受付 ID path 〇 - option オプション指定 delete: 完了 エラーの状態取得後に結果を削除 query 指定無し 15 / 27

16 メッセージボディ なし レスポンス ヘッダ 名前 値 補足 Content-Type application/json;charset=utf-8 メッセージボディ 形式 :JSON 名前 説明 型 status 処理状態 string 以下の 4 種類のいずれかが設定されます "ready" : 準備中 "processing" : 処理中 "completed" : 完了 "error" : エラー終了 results 結果情報 object(results) status が completed の場合に有効です errorinfo エラー情報 status が "error" の場合に有効です string results 名前説明型 fields 認識対象フィールドの結果の配列 object(fields) [] fields 名前 説明 型 name フィールド名 string status 処理状態 string 以下の 1 種類が設定されます "ready" : 準備中 "processing" : 処理中 "completed" : 完了 "error" : エラー終了 lineobject 認識対象の 1 行フィールドの結果情報 status が completed の場合に有効です object(lineobject) 16 / 27

17 errorinfo エラー情報 status が error の場合に有効 string lineobject 名前 説明 型 text 補正処理実施後の認識結果 ( 全角文字 ) string 補正無しの場合は textraw と同一になります 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 が存在しない場合に本メッセージ が出力されます 17 / 27

18 3.2.3 実行例 リクエスト 例 ) オプション未指定の場合 curl -X GET " ittentextlinerecognition/v1/recognitions/100022_ " -H "X-Access-Token: " -H "X-Service-Code: FJAI " -H "X-Asynchronous-CallId": "100022_ " 例 ) オプション (delete) 指定の場合 curl -X GET " ittentextlinerecognition/v1/recognitions/100022_ ?option=delete" -H "X-Access-Token: " -H "X-Service-Code: FJAI " -H "X-Asynchronous-CallId": "100022_ " レスポンス 手書文字列認識準備中の場合 "status": "ready" 手書文字列認識処理中の場合 "status": "processing" 18 / 27

19 手書文字列認識処理完了の場合 "status": "completed", "results": "fields": [ "name": "img001", "status": "completed", "lineobject": "text": " 結果 ", "textraw : " 結果 ", "characters": [ "character": " 結 ", "score": 0.997, "character": " 果 ", "score": ], "name": "img002", "status": "completed", "lineobject": :: ( 省略 ) ] 手書文字列認識処理エラーの場合 "status": "error", "errorinfo": "error information" 19 / 27

20 3.3 結果削除 手書文字列認識処理結果を削除します 但し 処理状態が処理中である場合は 削除できません URI HTTP メソッド /HandwrittenTextLineRecognition/v1/recognitions/act_id DELETE リクエスト ヘッダ 名前 値 補足 X-Service-Code FJAI X-Asynchronous- CallId 手書文字列認識 API のレスポンスヘッダの X-Asynchronous-CallId または レスポンスボディの act_id 非同期処理用の ID パラメータ 名前説明種別必須既定値 act_id 処理受付 ID path 〇 - メッセージボディ なし レスポンス ヘッダなし メッセージボディ なし エラー情報コード タイトル メッセージ 404 NOT_FOUND act_id does not exist. act_id が存在しない場合に本メッセージが出力されます 409 CONFLICT act_id is in use. act_id が処理中の場合に本メッセージ 20 / 27

21 が出力されます 実行例 リクエスト curl -X DELETE " itsu.com/handwrittentextlinerecognition/v1/recognitions/100022_ " -H "X-Access-Token: " -H "X-Service-Code: FJAI " -H "X-Asynchronous -CallId":"100022_ " レスポンス なし 21 / 27

22 3.4 処理一覧取得 手書文字列認識の処理受付 ID 一覧を取得します 受付 ID 保有数が多い場合 レスポンスが遅くなります URI HTTP メソッド /HandwrittenTextLineRecognition/v1/recognitions GET リクエスト ヘッダ 名前 値 補足 X-Service-Code FJAI パラメータ なし メッセージボディ なし レスポンス ヘッダ 名前 値 補足 Content-Type application/json メッセージボディ 形式 :JSON 名前 説明 型 act_ids 処理受付 ID 一覧 object(act_ids) [] act_ids 名前説明型 act_id 処理受付 ID string 22 / 27

23 status 処理状態以下の 4 種類のいずれかが設定されます ready : 準備中 processing : 処理中 completed : 完了 error : エラー終了 string エラー情報 なし 実行例 リクエスト curl -X GET " u.com/handwrittentextlinerecognition/v1/recognitions" -H "X-Acces s-token: " -H "X-Service-Code : FJAI XX" レスポンス "act_ids":[ "act_id", "100022_ ", "status": "processing", :: ( 省略 ) ] 23 / 27

24 3.5 モデル一覧取得 使用できる文字種モデルとフィールドモデルの組み合わせ一覧を取得します モデルの組み合わせについては 付録 B モデル組み合わせ一覧を参照ください URI HTTP メソッド /HandwrittenTextLineRecognition/v1/models GET リクエスト ヘッダ 名前 値 補足 X-Service-Code FJAI パラメータ なし メッセージボディ なし レスポンス ヘッダ 名前 値 補足 Content-Type application/json メッセージボディ 形式 :JSON 名前 説明 型 models モデルのリスト object(models) [] models 名前 説明 型 charactermodel 文字種モデル名 string description 文字種モデルの説明 string fielldmodels 文字種モデルで使用できるフィールドモデルの情報 object(fielldmodels) [] 24 / 27

25 fielldmodels 名前 説明 型 fieldmodel フィールドモデル名 string description フィールドモデルの説明 string correction 結果補正の利用可否 false: 利用不可 true: 利用可 boolean エラー情報 なし 実行例 リクエスト curl -X GET " u.com/handwrittentextlinerecognition/v1/models" -H "X-Access-Toke n: " -H "X-Service-Code: FJAI " レスポンス "models": [ "charactermodel": "all", "description": " 全文字種 ", "fielldmodels": [ "fieldmodel": "gen_all", "description": " 日本語一般 ", "correction": true, :: ( 省略 ) ], :: ( 省略 ) ] 25 / 27

26 付録 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 [] 表記 配列 object () 内にオブジェクト名表記 オブジェクト ( キーと値の組の集まり ) 26 / 27

27 付録 B モデル組み合わせ一覧 使用可能な文字種モデル フィールドモデル 及び結果補正利用可否の組み合わせを下記表に示します charactermodel 値 fieldmodel 値 補正 文字種モデル フィールドモデル 全文字種 all 日本語全般 gen_all ( 漢字 カタカナ ひらがな 住所 addr_all 数字 英字 記号 ) 会社名 comp_all 漢字 カタカナ ひらがな kanjikatahira 人名 name_kanji カタカナ kata 人名カタカナ name_kata カタカナ 数字 katanum カタカナ 数字一般 gen_kata カタカナ 数字 記号 katanummark 住所カタカナ addr_kata 会社名カタカナ comp_kata カタカナ 数字 英字 記号 katanumalphamark カタカナ一般 gen_kata 数字 num 数字一般 gen_num 数字 英字 numalpha 数字 英字一般 gen_numalpha 数字 記号 nummark. 電話番号 tel 数字 記号一般 gen_nummark 数字 英字 記号 numalphamark メールアドレス mail 漢字 : JIS 第一水準漢字 第二水準漢字 カタカナ カタカナ 数字モデルには一部の記号を含みます 詳細は付録 C をご参照ください 補正列 : = 補正利用可 組み合わせは 今後増えていく可能性があります 付録 C 認識可能な記号文字 記号文字については下記表ををご参照ください 記号一覧,. : ;?! ` ^ _ 々 〆 ー / \ ~ ( ) [ ] + - ± = < > $ % # & カタカナ カタカナ 数字モデルは下記の記号を含みます 記号一覧 ー 27 / 27