Overview

Avatar is an API that is used to get an avatar image or the URL of a swf file.

Avatar Object Fields

API Request

HTTP Methods

Proxy model

• GET - Gets an avatar image

Endpoint URL

• Sandbox environment

  http://sb.sp.app.mbga.jp/api/restful/v1/avatar/{-list|;|guid}/{selector}{-prefix|/|parameters}

• Production environment

  http://sp.app.mbga.jp/api/restful/v1/avatar/{-list|;|guid}/{selector}{-prefix|/|parameters}

URI Template Parameter

guid

Specify one of the following values for the guid parameter.

• You can specify more than one guid separated by semicolons.

selector

Specify the following value for the selector parameter.

parameters

parameters is used for describing the format of the avatar image. It is formed by constructing key=value pairs from the following table separated by semicolons.

The following table shows the keys and values that can be specified along with the default values when the corresponding keys are omitted.

The following table shows the image sizes that are supported for various combinations of size and view.
 

When size is defined to be 'small', view cannot be specified as 'upper'.

scene descriptor

When working with an swf file, the scene descriptor allows you to select 8 frames in the motion out of a total of 36 that will be used in the scene. The scene descriptor is configured as follows.

(scene descriptor) = {-join|-|scene}

The scene settings are delimited by hyphens "-". An individual scene setting is described as follows.

{scene} = {label}.{-join|.|frameId}.{endExpression}

The meaning of the parameters is shown below.

In the following example,

s1.10.11.stop-s2.13.15.loop

scene label s1 is defined to be frames 10 and 11 which are not repeated. Then, scene label s2 is defined to be frames 13 and 15 which are repeated.

When view is upper, these may be omitted, but they must be specified when view is entire.

Query Parameters

The following query parameter can be specified.

format

The response format can be specified as follows.

API Response

Response Codes

The following is a list of the API response codes.

Notes

Notes on Acquiring Image Data

• When dimension is 2D (for obtaining a 2D avatar), true (transparent ON) cannot be specified for the transparent parameter.
• When dimension is 3D (for obtaining a 3D avatar). the data cannot be obtained as an animation GIF/PNG when view is upper.

Notes on Acquiring swf Data

• When size is 'small', you cannot specify 'upper' for view.
• When swf is specified, you can only specify 3d for dimension.
• If you omit {itemID} for motion when view is 'upper', the current motion specified by the user will be used. If entire is specified, you must also specify {itemID} for motion.
• When view is 'upper', you do not need to specify the scene descriptor. If you do not specify a scene descriptor, "s1.0.stop" will be used instead. If entire is specified, you must specify a scene descriptor.
• movieClip names are numbered automatically. Please see the description of the movieClip field in the Response data.

Common Notes

• When the value of a parameter is set to "defined", the defined value is returned in the response data.
• If dimension is explicitly specified as 3D but the user does not have a 3D avatar, 400 Bad Request is returned.
• If more than one guid is specified, the total number cannot exceed 1000. However, from a performance standpoint, you should only specify the minimum number of guids necessary.
• If an avatar is requested for a non-existent user or for a user who has already left, 404 Not Found is returned.
• If anything other than @self is specified for the selector parameter, 400 Bad Request is returned.
• If the user has not installed the corresponding application, 403 will be returned for the response code.
   

  Examples

  Getting the Default Avatar

  This example shows how to get the default avatar of the viewer.

Request Format

GET /api/restful/v1/avatar/@me/@self

Response Format

200 OK
Content-Type: application/json; charset=utf8

{
   "startIndex" : 1,
   "itemsPerPage" : 1,
   "totalResults" : 1,
   "avatar" : {
      "extension" : "gif",
      "dimension" : "2d",
      "view" : "entire",
      "scene" : null,
      "appId" : null,
      "fps" : 12,
      "emotion" : "shy",
      "url" : "http://sb-sp.app.mbga.jp/img_op/10236/10000000/10.0.0.0.11.gif?consumer_key=f15cb13613e1bb51d103&guid=ON&sign=ceb2ed30ca9e09845ae56dc6fdaebe69a4d0eda9a82340e89aa45dd6cb64d41d",
      "motion" : 0,
      "transparent" : false,
      "type" : "image",
      "size" : "medium"
   }
}

Sample Image

More Complex Example

• size - large
• dimension - defined
• emotion - shy
• view - upper
• transparent - true

Consider the case when the above values are specified.

Request Format

GET /api/restful/v1/avatar/@me/@self/size=large;dimension=defined;emotion=shy;transparent=true;view=upper

Response Format

{
   "startIndex" : 1,
   "itemsPerPage" : 1,
   "totalResults" : 1,
   "avatar" : {
      "extension" : "gif",
      "dimension" : "2d",
      "view" : "upper",
      "scene" : null,
      "appId" : null,
      "fps" : 12,
      "emotion" : "shy",
      "url" : "http://sb-sp.app.mbga.jp/img_op/10236/10000000/1.5.0.0.11.gif?consumer_key=f15cb13613e1bb51d103&guid=ON&sign=0baf11a32a7384cd4c95bf1a564921203f0a888efc4494941c1e19a033c01ff8",
      "motion" : 0,
      "transparent" : false,
      "type" : "image",
      "size" : "large"
   }
}

Sample Image

Getting Multiple Avatars

Request Format

GET /api/restful/v1/avatar/10236;18407/@self/size=large;view=upper;dimension=2d;emotion=angry?format=json

Response Format

200 OK
Content-Type: application/json

{
   "entry" : {
      "sp.sb.mobage-platform.kr: 18407" : {
         "extension" : "gif",
         "dimension" : "2d",
         "view" : "upper",
         "scene" : null,
         "appId" : null,
         "fps" : 12,
         "emotion" : "angry",
         "url" : "http://sb-sp.app.mbga.jp/img_op/18407/10000000/1.3.1.0.5.gif?consumer_key=f15cb13613e1bb51d103&guid=ON&sign=bb478da73c763f1b3e2b9e7354a95e4526e2fe14ef80e1350faa7086db2c408c",
         "motion" : 0,
         "transparent" : false,
         "type" : "image",
         "size" : "large"
      },
      "sp.sb.mobage-platform.kr: 10236" : {
         "extension" : "gif",
         "dimension" : "2d",
         "view" : "upper",
         "scene" : null,
         "appId" : null,
         "fps" : 12,
         "emotion" : "angry",
?         "url" : "http://sb-sp.app.mbga.jp/img_op/10236/10000000/1.3.1.0.11.gif?consumer_key=f15cb13613e1bb51d103&guid=ON&sign=6ca5cea4ceea97f7828f0679f488f78ba6606c4bb8c319fedc1ac55d7c3621a9",
         "motion" : 0,
         "transparent" : false,
         "type" : "image",
         "size" : "large"
      }
   },
   "startIndex" : 1,
   "itemsPerPage" : 50,
   "totalResults" : 2
}

Getting a Motion Avatar

This example shows how to get the motion avatar of the viewer.

Request Format

GET /api/restful/v1/avatar/@me/@self/dimension=3d;extension=swf;scene=s1.0.7.14.21.28.35.loop;motion=3513000001;type=flash;appId=@app

Response Format

200 OK
Content-Type: application/json; charset=utf8

{
   "startIndex" : 1,
   "itemsPerPage" : 1,
   "totalResults" : 1,
   "avatar" : {
      "extension" : "swf",
      "emotion" : "normal",
      "movieClip" : "a1",
      "scene" : "s1.0.7.14.21.28.35.loop",
      "size" : "medium",
      "view" : "entire",
      "dimension" : "3d",
      "appId" : "@app",
      "fps" : 12,
      "url" : "http://sb-sp.app.mbga.jp/swf_op/18407/1/12000150/3513000001/10.9.0.0.1.swf?sc=s1%2C0%2C7%2C14%2C21%2C28%2C35%2Cloop&fps=12&nm=a1&consumer_key=f15cb13613e1bb51d103&sign=8306f490ae4cd7374e9c81970b95e46a793a22e603557f0c3bf554cb450ee099",
      "transparent" : false,
      "motion" : "3513000001",
      "type" : "flash"
   }
}

Sample Image

Reference Links

XML Schema Part 2: Datatypes Second Edition
URI Template draft-gregorio-uritemplate-03

Revision History

• 12/11/2012
  • Initial release