変更履歴 版数 修正日 修正箇所 修正内容 /4/27 初版 /7/27 - クリップボードへのコピーで不要な文字が含まれる事象を修正 /4/ 暗号化プロトコルのサポートについて記載 /8/ ステータス

Transcription

1 画像認識 API リファレンス 第 1.3 版 2018 年 8 月 2 日 富士通株式会社 1 / 21

2 変更履歴 版数 修正日 修正箇所 修正内容 /4/27 初版 /7/27 - クリップボードへのコピーで不要な文字が含まれる事象を修正 /4/ 暗号化プロトコルのサポートについて記載 /8/ ステータスコードの追記エラーメッセージの修正 2 / 21

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

4 目次 第 1 章 API 概要 基本利用方法 API 一覧... 5 第 2 章共通仕様 エンドポイント プロトコル 文字コード HTTP ヘッダ HTTP ステータスコード エラー形式 共通ヘッダ関連のエラー... 8 第 3 章 API 詳細 物体認識 リクエスト レスポンス 実行例 画像分類 リクエスト レスポンス 実行例 シーン分類 リクエスト レスポンス 実行例 付録 A パラメータ仕様 / 21

5 第 1 章 API 概要 画像認識では 画像に映っている物体やシーンの認識を行います 目的に応じて 3 つの API 物体認識 画像分類 シーン分類 を提供します 1.1 基本利用方法本 API の基本的な利用方法は以下の通りです 物体認識により 画像に映っている複数物体を認識します 画像分類により 画像に映っている物体を詳細に分類します シーン分類により 画像に映っている情景からシーンを分類します 1.2 API 一覧 提供する API 一覧は 以下の通りです 概要 URI メソッド 参照 物体認識 /ImageRecognition/v1/GenericObjectDetector POST 3.1 画像分類 /ImageRecognition/v1/GenericImageClassifier POST 3.2 シーン分類 /ImageRecognition/v1/SceneClassifier POST / 21

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 / 21

7 2.5 HTTP ステータスコード ステータスコード 意味 説明 200 OK リクエストは正常に処理されました 400 Invalid filename 指定した画像ファイル名が不正です Invalid image format サポートされていない画像ファイルが指定されました No image data 画像ファイルを1 件指定してください Incorrect parameter name パラメータを image にしてください 401 Unauthorized 認証に失敗しました 403 Forbidden アクセスを許可されている接続元から接続してください 404 Not Found URL に誤りがあります 405 Method Not Allowed メソッドに誤りがあります (POST 以外が指定されました ) 408 Request Timeout リクエストタイムアウトが発生しました 再度 API の実行をお願いします 413 File size exceeded 画像ファイルのサイズが超過しました 415 Unsupported format Content-Type に誤りがあります 500 Internal Server Error 内部サーバエラーが発生しました しばらくたってからご利用ください 改善されない場合は管理者にご連絡してください 503 Access Limited 同時アクセス数の制限を超えています しばらくたってからご利用ください 2.6 エラー形式 JSON で以下の情報を返します 名前 説明 error エラー情報のオブジェクト code エラーコード title エラータイトル ( 英語 ) message エラーメッセージ ( 英語 ) 7 / 21

8 レスポンス例 "error": "code": 400, "title": "Invalid image format", "message": "Could not open image file." } } 共通ヘッダ関連のエラー コードタイトルメッセージ 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 には任意の文字列が入ります 8 / 21

9 第 3 章 API 詳細 本章では 各 API の詳細仕様を説明します パラメータの表記については 付録 A パラメータ仕様 をご 参照ください 3.1 物体認識 入力として画像を受け取り 画像中に含まれる物体の矩形領域とクラス 分類の出力を行います URI HTTP メソッド /ImageRecognition/v1/GenericObjectDetector POST リクエスト ヘッダ 名前 値 補足 X-Service-Code FJAI Content-Type multipart/form-data - パラメータ名前 説明 種別 必須 既定値 maxresults 推論結果として出力可能な件数の最大値 推論する画像によっては 推論結果として出力可能な件数が最大出力件数より少ないことがある 設定可能な範囲は 1~10 省略または範囲外の値が設定された時の値は 5 query / 21

10 メッセージボディ 形式 : フォーム名前 説明 必須 既定値 filename 画像ファイル名 1 文字以上 ~300 文字以内 半角英数およびドット(.) アップロード可能な画像ファイル数は1つ - 形式 : ファイル名前 説明 種別 必須 既定値 image 画像データ 画像ファイル 最大ファイルサイズ:2MB ファイル形式:PNG/JPEG チャネル数:3(RGB) 幅:1~4096( ピクセル ) 高さ:1~2160( ピクセル ) - 10 / 21

11 3.1.2 レスポンス ヘッダ名前値補足 Content-Type application/json メッセージボディ 形式 :JSON 名前 説明 型 classes 座標 名称 確度を配列化したもの object(class) [] image 画像ファイル名称 string Class 名前 説明 型 box 画像から識別された名称の座標 number[] 画像の左上を始点とし右下を終点とする 先頭から順に以下の意味を持つ 1. 開始点の x 座標 2. 開始点の y 座標 3. 終了点の x 座標 4. 終了点の y 座標 label 画像から識別された名称 string score 画像から識別された名称の確率分布を表す number エラー情報コード タイトル メッセージ 400 Invalid filename The filename you requested is incorrect. Invalid image format Could not open image file. No image data Incorrect parameter The file you requested could not be found. The parameter is incorrect. 403 Forbidden You don t have permission to access on this server. 404 Not Found We could not find the resource you requested. 405 Method Not Allowed The method is not allowed for the requested URL. 413 File size exceeded The file exceeds the maximum size limit. 415 Unsupported format The content-type is unsupported. 500 Internal Server Error The server encountered an internal error. 503 Access Limited The user limit has been exceeded. 11 / 21

12 3.1.3 実行例 リクエスト curl " magerecognition/v1/genericobjectdetector?maxresults=3" -H "X-Acce ss-token: FJAI000000aaaa1" -H "X-Service-Cod e: FJAI " -F レスポンス "classes":[ "box":[ 118, 15, 168, 65 ], "label":"apple", "score": }, "box":[ 98, 55, 198, 155 ], "label":"grape", "score": }, "box":[ 88, 10, 138, 60 ], "label":"apple", "score": } ], "image":"sample1.jpg" } 12 / 21

13 3.2 画像分類 入力として画像を受け取り 画像に映っているものが何であるかの判別を行います URI HTTP メソッド /ImageRecognition/v1/GenericImageClassifier POST リクエスト ヘッダ 名前 値 補足 X-Service-Code FJAI Content-Type multipart/form-data - パラメータ名前 説明 種別 必須 既定値 maxresults 推論結果として出力可能な件数の最大値 推論する画像によっては 推論結果として出力可能な件数が最大出力件数より少ないことがある 設定可能な範囲は 1~10 省略または範囲外の値が設定された時の値は 5 query / 21

14 メッセージボディ 形式 : フォーム名前 説明 必須 既定値 filename 画像ファイル名 1 文字以上 ~300 文字以内 半角英数およびドット(.) アップロード可能な画像ファイル数は1つ - 形式 : ファイル名前 説明 種別 必須 既定値 image 画像データ 画像ファイル 最大ファイルサイズ:2MB ファイル形式:PNG/JPEG チャネル数:3(RGB) 幅:1~4096( ピクセル ) 高さ:1~2160( ピクセル ) - 14 / 21

15 3.2.2 レスポンス ヘッダ名前値補足 Content-Type application/json メッセージボディ 形式 :JSON 名前 説明 型 classes 名称 確度を配列化したもの object(class) [] image 画像ファイル名称 string Class 名前 説明 型 label 画像から識別された名称 string score 画像から識別された名称の確率分布を表し総和を 1 とする number エラー情報コード タイトル メッセージ 400 Invalid filename The filename you requested is incorrect. Invalid image format Could not open image file. No image data Incorrect parameter The file you requested could not be found. The parameter is incorrect. 403 Forbidden You don t have permission to access on this server. 404 Not Found We could not find the resource you requested. 405 Method Not Allowed The method is not allowed for the requested URL. 413 File size exceeded The file exceeds the maximum size limit. 415 Unsupported format The content-type is unsupported. 500 Internal Server Error The server encountered an internal error. 503 Access Limited The user limit has been exceeded. 15 / 21

16 3.2.3 実行例 リクエスト curl " magerecognition/v1/genericimageclassifier?maxresults=5" -H "X-Acc ess-token: FJAI000000aaaa1" -H "X-Service-Co de: FJAI " -F " レスポンス "classes":[ "label":"truck", "score": }, "label":"bus", "score": }, "label":"clock", "score": }, "label":"ship or boat", "score": }, "label":"train", "score": } ], "image":"sample2.jpg" } 16 / 21

17 3.3 シーン分類 入力として画像を受け取り 画像全体がどのようなシーンであるかの推論を行います URI HTTP メソッド /ImageRecognition/v1/SceneClassifier POST リクエスト ヘッダ 名前 値 補足 X-Service-Code FJAI Content-Type multipart/form-data - パラメータ名前 説明 種別 必須 既定値 maxresults 推論結果として出力可能な件数の最大値 推論する画像によっては 推論結果として出力可能な件数が最大出力件数より少ないことがある 設定可能な範囲は 1~10 省略または範囲外の値が設定された時の値は 5 query / 21

18 メッセージボディ 形式 : フォーム名前 説明 必須 既定値 filename 画像ファイル名 1 文字以上 ~300 文字以内 半角英数およびドット(.) アップロード可能な画像ファイル数は1つ - 形式 : ファイル名前 説明 種別 必須 既定値 image 画像データ 画像ファイル 最大ファイルサイズ:2MB ファイル形式:PNG/JPEG チャネル数:3(RGB) 幅:1~4096( ピクセル ) 高さ:1~2160( ピクセル ) - 18 / 21

19 3.3.2 レスポンス ヘッダ名前値補足 Content-Type application/json メッセージボディ 形式 :JSON 名前 説明 型 classes 名称 確度を配列化したもの object(class) [] image 画像ファイル名称 string Class 名前 説明 型 label 画像から識別された名称 string score 画像から識別された名称の確率分布を表し総和を 1 とする number エラー情報コード タイトル メッセージ 400 Invalid filename The filename you requested is incorrect. Invalid image format Could not open image file. No image data Incorrect parameter The file you requested could not be found. The parameter is incorrect. 403 Forbidden You don t have permission to access on this server. 404 Not Found We could not find the resource you requested. 405 Method Not Allowed The method is not allowed for the requested URL. 413 File size exceeded The file exceeds the maximum size limit. 415 Unsupported format The content-type is unsupported. 500 Internal Server Error The server encountered an internal error. 503 Access Limited The user limit has been exceeded. 19 / 21

20 3.3.3 実行例 リクエスト curl " magerecognition/v1/sceneclassifier?maxresults=5" -H "X-Access-Tok en: FJAI000000aaaa1" -H "X-Service-Code: FJAI " -F レスポンス "classes":[ "label":"airfield", "score": }, "label":"airport terminal", "score": }, "label":"bus station indoor", "score": }, "label":"ticket booth", "score": }, "label":"subway station platform", "score": } ], "image":"sample3.jpg" } 20 / 21

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