Avatar
概要
获取头像图片和 swf 的 URL 所需的 API。
Avatar 对象字段
向Avatar API 发送请求后,会反馈Avatar 对象。
| 值 | 说明 | 类型 | 补充 |
|---|---|---|---|
| size | 大小 | xs:string | "large" |
| view | 显示 | xs:string | "entire" |
| emotion | 表情 | xs:string | "defined" |
| dimension | 选择2D/3D | xs:string | "defined" |
| transparent | 透明 | xs:Boolean | true |
| type | 格式形式 | xs:string | "image" |
| extension | 格式扩展名 | xs:string | "gif" |
| motion | 动作的 AvatarItem#id | xs:string | 仅限当type 为 flash, extension 为 swf 时可使用 |
| scene | 头像 flash 的场景设置描述 | xs:string | 仅限当type 为 flash, extension 为 swf 时可使用 |
| fps | frames per second | xs:string | 仅限当type 为 flash, extension 为 swf 时可使用 |
| appId | 应用软件 ID | xs:string | type 为 flash, extension 为 swf 时必须。只能指定当前的 appId 值或 @app |
| movieClip | MovieClip 的名称 | xs:string | type 为 flash, extension 为 swf 时, 在Response 时含有的参数。 |
| url | 头像图片的 URL | xs:string | – |
API请求
HTTP 方法
-
Authorization Code Grant
- GET - 获取头像图片
-
Client Credentials Grant
-
GET - 获取头像图片
端点 URL
-
-
Sandbox 环境
https://sb-app.mobage.jp/social/api/restful/v2/avatar/{-list|;|guid}/{selector}{-prefix|/|parameters} -
正式环境
https://app.mobage.jp/social/api/restful/v2/avatar/{-list|;|guid}/{selector}{-prefix|/|parameters}
URI Template 参数
guid
在guid 参数中,指定下述任意一项的值。
| 值 | 说明 | 备注 |
|---|---|---|
| @me | viewer 的 guid | 必须 |
| {-list | ; | guid} |
- 使用分号分隔,可指定多个guid。
selector
在selector 参数中,指定下述任意一项的值。
| 值 | 说明 | 备注 |
|---|---|---|
| @self | 对guid 参数指定的用户本人头像图片的条目资源 | 必须 |
parameters
在parameters 参数中,添加用于确定头像图片格式所需的值。使用 "=" (等于) 分隔,对以下 key 设置 value ,使用 ";" (分号) 分割组成对。对每个key 可设置的 value 值及其默认值的对应关系如下表所示。
| key | value | default | 说明 |
|---|---|---|---|
| size | large | false | 图片大 |
| size | medium | true | 图片中 |
| size | small | false | 图片小 |
| view | entire | true | 全身 |
| view | upper | false | 上半身 |
| emotion | defined | true | 用户当前设置 |
| emotion | normal | false | 表情 - 通常 |
| emotion | smile | false | 表情 - 笑 |
| emotion | cry | false | 表情 - 哭 |
| emotion | angry | false | 表情 - 怒 |
| emotion | shy | false | 表情 - 羞 |
| dimension | defined | true | 用户当前设置 |
| dimension | 2d | false | 2D 头像 |
| dimension | 3d | false | 3D 头像 |
| transparent | true | false | 透明 ON |
| transparent | false | true | 透明 OFF |
| type | image | true | 获取图片格式 |
| type | flash | false | 获取flash格式得 |
| extension | gif | true | 获取gif 图片 |
| extension | png | false | 获取png 图片 |
| extension | swf | false | 获取swf |
| motion | {itemId} | undedined | swf 时,进入指定动作的应用状态 |
| scene | {scene} | undefined | swf 时,使用指定场景设置生成 swf |
| appId | {appId} | undefined | swf 时,指定当前的 appId 值或 @app (必须) |
另外,根据 size, view 的组合,可获取图片大小的对应表如下。
| size | view | width | height |
|---|---|---|---|
| large | entire | 120 | 160 |
| large | upper | 60 | 80 |
| medium | entire | 60 | 80 |
| medium | upper | 30 | 40 |
| small | entire | 30 | 40 |
size 为 small 时,在 view 中不能指定 upper。
scene 描述符
scene 描述符是获取 swf 数据时,从36帧动作中选出8帧分配在场景中所需的描述。scene 描述符的配置如下。
(scene 描述符) = {-join|-|scene}
使用 "-" (连字符) 分隔各场景设置。各场景设置本身的配置如下。
{scene} = {label}.{-join|.|frameId}.{endExpression}
各参数的含义如下所述。
| 名称 | 含义 |
|---|---|
| label | 各场景的命名。可指定由英文数字和下划横线组成的字符串 |
| frameId | 各帧在36帧的编号。可指定0-35 |
| endExpession | 场景的重复设置。可指定"loop" 或 "stop" |
例如,
s1.10.11.stop-s2.13.15.loop
那么场景等级 s1 由帧 10, 11 组成,不重复。接着场景等级 s2 由帧 13, 15 组成,重复13, 15 。
view 为 upper 时,可省略,但entire 时必须指定。
查询参数
可指定下述查询参数。
format
可指定响应格式。
| 值 | 说明 | 备注 |
|---|---|---|
| json | "application/json; charset=utf8" | 任意、默认值 |
API 响应
响应代码
API 的响应代码为以下中的任意一项。
| 请求 HTTP 方法 | 响应代码 | 响应信息 | 说明 |
|---|---|---|---|
| GET | 200 | OK | 数据获取正常完成 |
| GET | 400 | Bad Request | 请求数据不当 |
| GET | 401 | Unauthorized | OAuth 验证失败 |
| GET | 403 | Forbidden | 由于认证错误以外的原因导致不能访问的情况 |
| GET | 404 | Not Found | 用户不存在或不允许用户操作 |
| GET | 405 | Method Not Allowed | 方法不允许 |
| GET | 500 | Internal Server Error | API 端的问题导致失败 |
注意事项
获取图片格式时的注意事项
- dimension 为 2D 时 (获取2D 头像时),在transparent 参数中不能指定 true (透明 ON) 。
- dimension 为 3D 时 (获取3D 头像),当view 为 upper (上半身) 时,不能获取 GIF/PNG 动画。
获取swf 格式时的注意事项
- size 为 small 时,在 view 中不能指定 upper。
- 指定swf 时, dimension 只有 3d。
- view 为 upper (上半身) 时,当省略 motion 的 {itemId} 值时,会设置当前用户指定的 motion 。当指定entire 时,必须指定motion 的 {itemId} 值。
- view 为 upper (上半身) 时,可省略 scene 描述符。省略时的 scene 指定为 "s1.0.stop" 。当指定entire 时,scene 描述符为必须。
- movieClip 的名称采用自动编号。请参见Response 数据中含有的 movieClip 字段值。
通用注意事项
- 对指定有defined 值的参数,响应数据会反馈规定的设置值。
- 对3D 头像数据不存在的用户,当明确指定 dimension 为 3D 时,会反馈 400 Bad Request。
- 指定多个guid 时,最大条数为 1000 条。但是,出于性能方面的考虑,请指定最低必要限度的 guid。
- 如果发送不存在用户或退会用户的头像图片等请求,会反馈 404 Not Found。
- 指定@self 以外的selector 参数时,响应代码会反馈 400 Bad Request。
- 用户未安装此应用软件时,响应代码会反馈 403。
样例
获取默认头像图片
获取viewer 默认头像图片的示例。
请求格式
GET /social/api/restful/v2/avatar/@me/@self
响应格式
200 OK
Content-Type: application/json; charset=utf8
{
"extension":"gif",
"dimension":"3d",
"view":"entire",
"scene":null,
"appId":null,
"fps":12,
"emotion":"defined",
"url":"http://sb-sp.mbga.jp/img_op/10236/10000000/1.5.0.0.2.gif?guid=ON",
"motion":0,
"transparent":false,
"type":"image",
"size":"medium"
}
复杂的指定示例
- size - large
- dimension - defined
- emotion - shy
- view - upper
- transparent - true
按上述进行指定。
请求格式
GET /social/api/restful/v2/avatar/@me/@self?size=large;dimension=defined;emotion=shy;transparent=true;view=upper
响应格式
{
"extension":"gif",
"dimension":"3d",
"view":"upper",
"scene":null,
"appId":null,
"fps":12,
"emotion":"shy",
"url":"http://sb-sp.mbga.jp/img_op/10236/10000000/1.5.0.0.2.gif?guid=ON",
"motion":0,
"transparent":true,
"type":"image",
"size":"large"
}
更新履历
- 2015/12/25
- 对样例中的请求格式和响应格式进行了修改。
- 2015/12/02
- 已支持Client Credentials Grant,故补充。
- 2014/11/27
- 对样例中的响应格式进行了修改。