REST API :: faces.train

Calls the training procedure for the specified UIDs, and reports back changes.

The training procedure uses information from previous tags.save calls to build a training set for the specified UIDs. For Facebook UIDs, you can skip the tags.save stage and call faces.train directly - we will use the passed credentials to create a training set from the users' tagged photos on Facebook. For more information on Training and Using the face.com index, check out Recognition How-To.

usage notes:

This is a potentially long operation. When used with more than one UID, a callback_url must be provided (if not, a SYNCHRONOUS_REQUEST_TOO_BIG will be returned).
The callback_url will be called one time for each UID provided (or for all uids in users list, such as friends or all), and return the status of that UID when his train finished.
In case the UID status is required before the callback is called, the method faces.status can provide that data.
The training procedure will attempt to access all URLs used during previous tags.save calls for the passed UIDs. Make sure all URLs used in prior tags.save calls remain public until the training process is completed. Once training is completed, the URLs are no longer required for to perform recognition tasks.
When training facebook uids, face.com also tries to get tagged photos of the uid from facebook as an input for the training. Make sure your facebook application has access to that information, for the user and/or his friends by asking the data read permissions: user_photos, friends_photos, user_photo_video_tags,friends_photo_video_tags,user_birthday,friends_birthday. For more information about facebook read permissions visit this link.

Try it now on the API Sandbox

url:

http://api.face.com/faces/train.format

parameters:

Name	Description
api_key	your face.com API Key
api_secret	your face.com API Secret
	uids	a comma separated list of user IDs to search for in the photos passed in the request
Optional	namespace	a default user namespace to be used for all users specified in the short-hand syntax (just the user ID, without the '@namespace')
	format	‘json’ (default) or ‘xml’
	callback	javascript method to wrap a json-formatted response (for JSONP support, ignored if format=xml)
	callback_url	asynchronously invoke the method, and POST the response to the specified url. Suitable for calling lengthy operations. Reponse is POSTed to the callback_url as JSON/XML in a field called 'data'. If response is not required "no-reply" constant may be used.
	user_auth	signed-in facebook or twitter user credentials. Required only when specifying UIDsin these namespaces. Use name:value pairs, separated by comma: fb_user:[facebook user id] [Deprecated] ~~fb_session:[facebook session id]~~ fb_oauth_token [facebook oauth 2.0 access token] and/or: twitter_username:[twitter screen name] twitter_password:[twitter password] or: twitter_oauth_user:[twitter OAuth user] twitter_oauth_secret:[twitter OAuth secret] twitter_oauth_token:[twitter OAuth token]

example:

http://api.face.com/faces/train.json?api_key=4b4b4c6d54c37&api_secret=&uids=friends@facebook.com&callback_url=http://somecallback.face.com/

Response

User_Status is returned for each trained user. Each includes:

Name	Description
uid	The user id that was trained
training_set_size	The number of photos used to train this model
last_trained	Unixtimestamp of the last time this uid was trained
training_in_progress	Boolean that indicates if another train is running to that uid at the moment

Each User_Status is an element in one of the following lists:

Name	Description
no_training_set	Uids with no training set, and there is not enough data to build one
created	Uids that had no train set, and it was created now
updated	Uids that already had a train set, and it was updated (improved) now
unchanged	Uids that already had a train set, and no change was made to it
in_progress	Uids that are currently in progress of another train call

response sample (json, truncated):

View complete list of response fields

{
    no_training_set: [
        {
            uid: "899195206@facebook.com",
            training_set_size: 0,
            last_trained: 0,
            training_in_progress: false
        },
        {
            uid: "711413@facebook.com",
            training_set_size: 0,
            last_trained: 0,
            training_in_progress: false
        },
        {
            uid: "565267163@facebook.com",
            training_set_size: 0,
            last_trained: 0,
            training_in_progress: false
        }
    ],
    unchanged: [
        {
            uid: "905570720@facebook.com",
            training_set_size: 18,
            last_trained: 1267098123,
            training_in_progress: false
        },
        {
            uid: "1066302268@facebook.com",
            training_set_size: 17,
            last_trained: 1267639090,
            training_in_progress: false
        },
        {
            uid: "1066813337@facebook.com",
            training_set_size: 2,
            last_trained: 1267639089,
            training_in_progress: false
        },
        {
            uid: "575363003@facebook.com",
            training_set_size: 4,
            last_trained: 1267865211,
            training_in_progress: false
        }
    ],
    updated: [
        {
            uid: "661810743@facebook.com",
            training_set_size: 25,
            last_trained: 1267865200,
            training_in_progress: false
        },
        {
            uid: "679769112@facebook.com",
            training_set_size: 23,
            last_trained: 1267865200,
            training_in_progress: false
        },
        {
            uid: "571876003@facebook.com",
            training_set_size: 31,
            last_trained: 1267865211,
            training_in_progress: false
        }
    ],
    status: "success",
    usage: {
        remaining: 200,
        limit: 200,
        reset_time_text: "Thu, 01 Jan 1970 00:00:00 +0000",
        reset_time: null
    }
}