Skip to main content

Avatar

Overview​

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


Avatar Object Fields​

ValueDescriptionTypeNamespaceRemark
sizeSizexs:stringhttp://ns.dena.jp/mbga/gameapi/v1#avatarEither "large"
viewViewxs:stringhttp://ns.dena.jp/mbga/gameapi/v1#avatarEither "entire"
emotionEmotionxs:stringhttp://ns.dena.jp/mbga/gameapi/v1#avatarEither "defined"
dimensionChoose 2D or 3Dxs:stringhttp://ns.dena.jp/mbga/gameapi/v1#avatarEither "defined"
transparentTransparentxs:Booleanhttp://ns.dena.jp/mbga/gameapi/v1#avatarEither true
typeFormatxs:stringhttp://ns.dena.jp/mbga/gameapi/v1#avatarEither "image"
extensionFormat extensionxs:stringhttp://ns.dena.jp/mbga/gameapi/v1#avatarEither "gif"
motionAvatarItem#id of motionxs:stringhttp://ns.dena.jp/mbga/gameapi/v1#avatarCan be used only when the type is flash and the extension is swf
sceneScene configuration description of the avatar Flashxs:stringhttp://ns.dena.jp/mbga/gameapi/v1#avatarCan be used only when type is flash and extension is swf
fpsframes per secondxs:stringhttp://ns.dena.jp/mbga/gameapi/v1#avatarCan be used only when type is flash and extension is swf
appIdApplication IDxs:stringhttp://ns.dena.jp/mbga/gameapi/v1#avatarRequired when the type is flash and the extension is swf. Only the current appID or @app can be specified
movieClipMovieClip namexs:stringhttp://ns.dena.jp/mbga/gameapi/v1#avatarThis parameter is included in the Response when the type is flash and the extension is swf. string
urlURL of the avatar imagexs:stringhttp://ns.dena.jp/mbga/gameapi/v1#avatar–

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.

ValueDescriptionRemark
@meguid of the viewerRequired
{-list;guid}
  • You can specify more than one guid separated by semicolons.
selector​

Specify the following value for the selector parameter.

ValueDescriptionRemark
@selfEntry resource for the avatar image specified in the guid parameter for this userRequired
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.

keyvaluedefaultDescription
sizelargefalseLarge image
sizemediumtrueMedium image
sizesmallfalseSmall image
viewentiretrueEntire
viewupperfalseUpper half
emotiondefinedtrueEmotion currently set by the user
emotionnormalfalseEmotion - normal
emotionnormalfalseEmotion - smiling
emotionnormalfalseEmotion - crying
emotionnormalfalseEmotion - angry
emotionnormalfalseEmotion - shy
dimensiondefinedtrueDimension currently set by the user
dimension2dfalse2D avatar
dimension3dfalse3D avatar
transparenttruefalseTransparent ON
transparentfalsetrueTransparent OFF
typeimagetrueObtain as image
typeflashfalseObtain as flash
extensiongiftrueObtain as gif image
extensionpngfalseObtain as png image
extensionswffalseObtain as swf
motion{itemId}undefinedApply specified motion when working with swf
scene{scene}undefinedCreate swf using specified scene settings when working with swf
appId{appId}undefinedSpecify current appId or @app when working with swf (required)

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

sizeviewwidthheight
largeentire120160
largeupper6080
mediumentire6080
mediumupper3040
smallentire3040

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.

NameMeaning
labelName assigned to the scene. A string consisting of alphanumeric characters and underscores.
frameIdA number up to 36 identifying the frame. Values from 0 to 35 can be specified
endExpessionScene repetition setting. " loop" or "stop" can be specified.

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.

ValueDescriptionRemark
json"application/json; charset=utf8"Optional, default value

API Response​

Response Codes​

The following is a list of the API response codes.

Request HTTP methodResponse codeResponse messageDescription
GET200OKSuccessfully acquired the data
GET400Bad RequestInvalid request data
GET401UnauthorizedOAuth authorization failed
GET403ForbiddenCannot access data for a reason other than an authentication error
GET404Not FoundThe user does not exist, or is not allowed to perform the operation
GET405Method Not AllowedMethod is not allowed
GET500Internal Server ErrorFailed because of an API problem

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​


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

Revision History​

  • 12/11/2012
    • Initial release