メインコンテンツまでスキップ

Avatar

概要​

アバター画像や swf の URL を取得する API です。

Avatar オブジェクトフィールド​

Avatar API にリクエストを行うと、Avatar オブジェクトが返却されます。

値説明型補足
size大きさxs:string"large"
view表示xs:string"entire"
emotion表情xs:string"defined"
dimension2D/3D の選択xs:string"defined"
transparent透過xs:Booleantrue
typeフォーマット形式xs:string"image"
extensionフォーマット拡張子xs:string"gif"
motionモーションの AvatarItem#idxs:stringtype が flash, extension が swf の場合にのみ利用可能
sceneアバター flash のシーン設定記述xs:stringtype が flash, extension が swf の場合にのみ利用可能
fpsframes per secondxs:stringtype が flash, extension が swf の場合にのみ利用可能
appIdアプリケーション IDxs:stringtype が flash, extension が swf の場合に必須。現在の appId 値または @app のみ指定可能
movieClipMovieClip の名称xs:stringtype が flash, extension が swf の時に Response 時に含まれるパラメータです。
urlアバター画像の URLxs: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 パラメータは下記のいずれかの値を指定します。

値説明備考
@meviewer の guid必須
{-list;guid}
  • guid をセミコロン区切りで複数指定する事が出来ます。
selector​

selector パラメータは下記のいずれかの値を指定します。

値説明備考
@selfguid パラメータで指定したユーザー自身のアバター画像に対するエントリリソース必須
parameters​

parameters パラメータはアバター画像の形式を決める為の値を入れます。以下の key に対して value を "=" (イコール) 区切りで設定し、それらのペアを ";" (セミコロン) 区切りで繋げた物になります。key ごとに設定出来る value 値及び、それらのデフォルト値の対応が下記の表になります。

keyvaluedefault説明
sizelargefalse画像大
sizemediumtrue画像中
sizesmallfalse画像小
viewentiretrue全体
viewupperfalse上半身
emotiondefinedtrueユーザーが現在設定しているもの
emotionnormalfalse表情 - 通常
emotionsmilefalse表情 - 笑う
emotioncryfalse表情 - 泣く
emotionangryfalse表情 - 怒る
emotionshyfalse表情 - 照れ
dimensiondefinedtrueユーザーが現在設定しているもの
dimension2dfalse2D アバター
dimension3dfalse3D アバター
transparenttruefalse透過 ON
transparentfalsetrue透過 OFF
typeimagetrue画像形式として取得
typeflashfalseflash形式として取得
extensiongiftruegif 画像として取得
extensionpngfalsepng 画像として取得
extensionswffalseswf として取得
motion{itemId}undedinedswf 時に指定したモーションを適用した状態にします
scene{scene}undefinedswf 時に指定したシーン設定で swf を生成します
appId{appId}undefinedswf 時に現在の appId 値または @app と指定します (必須)

また size, view の組み合わせで取得出来る画像サイズの対応表が下記になります。

sizeviewwidthheight
largeentire120160
largeupper6080
mediumentire6080
mediumupper3040
smallentire3040

size が small の場合に view に upper を指定することは出来ません。

scene 記述子​

scene 記述子は swf データを取得する際にモーションに含まれる36フレームから8フレームを選び出しシーンに振り分ける為の記述になります。scene 記述子は次のような構成になっています。

(scene 記述子) = {-join|-|scene}

各シーン設定を "-" (ハイフン) で区切ります。各シーン設定自体は次のような構成になっています。

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

各パラメータの意味は下記のようになります。

名称意味
label各シーンにつける名称です。英数字とアンダースコアからなる文字列を指定可能です
frameId36フレームに対するそれぞれのフレームを表す番号です。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 メソッドレスポンスコードレスポンスメッセージ説明
GET200OK正常にデータ取得が完了しました
GET400Bad Requestリクエストデータが不正です
GET401UnauthorizedOAuth による認可が失敗しています
GET403Forbidden認証エラー以外の理由でアクセス出来ない場合です
GET404Not Found存在しないユーザーまたは操作が許可されていないユーザーです
GET405Method Not Allowedメソッドが許可されていません
GET500Internal Server ErrorAPI 側の問題による失敗です

注意事項​

画像形式での取得時に関する注意事項​

  • 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 が返されます。
  • selector パラメータを@self 以外で指定された場合 レスポンスコードは 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"
}

更新履歴​

  • 2018/12/04
    • サンプルを修正しました。
  • 2015/12/25
    • サンプルにあるリクエスト形式、レスポンス形式を修正しました。
  • 2015/12/02
    • Client Credentials Grant に対応したので、その旨追記しました。
  • 2014/11/27
    • サンプルにあるレスポンス形式を修正しました。