顔ラボ » 顔検出WebAPI仕様

顔検出WebAPI仕様

概要

このWebAPIは、https通信によるREST形式のWebAPIです。
指定された画像に対して顔検出を行い、検出した顔に関する情報をXMLで返します。
画像の指定方法は、URLによる指定と、POSTメソッドによる直接送信との2種類を用意しています。

リクエストURL

https://kaolabo.com/api/detect

利用できるHTTPメソッド

GETとPOSTの2種類の方法でWebAPIを利用することができます。

● GET

・クエリーパラメータ

名前	説明	値	必須
apikey	アプリケーションを利用するための認証キー	文字列	○
url	顔検出する画像を指すURL ※URLが指す画像はJPEGである必要があります。	URLを表す文字列	○

例)

GET /api/detect?apikey=[認証キー]&url=http://example.com/sample.jpg

● POST

・クエリーパラメータ

名前	説明	値	必須
apikey	アプリケーションを利用するための認証キー	文字列	○

・リクエストヘッダ
　Content-Typeヘッダが「image/jpeg」である必要があります。

・リクエストボディ
　JPEG画像である必要があります。

例)

POST /api/detect?apikey=[認証キー]
Content-Type: image/jpeg

[JPEG画像のバイナリデータ]

レスポンスフィールド

名前	属性	説明	値
results	version	レスポンスXMLのバージョン	1.0
results	xmlns	レスポンスXMLの名前空間URI	http://xmlns.kao labo.com/detect
faces	–	顔検出結果のルート要素	–
face	–	顔検出結果顔が見つからない場合はなし	–
	x	顔領域矩形の左上のx座標	例) 234
	y	顔領域矩形の左上のy座標	例) 117
	width	顔領域矩形の幅	例) 60
	height	顔領域矩形の高さ	例) 60
	score	顔らしさを表すスコア	例) 742
left-eye	–	左目検出結果	–
	x	左目のx座標	例) 275
	y	左目のy座標	例) 136
right-eye	–	右目検出結果	–
	x	右目のx座標	例) 253
	y	右目のy座標	例) 136

例)

<?xml version="1.0" encoding="UTF-8"?>
<results version="1.0" xmlns="http://xmlns.kaolabo.com/detect">
　　　<faces>
　　　　　<face height="60" score="742" width="60" x="234" y="117">
　　　　　　　　<left-eye x="275" y="136" />
　　　　　　　　<right-eye x="253" y="136" />
　　　　　</face>
　　　　　<face height="48" score="705" width="48" x="303" y="138">
　　　　　　　　<left-eye x="336" y="153" />
　　　　　　　　<right-eye x="318" y="153" />
　　　　　</face>
　　　　　<face height="36" score="505" width="36" x="134" y="143">
　　　　　　　　<left-eye x="159" y="153" />
　　　　　　　　<right-eye x="145" y="153" />
　　　　　</face>
　　</faces>
</results>

エラー時のレスポンス

エラー発生時、サーバはエラーに応じて以下のステータスコードを返します。

コード	メッセージ	説明
400	Bad Request	パラメータの指定が正しくない場合
403	Forbidden	リソースへのアクセスが許可されていない場合認証キーが間違っている、利用制限を超えている場合
405	Method Not Allowed	許されていないメソッドをリクエストした場合
408	Request Time-out	クライアントが時間内にリクエストを発行しなかった場合
415	Unsupported Media Type	POSTでアップロードされた画像が処理できないフォーマットだった場合
500	Internal Server Error	予期しないエラーがサーバ側で発生した場合

また、次のフィールドを持つエラーレスポンスを返します。

要素	属性	説明	値
results	–	レスポンスXMLのルート要素	–
	version	レスポンスXMLのバージョン	1.0
	xmlns	レスポンスXMLの名前空間URI	http://xmlns.kaolabo.com/error
error	–	エラー詳細	–
error	message	エラーメッセージ	認証キーが正しくありません。

例)

<?xml version="1.0" encoding="UTF-8"?>
<results xmlns="http://xmlns.kaolabo.com/error" version="1.0">
　　　<error message="認証キーが正しくありません。" />
</results>