リファレンス
概要
顔認識APIは、入力された画像から人間の顔を見つけ、 見つかったそれぞれの顔について詳しく分析して、特徴となるパーツの座標を返すものです。 入力画像は、リクエストと一緒にポストするか、 インターネット上にある画像のURLをパラメータに付ける事によって指定します。
利用する際は必ず利用規約を確認し、 規約内容について同意の上でご利用ください。
顔認識処理
クリックで拡大します
画像が入力されると、 まず最初に画像の中から人間の顔らしき領域(顔の候補)を検出して、 大まかな位置とサイズを決めます。
次に、顔の候補から左右の目と思われる領域を特定して、 大まかな位置とサイズを決めます。
両方の目が検出された場合にはさらに詳細な分析を行って、 顔を構成する特徴的な部分、特徴点の位置を特定します。 このWebAPIでは、50個の特徴点を扱っています。
50個の特徴点には、それぞれを区別するために便宜上の名前が付けてあります。 どの部位にどの点が対応するかについては、右の図をご覧下さい。
検出モード
入力画像から顔候補を検出する動作は、 内部的なパラメータを調整することで大きく変化し、 主に敏感さと実行速度の間にトレードオフがあります。 人物が一人だけの証明写真のような構図が多いと仮定できるならば、 検出もれは多くなりますが、処理時間を短くすることができます。 逆に、長い時間をかければ複数の顔をできるだけ見落とさないようになりますが、 同時に過剰に検出してしまう事も増えてしまいます。
このWebAPIでは、 あらかじめ調整したいくつかの検出モードを選択する事ができます。
| m=0 | 複数の顔をできるだけ見落とさないようにがんばりますが、
処理には一番長い時間がかかります。 これは検出モードを指定しない場合の動作です。 |
|---|---|
| m=1 | 複数の顔を見落とさないようにがんばりますが、多少手を抜きます。 少し処理時間が短いです。 |
| m=2 | 人物が一人だけの証明写真のような構図向け。 処理時間は短くなりますが、条件に合わない顔はほとんど検出されません。 |
| m=3 | 「m=2」に加えて、入力画像を予め一定のサイズまで縮小してしまいます。 処理時間はかなり短くなりますが、 特に小さ目の顔はまったく検出されません。 |
ムリヤリ度
通常、両方の目が検出できない場合は、 特徴点の位置を決める詳細な分析を諦めてしまいます。
そのような場合でも、ムリヤリ度を指定する事によって、 「だいたいこの辺だろう」といういい加減な推測に基づいて 目が検出された事にして、続く詳細な分析をムリヤリ行わせる事ができます。
これによって、かなり信用できないものの、 ともかく50個の特徴点を得ることができます。
ムリヤリ度は、リクエストのパラメータ「f」の値として、 0～2の整数を指定します。
| f=0 | 両目が検出できた場合にだけ、詳細な分析を行います。 これはムリヤリ度を指定しない場合の動作です。 |
|---|---|
| f=1 | 片目しか検出できなかった場合に、 もう一方の目の位置をムリヤリ決めて詳細な分析に進みます。 |
| f=2 | 顔の候補から目が検出できなくても、 目の位置をムリヤリ決めて詳細な分析に進みます。 |
信頼度
50個の特徴点それぞれについて、 詳細な分析処理において求まる、信頼度と呼ばれる値が返されます。
これは0.0～1.0の範囲の実数で、1.0に近いほど、 その特徴点を正しく位置付けた可能性が高いと解釈する事ができます。
また、特徴点すべてについて、信頼度の平均値、最小値、最大値も返されます。
リクエスト
ローカルの画像をポストする場合
- m=Nの形式で0～3の検出モードを選択できます。
- f=Nの形式で0～2のムリヤリ度を付加できます。
- リクエストのボディとして、対象画像をバイナリのまま送信して下さい。
- 処理可能な画像形式はJPEGとPNGです。
- 画像ファイルの形式によって適切なContent-Typeヘッダを 設定して下さい。
- Content-Typeが"image/jpeg"、"image/png"以外の場合は失敗します。
- 画像のサイズが2MBを超える場合は処理できません。
- 処理可能でない事が分っているファイルは、出来るだけポストしないようにして下さい。
インターネット上の画像を指定する場合
- m=Nの形式で0～3の検出モードを選択できます。
- f=Nの形式で0～2のムリヤリ度を付加できます。
- URLには、実際にGETリクエストで取得できる画像のURLを指定して下さい。
- 処理可能な画像形式はJPEGとPNGです。
- 画像を取得するリクエストの結果に適切なContent-Typeヘッダが付いてこない場合は失敗します。
- 画像のサイズが2MBを超える場合は処理できません。
- 処理可能でない事が分っているURLは、出来るだけ指定しないようにして下さい。
あなたが送信した画像や他サイトから取得した画像は、 サーバ上に一時的に保存され、顔認識処理が終了すると同時に自動的に削除されます。
レスポンス
顔認識の処理に成功すると、ステータスコード200と共に、次の様なXML形式の結果が返されます。
<faces> <face id="0"> <bounds x="45" y="153" width="386" height="386"/> <right-eye x="164" y="302"/> <left-eye x="317" y="304"/> <features s-avg="0.88" s-min="0.71" s-max="0.96"> <point id="PR" x="171" y="317" s="0.89"/> <point id="PL" x="312" y="311" s="0.87"/> ..省略.. <point id="F7" x="350" y="489" s="0.88"/> </features> </face> <face id="1"> ..省略.. </face> </faces>
- 検出された顔の候補それぞれについてfaceタグが存在しています。
- faceタグのid属性には、検出した順に番号が振られます。
- boundsタグに顔の大まかな位置と大きさが示されます。
- 右目らしきパーツが検出された場合には、right-eyeタグに大まかな位置が示されます。
検出されなければタグ自体が存在しません。 - 左目らしきパーツが検出された場合、left-eyeタグにその大まかな位置が示されます。
検出されなければタグ自体が存在しません。 - 両目ともに検出された場合にはさらに詳しい分析が行われ、 成功すればその結果がfeaturesタグに返されます。
- featuresタグの下には、特徴点毎にpointタグが並びます。
それぞれid属性に名前が、x属性とy属性に位置が、 s属性に信頼度が示されます。 - featuresタグには、すべての特徴点の信頼度について、 平均値(s-avg)、最小値(s-min)、最大値(s-max)の属性が付加されます。
エラー
リクエストに失敗した場合には以下の様なステータスコードが返されます。
| 400 | POSTリクエストでURLが指定されない場合。 |
|---|---|
| 405 | GET,POST以外のメソッドでのリクエスト。 |
| 415 | 処理できない形式のファイルが入力された場合。 |
| 500 | 入力画像のサイズが2MBを超える場合。その他の内部的なエラー。 |
| 503 | アクセスが集中してサーバが込み合っている等、 なんらかの都合で処理を実行できない場合。 |
ご利用にあたってのお願い
本APIが行っている顔認識は比較的負荷の高い処理であるため、 混雑時などには多数が同時に走ってサーバの処理能力を超えてしまわないように、 アクセスを制限する事があります。
無料で気軽なWebサービスを維持するため、 特に機械的に多数のリクエストを発行する場合には、 以下の点にご協力下さい。
- 同時に複数のリクエストを発行しないこと。
- リクエストの間隔をある程度空けること。
- エラーになることが分っているファイルを無闇に入力しないこと。
うまく認識させるためのヒント
姿勢や表情、照明の加減など、 様々な条件で見え方が大きく変わってしまうので、 入力画像から安定して顔を認識するのは、とても難しいです。 このシステムでも、残念ながらうまく認識できなかったり、 実際には顔でないものが顔と認識されてしまう事が多々あります。
最後に、うまく認識させるためのヒントになりそうな事柄をいくつか挙げておきます。
- 正面を向いている方がうまく認識されます。
- 前髪や眼鏡などで顔が隠れていない方がうまく認識されます。
- 小さな顔は認識しにくいようです。
- あまり大きな画像では、顔以外の領域を顔と誤認識してしまう事が多くなります。
- 明るすぎたり、暗すぎたりする画像は苦手なようです。