REST API :: tags.save

Saves a face tag. Use this method to save tags for training the face.com index, or for future use of the faces.detect and tags.get methods.

This method accepts 2 primary parameters: User ID (uid) and a list of one or more Tag IDs (tids). The uid field represents a single user ID to associate with the saved tags with, while the tids is a list of tag ids previously acquired through calls to faces.detect or faces.recognize. When photos are processed through the detect and recognize methods, their response includes temporary tag IDs for use in subsequent tags.save calls. The temporary tag IDs are replaced with permanent tag IDs after calling the tags.save method, and are returned in the method's response for future reference.

Try it now on the API Sandbox

In order to start recognizing the user ID for which you are saving the tags for (via future faces.recognize calls), follow up with a call to faces.train which uses the saved tag information for the user ID to add or update an entry in the face index. For more information on recognition, check out Recognition How-To.

When using private namespaces, this method implicitly adds new users to your index when this is the first time you save a user's tag(s).

Keeping things fun and friendly, there are a few limitations to keep in mind:

Saving an already saved tag, with different uid, will update the tag, and remove this tag from the original uid's training-set.
When passing facebook or twitter user IDs, you can tag friends of the currently signed-in user only. This means you'll need to pass the current users' credentials, and for facebook connect/apps this also means you'll need to set your facebook's API key and secret. We'll use these credentials to authenticate the request, by making sure friend relationships are in place, and that the user IDs are accessible to the signed-in user.
When passing private namespace user IDs, there's no need to provide additional credentials. However, please make sure user's privacy is maintained (see our terms).
For more information check our Auth section and User IDs.

url:

http://api.face.com/tags/save.format

parameters:

Required	Name	Description
Required	api_key	your face.com API Key
	api_secret	your face.com API Secret
	tids	one or more tag ids to associate with the passed uid. The tag id is a reference field in the response of faces.detect and faces.recognize methods
	uid	the user ID of the user being tagged
Optional	tagger_id	the ID of the user who's adding the tag
	label	the display name of the user (usually First and Last name)
	format	‘json’ (default) or ‘xml’
	callback	javascript method to wrap a json-formatted response (for JSONP support, ignored if format=xml)
	password	for use when saving tags is a privileged action in your client-side application (must be enabled in application settings)
	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/tags/save.json?api_key=4b4b4c6d54c37&api_secret= &uid=testing@test.face.com&tids=TMP@d64c477a1e9991e9aec2710c08102982_4b5840ff65801_14.81_44.20_0

response sample (json):

View complete list of response fields

{
    saved_tags: [
            {
                detected_tid: "TEMP_F@c650d8026c85d4f78d33adfe05c9fa98_4b5840ff65801_11.41_64.20_0"
                tid: "17268_4b5840ff65801"
            }
      ]
    message: "Tag saved with uid: testing@test.face.com, label: "
    status: "success"
}