Betaface API を使った顔検出処理について : 犬ターネット

Betaface API ( https://www.betafaceapi.com/wpa/ ) についての日本語情報があまり見つからないから少しまとめておく。

Betaface API とは

フリーの顔認識/検出webサービス。有償版もあるっぽい。

画像をアップロードすると、顔座標や顔情報(性別、年齢など)を検出するだけでなくモーフィングなどの変換処理も行える。

データのやり取りは HTTP + XML で行われる。最近 JSON 版も公開されたけど動かないものが多いので XML を使ったほうが無難。

例

例えば、以下の画像から

顔部分だけを切り出したり、

モーフィングしたり、笑わせたり（?）といったことが可能。

公式ドキュメントなど

ツイッターもフォローしとくと吉。

APIキー、利用制限など

フリー版のAPIキーは以下。

api_key: d45fd466-51e2-4701-8da8-04351c872236
api_secret: 171e8465-f548-401d-b63b-caf0dc28df5f

新規画像アップロードは 500枚/1日、15,000枚/1ヵ月。顔検出リクエストについては制限なし。

参考 : https://twitter.com/betaface/status/431178439110819840

処理の流れ

画像をアップロードする ( UploadNewImage_File, UploadNewImage_Url )
アップロードした画像の顔情報を得る ( GetImageInfo )
顔画像の変換処理をする (Transform_Faces )
変換した顔画像を取得する ( GetTransformResult )

メソッド

とりあえずよく使いそうなものだけ。

UploadNewImage_File

画像ファイルをアップロードして img_uid を取得する。画像ファイルは base64 encode した文字列で指定する。

url : http://betafaceapi.com/service.svc/UploadNewImage_File
method : POST
params
- api_key
- api_secret
- detection_flags : 顔検出方法を定義するフラグ。以下が指定可能。
  - (未指定) : "propoints,classifiers" フラグが設定される。
  - bestface : もっとも顔スコアが高い(?)顔情報をひとつだけ返す。
  - propoints : 「右目中央」「左目の端」みたいな細かい座標情報を検出する。変換処理を行うにはこのフラグが必須。
  - classifiers : 性別、年齢、髭の有り無し、といった拡張情報を検出する。
  - extended : その他拡張情報を検出する。処理時間が増加。
- imagefile_data : 画像ファイルの base64 文字列
- original_filename : ファイル名

requestサンプル

<?xml version="1.0" encoding="utf-8"?>
<ImageRequestBinary>
  <api_key>d45fd466-51e2-4701-8da8-04351c872236</api_key>
  <api_secret>171e8465-f548-401d-b63b-caf0dc28df5f</api_secret>
  <detection_flags></detection_flags>
  <imagefile_data>/9j/4gIcSUNDX1...</imagefile_data>
  <original_filename>test.jpg</original_filename>
</ImageRequestBinary>

Responseサンプル

<BetafaceImageResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <int_response>0</int_response>
  <string_response>ok</string_response>
  <img_uid>22755636-7d67-458b-adbd-fafa7b90ae15</img_uid>
</BetafaceImageResponse>

UploadNewImage_Url

画像ファイルをアップロードして img_uid を取得する。画像ファイルは url で指定する。

url : http://betafaceapi.com/service.svc/UploadNewImage_Url
method : POST
params
- api_key
- api_secret
- detection_flags : UploadNewImage_File の params の項を参照。
- image_url : 画像url

requestサンプル

<?xml version="1.0" encoding="utf-8"?>
<ImageRequestUrl>
  <api_key>d45fd466-51e2-4701-8da8-04351c872236</api_key>
  <api_secret>171e8465-f548-401d-b63b-caf0dc28df5f</api_secret>
  <detection_flags></detection_flags>
  <image_url>http://upload.wikimedia.org/wikipedia/commons/2/2f/Early_White_Stripes.jpg</image_url>
</ImageRequestUrl>

responseサンプル

<BetafaceImageResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <int_response>0</int_response>
  <string_response>ok</string_response>
  <img_uid>89760281-b14a-424f-bb1f-e167f290cb89</img_uid>
</BetafaceImageResponse>

GetImageInfo

img_uid に紐づく画像情報を得る。個々の顔情報は <FaceInfo>～</FaceInfo> に含まれる。

url : http://betafaceapi.com/service.svc/GetImageInfo
method : post
params
- api_key
- api_secret
- img_uid : UploadNewImage_File, UploadNewImage_Url で取得した img_uid を設定する。

requestサンプル

<?xml version="1.0" encoding="utf-8"?>
<ImageInfoRequestUid>
  <api_key>d45fd466-51e2-4701-8da8-04351c872236</api_key>
  <api_secret>171e8465-f548-401d-b63b-caf0dc28df5f</api_secret>
  <img_uid>89760281-b14a-424f-bb1f-e167f290cb89</img_uid>
</ImageInfoRequestUid>

responseサンプル

<BetafaceImageInfoResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <int_response>0</int_response>
  <string_response>ok</string_response>
  <checksum>91513f414a2ee5ce5aee64bb11e606ee2ec344302f4569dde6b514a8e36f8f81</checksum>
  <faces>
      <FaceInfo>
          <angle>-3.6756</angle>
          <height>86.83</height>
          <image_uid>89760281-b14a-424f-bb1f-e167f290cb89</image_uid>
          <points>
              <PointInfo>
                  <name>basic eye left</name>
                  <type>512</type>
                  <x>149.44</x>
                  <y>208.19</y>
              </PointInfo>
              <!-- 略 -->
          </points>
          <score>6.14</score>
          <tags>
              <TagInfo>
                  <confidence>-0.3</confidence>
                  <name>age</name>
                  <value>29</value>
              </TagInfo>
              <!-- 略 -->
          </tags>
          <uid>a5bf1ba6-db01-11e3-a3fc-80ee734cfa77</uid>
          <user_points i:nil="true"/>
          <width>86.83</width>
          <x>166.22</x>
          <y>217.97</y>
      </FaceInfo>
      <FaceInfo>
          <!-- 略 -->
      </FaceInfo>
  </faces>
  <uid>89760281-b14a-424f-bb1f-e167f290cb89</uid>
</BetafaceImageInfoResponse>

GetFaceImage

uidに紐づいた顔情報を返す。<face_image>～</face_image>には顔画像の base64 encode 文字列が設定される。

url : http://betafaceapi.com/service.svc/GetFaceImage
method : post
params
- api_key
- api_secret
- face_uid : GetImageInfoで検出した顔情報のuid

requestサンプル

<?xml version="1.0" encoding="utf-8"?>
<FaceRequestId>
  <api_key>d45fd466-51e2-4701-8da8-04351c872236</api_key>
  <api_secret>171e8465-f548-401d-b63b-caf0dc28df5f</api_secret>
  <face_uid>a5a956df-db01-11e3-a3fc-80ee734cfa77</face_uid>
</FaceRequestId>

responseサンプル

<BetafaceFaceImageResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <int_response>0</int_response>
  <string_response>ok</string_response>
  <face_image>/9j/4AAQSkZJRgABAQAA....</face_image>
  <face_info>
      <angle>0</angle>
      <height>139</height>
      <image_uid>89760281-b14a-424f-bb1f-e167f290cb89</image_uid>
      <points>
          <PointInfo>
              <name>basic eye left</name>
              <type>512</type>
              <x>71.41</x>
              <y>132.22</y>
          </PointInfo>
          <!-- 略 -->
      </points>
      <score>5.49</score>
      <tags>
          <TagInfo>
              <confidence>0.41</confidence>
              <name>age</name>
              <value>44</value>
          </TagInfo>
          <!-- 略 -->
      </tags>
      <uid>a5a956df-db01-11e3-a3fc-80ee734cfa77</uid>
      <user_points i:nil="true"/>
      <width>139</width>
      <x>99.21</x>
      <y>146.12</y>
  </face_info>
  <uid>a5a956df-db01-11e3-a3fc-80ee734cfa77</uid>
</BetafaceFaceImageResponse>

Transform_Faces

GetImageInfo で検出した顔情報の uid を使って画像変換処理を行い transform_uid を得る。

※公式ドキュメント上は deprecated になってるけどちゃんと動く。

url : http://betafaceapi.com/service.svc/Transform_Faces
method : post
params
- api_key
- api_secret
- action : 変換処理を指定する。以下が指定可能。
  - average : 複数の uid の顔画像を平均化してモーフィングする。
  - expression_smile : faces に指定した uid の顔画像を笑わせる。
  - expression_wow : faces に指定した uid の顔画像をびっくりさせる
  - expression_excited : faces に指定した uid の顔画像を興奮させる。
  - expression_love : faces に指定した uid の顔画像をLOVEする。
- faces : 顔情報uidの配列。action が expression_* の場合は uid はひとつだけ指定。複数指定時はどれが変換されるかは不明。
- parameters : action が expression_* のときに使用。rangeは ~~-1.5 ～ 1.5 まで？~~ -3.0 ～ 3.0 まで。

action = average 指定時の request と response サンプル

request

<?xml version="1.0" encoding="utf-8"?>
<TransformRequest>
<api_key>d45fd466-51e2-4701-8da8-04351c872236</api_key>
<api_secret>171e8465-f548-401d-b63b-caf0dc28df5f</api_secret>
<action>average</action>
<faces>
  <guid xmlns="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
      a5bf1ba6-db01-11e3-a3fc-80ee734cfa77
  </guid>
  <guid xmlns="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
      a5a956df-db01-11e3-a3fc-80ee734cfa77
  </guid>
</faces>
<parameters>1.5</parameters>
</TransformRequest>

response

<BetafaceTransformRequestResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<int_response>0</int_response>
<string_response>ok</string_response>
<transform_uid>22e1d4d2-db04-11e3-a3fc-80ee734cfa77</transform_uid>
</BetafaceTransformRequestResponse>

action = expression_smile 指定時の request と response サンプル

request

<?xml version="1.0" encoding="utf-8"?>
<TransformRequest>
<api_key>d45fd466-51e2-4701-8da8-04351c872236</api_key>
<api_secret>171e8465-f548-401d-b63b-caf0dc28df5f</api_secret>
<action>expression_smile</action>
<faces>
  <guid xmlns="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
      a5bf1ba6-db01-11e3-a3fc-80ee734cfa77
</guid>
</faces>
<parameters>1.5</parameters>
</TransformRequest>

response

<BetafaceTransformRequestResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<int_response>0</int_response>
<string_response>ok</string_response>
<transform_uid>08ff342d-db05-11e3-a3fc-80ee734cfa77</transform_uid>
</BetafaceTransformRequestResponse>

GetTransformResult

Transform_Faces で得た transform_uid を渡して変換後の画像を取得する。画像は base64 encode 文字列で返される。

url : http://betafaceapi.com/service.svc/GetTransformResult
method : POST
params
- api_key
- api_secret
- transform_uid : Transform_Faces で得た transform_uid

requestサンプル

<?xml version="1.0" encoding="utf-8"?>
<TransformResultRequest>
  <api_key>d45fd466-51e2-4701-8da8-04351c872236</api_key>
  <api_secret>171e8465-f548-401d-b63b-caf0dc28df5f</api_secret>
  <transform_uid>22e1d4d2-db04-11e3-a3fc-80ee734cfa77</transform_uid>
</TransformResultRequest>

responseサンプル

<BetafaceTransformResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <int_response>0</int_response>
  <string_response>ok</string_response>
  <result_image>/9j/4AAQSkZJRgABA...</result_image>
  <transform_uid>22e1d4d2-db04-11e3-a3fc-80ee734cfa77</transform_uid>
</BetafaceTransformResponse>

その他

処理正常終了時/異常終了時の判定

正常に処理が終了した場合、XML レスポンス内の int_response に「0」が設定される。処理中やエラーの場合は int_response に「0」以外が設定される。エラーメッセージは string_response に何かしら設定される。

処理が即時完了することはまずないから、プログラム側で適当にwaitかけてリクエストを投げてあげる必要がある。

バグっぽいやつ

TransformFaces 処理で expression_* すると、たまに全然違う画像が返ってきたりする。

以下は expresson_excited 指定したら何故か男性の顔が返ってきたケース。誰だよあんた...

パラメータ少しいじってもう一度リクエスト投げると正しい画像が返ってくるかもしれない。