画像認識
API リファレンス
第 1.3 版
2018 年 8 月 2 日 富士通株式会社
変更履歴
版数 修正日 修正箇所 修正内容 1.0 2017/4/27 初版 1.1 2017/7/27 - クリップボードへのコピーで不要な 文字が含まれる事象を修正 1.2 2018/4/26 2.2 暗号化プロトコルのサポートについ て記載 1.3 2018/8/2 2.5 2.6.1 ステータスコードの追記 エラーメッセージの修正はじめに
本書の目的 本書は、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 共通ヘッダ関連のエラー ... 8 第 3 章 API 詳細 ... 9 3.1 物体認識 ... 9 3.1.1 リクエスト ... 9 3.1.2 レスポンス ... 11 3.1.3 実行例 ... 12 3.2 画像分類 ... 13 3.2.1 リクエスト ... 13 3.2.2 レスポンス ... 15 3.2.3 実行例 ... 16 3.3 シーン分類 ... 17 3.3.1 リクエスト ... 17 3.3.2 レスポンス ... 19 3.3.3 実行例 ... 20 付録 A パラメータ仕様 ... 21第1章 API 概要
画像認識では、画像に映っている物体やシーンの認識を行います。 目的に応じて３つの 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 3.3第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 桁]” 例: FJAI000001-00001 K5 PaaS Portal で各サービスに割り振ら れたコード（10 桁）と、各サービスの各 API が持つ固有の番号（5 桁）をハイフ ンで繋ぎ合わせた文字列です。実際の値 は、「第 3 章 API 詳細」のリクエストヘッダ 仕様をご参照ください。2.5 HTTP ステータスコード
ステータスコード 意味 説明
200 OK リクエストは正常に処理されました。
400 Invalid filename 指定した画像ファイル名が不正です。
Invalid image format サポートされていない画像ファイルが指定されました。 No image data 画像ファイルを１件指定してください。
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 エラーメッセージ(英語)※レスポンス例 {
"error": {
"code": 400,
"title": "Invalid image format",
"message": "Could not open image file." }
}
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 物体認識
入力として画像を受け取り、画像中に含まれる物体の矩形領域とクラス、分類の出力を行います。 URI /ImageRecognition/v1/GenericObjectDetector HTTP メソッド POST 3.1.1 リクエスト ヘッダ 名前 値 補足 X-Service-Code FJAI000001-00001 - Content-Type ｍultipart/form-data - パラメータ 名前 説明 種別 必須 既定値 maxResults 推論結果として出力 可能な件数の最大 値。 推論する画像によっ ては、推論結果とし て出力可能な件数 が最大出力件数より 少ないことがある。 設定可能な範囲は 1～10。 省略または範囲外の 値が設定された時の 値は 5。 query - 5 メッセージボディ 形式：フォーム 名前 説明 必須 既定値 filename 画像ファイル名 ・１文字以上～300 文字以内 ・半角英数およびドット(.) ・アップロード可能な画像ファイル数は１つ ◯ - 形式：ファイル 名前 説明 種別 必須 既定値 image 画像データ 画像ファイル ・最大ファイルサイズ：2MB ・ファイル形式：PNG/JPEG ・チャネル数：3（RGB） ・幅：1～4096(ピクセル) ・高さ：1～2160(ピクセル) ◯ -
3.1.2 レスポンス ヘッダ 名前 値 補足 Content-Type application/json メッセージボディ 形式：JSON 名前 説明 型
classes 座標、名称、確度を配列化したもの object(Class) []
image 画像ファイル名称 string Class 名前 説明 型 box 画像から識別された名称の座標 ・画像の左上を始点とし右下を終点とする ・先頭から順に以下の意味を持つ １．開始点の x 座標 ２．開始点の y 座標 ３．終了点の x 座標 ４．終了点の y 座標 number[] label 画像から識別された名称 string score 画像から識別された名称の確率分布を表す number エラー情報 コード タイトル メッセージ
400 Invalid filename The filename you requested is incorrect. Invalid image format Could not open image file.
No image data The file you requested could not be found. Incorrect parameter 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.
3.1.3 実行例
リクエスト
curl "https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/I mageRecognition/v1/GenericObjectDetector?maxResults=3" -H "X-Acce ss-Token: 000000000000000000001FJAI000000aaaa1" -H "X-Service-Cod e: FJAI000001-00001" -F "image=@sample1.jpg;filename=sample1.jpg" レスポンス { "classes":[ { "box":[ 118, 15, 168, 65 ], "label":"apple", "score":0.945656 }, { "box":[ 98, 55, 198, 155 ], "label":"grape", "score":0.895656 }, { "box":[ 88, 10, 138, 60 ], "label":"apple", "score":0.745656 } ], "image":"sample1.jpg" }
3.2 画像分類
入力として画像を受け取り、画像に映っているものが何であるかの判別を行います。 URI /ImageRecognition/v1/GenericImageClassifier HTTP メソッド POST 3.2.1 リクエスト ヘッダ 名前 値 補足 X-Service-Code FJAI000001-00002 - Content-Type multipart/form-data - パラメータ 名前 説明 種別 必須 既定値 maxResults 推論結果として出力 可能な件数の最大 値。 推論する画像によっ ては、推論結果とし て出力可能な件数 が最大出力件数より 少ないことがある。 設定可能な範囲は 1～10。 省略または範囲外の 値が設定された時の 値は 5。 query - 5 メッセージボディ 形式：フォーム 名前 説明 必須 既定値 filename 画像ファイル名 ・１文字以上～300 文字以内 ・半角英数およびドット(.) ・アップロード可能な画像ファイル数は１つ ◯ - 形式：ファイル 名前 説明 種別 必須 既定値 image 画像データ 画像ファイル ・最大ファイルサイズ：2MB ・ファイル形式：PNG/JPEG ・チャネル数：3（RGB） ・幅：1～4096(ピクセル) ・高さ：1～2160(ピクセル) ◯ -
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 The file you requested could not be found. Incorrect parameter 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.
3.2.3 実行例
リクエスト
curl "https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/I mageRecognition/v1/GenericImageClassifier?maxResults=5" -H "X-Acc ess-Token: 000000000000000000001FJAI000000aaaa1" -H "X-Service-Co de: FJAI000001-00002" -F "image=@sample2.jpg;filename=sample2.jpg " レスポンス { "classes":[ { "label":"truck", "score":0.827877998352051 }, { "label":"bus", "score":0.096360206604004 }, { "label":"clock", "score":0.005639238357544 }, { "label":"ship or boat", "score":0.0038659954071045 }, { "label":"train", "score":0.0003468704223633 } ], "image":"sample2.jpg" }
3.3 シーン分類
入力として画像を受け取り、画像全体がどのようなシーンであるかの推論を行います。 URI /ImageRecognition/v1/SceneClassifier HTTP メソッド POST 3.3.1 リクエスト ヘッダ 名前 値 補足 X-Service-Code FJAI000001-00003 - Content-Type multipart/form-data - パラメータ 名前 説明 種別 必須 既定値 maxResults 推論結果として出力 可能な件数の最大 値。 推論する画像によっ ては、推論結果とし て出力可能な件数 が最大出力件数より 少ないことがある。 設定可能な範囲は 1～10。 省略または範囲外の 値が設定された時の 値は 5。 query - 5 メッセージボディ 形式：フォーム 名前 説明 必須 既定値 filename 画像ファイル名 ・１文字以上～300 文字以内 ・半角英数およびドット(.) ・アップロード可能な画像ファイル数は１つ ◯ - 形式：ファイル 名前 説明 種別 必須 既定値 image 画像データ 画像ファイル ・最大ファイルサイズ：2MB ・ファイル形式：PNG/JPEG ・チャネル数：3（RGB） ・幅：1～4096(ピクセル) ・高さ：1～2160(ピクセル) ◯ -
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 The file you requested could not be found. Incorrect parameter 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.
3.3.3 実行例
リクエスト
curl "https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/I mageRecognition/v1/SceneClassifier?maxResults=5" -H "X-Access-Tok en: 000000000000000000001FJAI000000aaaa1" -H "X-Service-Code: FJAI 000001-00003" -F "image=@sample3.jpg;filename=sample3.jpg" レスポンス { "classes":[ { "label":"airfield", "score":0.8097028970718384 }, { "label":"airport terminal", "score":0.0159448699951172 }, {
"label":"bus station indoor", "score":0.0111513423919678 }, { "label":"ticket booth", "score":0.0104156574452484 }, {
"label":"subway station platform", "score":0.006951379776001
} ],
"image":"sample3.jpg" }
付録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 ※[]表記 配列
