Overview

Version information

Version : 1.0.0

URI scheme

Host : api.avatarplay3d.com
Schemes : HTTPS

Consumes

  • application/x-www-form-urlencoded

Produces

  • application/json

Paths

POST /v1/AccessToken

Description

付与トークンを渡し、アクセストークンとアバターIDを取得します。アバターIDを自社アプリのユーザと紐づけて、他のAPIで利用してください。接続開始時にゲストユーザのアバターIDを指定している場合、アップグレード処理も実行されます。RESTful APIのみを利用している場合、ここで得られたアクセストークンは破棄して問題ありません。

Parameters

Type Name Description Schema

Query

avatarId
optional

アップグレードの場合、ゲストとして割り振ったアバターID。アップグレードする場合は必ず指定してください。接続開始時に指定した値と一致する必要があります。

integer (int64)

Query

codeVerifier
required

接続開始時にcodeChallengeの生成で利用したcodeVerifier。Example: 4hmLHty5K6P…

string

Query

redirectUri
required

接続開始時に指定したリダイレクトURI。Example: https://example.com/oauth_callback

string

Query

requestDate
required

接続開始時にcodeChallengeの生成で利用したリクエスト日時。Example: 1552356284

integer (int64)

Query

scope
required

接続開始時に指定したスコープ。Example: AvatarLoad,ItemGrant

string

Query

token
required

redirectUri経由で受け取ったtokenパラメータの値をそのまま指定します。Example: veneh5On7MW…

string

Responses

HTTP Code Description Schema

200

成功

default

エラー

GET /v1/Avatar/{avatarId}

Description

ひとつのアバターIDを指定して、アバター画像のURLなどを取得するAPIです。複数のアバター画像を取得するには、Avatars API を利用します。この API のレスポンスは、最大10分間キャッシュできます。

Parameters

Type Name Description Schema

Path

avatarId
required

アバターID

integer (int64)

Responses

HTTP Code Description Schema

200

成功

default

エラー

POST /v1/Avatar/{avatarId}/Items

Description

指定したアバターIDを持つユーザに、指定したアイテムを付与します。前提として、アイテム付与の権限を持つアクセストークンが有効となっている必要があります。デフォルトの動作では、付与アイテムの中に既に所持済みのアイテムが含まれていた場合、未所持のアイテムのみを付与して処理を正常終了します。個々のアイテムが付与されたかどうかは返り値のItemResultで確認できます。この動作は、failIfOwnedItemExists パラメータに真を指定することで変更できます。

Parameters

Type Name Description Schema

Path

avatarId
required

アバターID

integer (int64)

Query

failIfOwnedItemExists
optional

付与アイテムの中に一つでも所持アイテムが含まれている場合、全ての処理を失敗させる場合は真。デフォルトは偽。

boolean

Query

itemId
required

アイテムID。アプリが利用可能なアイテムとして登録されている必要があります。最大10個のアイテムIDを指定できます。

< integer (int64) > array(multi)

Query

shopSessionId
optional

UI Kit のショップ経由の場合、セッションIDを指定します。セッションが削除され、再利用できなくなります。

string

Responses

HTTP Code Description Schema

200

成功

default

エラー

GET /v1/Avatars

Description

アバターIDを指定して、アバター画像のURLなどを取得するAPIです。全身のアバター画像と、サムネイル表示などに使えるバストアップ画像のURLを取得できます。全身のアバター画像には、テイストに応じたアニメーションが付きます。バストアップ画像にはアニメーションは付きません。この API のレスポンスは、最大10分間キャッシュできます。

Parameters

Type Name Description Schema

Query

avatarId
required

アバターID。最低1つ指定する必要があり、最大50個まで指定できます。個別のアバター画像の取得は失敗する可能性があり、取得に失敗したアバターIDが含まれていた場合も、全体のレスポンスとしては正常(200)を返します。個々のアバターIDのステータスは、statusプロパティで確認できます。

< integer (int64) > array(multi)

Responses

HTTP Code Description Schema

200

成功。アバター画像のURLリストを返します。

default

エラー

GET /v1/Echo

Description

与えたメッセージを出力するだけのテスト用のAPIです。認証の動作確認などに利用してください。

Parameters

Type Name Description Schema

Query

message
optional

出力するメッセージ

string

Responses

HTTP Code Description Schema

200

成功

default

失敗

GET /v1/Gacha/Session

Description

UI Kit のガチャのセッション情報を取得するためのAPIです。ガチャ購入確認画面を構成する際に利用します。ここで取得したアイテムがガチャから引き当てられたアイテムとなるため、サーバに一時保存しておき、購入完了時にアイテム付与します。

Parameters

Type Name Description Schema

Query

avatarId
required

自社アプリ側で認証できたユーザのアバターID

integer (int64)

Query

gachaSessionId
required

ガチャセッションID。購入確認画面のURLに追加されたパラメータから取得できます。

string

Responses

HTTP Code Description Schema

200

成功

default

失敗

POST /v1/Guest

Description

ゲストアバターを新規作成します。発行されたアバターIDを自社サービスのユーザと紐づけることで、以降は Avatars APIを使ってユーザのアバター画像URLなどを取得できるようになります。

Parameters

Type Name Description Schema

Query

scope
optional

スコープ。パーミッション名をカンマ区切りで連結した文字列。指定しなかった場合、アバターをロード(表示)する権限(AvatarLoad)のみのスコープを要求します。アイテム付与するためにはアイテム付与権限(ItemGrant)が必要になります。Example: AvatarLoad,ItemGrant

< string > array(multi)

Responses

HTTP Code Description Schema

200

成功。ゲストアバターの情報が返ります。

default

失敗

GET /v1/Items

Description

アプリで利用可能なアイテムの情報(サムネイル画像URLなど)をを取得します。avatarId を指定していない場合に限り、この API のレスポンスは、最大10分間キャッシュできます。

Parameters

Type Name Description Schema

Query

avatarId
optional

アバターID。指定した場合、そのユーザが該当アイテムを所持しているかどうかも判別できます。

integer (int64)

Query

itemId
required

アイテムID。アプリが利用できるアイテムとして登録されている必要があります。

< integer (int64) > array(multi)

Responses

HTTP Code Description Schema

200

成功

default

失敗

GET /v1/Shop/Session

Description

UI Kit のショップのセッション情報を取得するためのAPIです。アイテム購入確認画面を構成する際に利用します。ここで返されるアイテム情報は、購入対象となる、エンドユーザにとって未所持のアイテムに絞られます。

Parameters

Type Name Description Schema

Query

avatarId
required

自社アプリ側で認証できたユーザのアバターID

integer (int64)

Query

shopSessionId
required

ショップセッションID。購入確認画面のURLに追加されたパラメータから取得できます。

string

Query

shopSessionVersion
required

ショップセッションのバージョン。購入確認画面のURLに追加されたパラメータから取得できます。セッションのバージョンが古い場合、APIへのアクセスがエラーとなります。これは、ブラウザのバックボタンでの操作や別の画面・タブを使って選択したアイテムが変更された場合に起こります。

integer (int32)

Responses

HTTP Code Description Schema

200

成功

default

失敗

Definitions

AccessToken

連携したアバターのアバターIDとアクセストークンを収録しています。

Name Description Schema

accessToken
optional

アクセストークン。RESTful APIのみを利用する場合は破棄して問題ありません。
Example : "d030073d5d1…​"

string

avatarId
optional

アバターID。自社アプリ内でアバターを一意に表すIDです。RESTful APIのパラメータとして利用できます。
Example : 1234567890

integer (int64)

avatarImageUrl
optional

アバター全身画像のURL。画像は240x320ピクセルサイズのアニメーションGIFです。テイストに応じたアニメーションが付きます。
Example : "https://example.com/avatar.gif"

string

faceImageUrl
optional

アバターバストアップ画像のURL。画像は120x120ピクセルサイズのGIFファイルです。アバターが正面を向いたアニメーションなしの画像です。サムネイルとしての利用などに適しています。
Example : "https://example.com/face.gif"

string

scope
optional

スコープ
Example : "AvatarLoad,ItemGrant"

string

tokenType
optional

トークンの種類。「Bearer」で固定です。
Example : "Bearer"

string

Avatar

アバター画像URLなどのアバター情報

Name Description Schema

avatarId
optional

アバターID
Example : 1234567890

integer (int64)

avatarImageUrl
optional

アバター全身画像のURL。画像は240x320ピクセルサイズのアニメーションGIFです。テイストに応じたアニメーションが付きます。
Example : "https://example.com/avatar.gif"

string

faceImageUrl
optional

アバターバストアップ画像のURL。画像は120x120ピクセルサイズのGIFファイルです。アバターが正面を向いたアニメーションなしの画像です。サムネイルとしての利用などに適しています。
Example : "https://example.com/face.gif"

string

guest
optional

ゲストユーザなら真
Example : true

boolean

status
optional

アバターのステータスを返します。200: 正常に画像取得。401: 画像取得のパーミッションが取れませんでした。ユーザがパーミッションを削除したなどの可能性があります。パーミッションを再取得することで改善する可能性があります。404: 存在しないアバターです。アバターIDが誤っているか、ユーザが削除された可能性があります。
Example : 200

integer (int32)

Avatars

Avatar のリストです。

Name Schema

avatars
optional

< Avatar > array

EchoMessage

エコー出力

Name Description Schema

message
optional

出力するメッセージ
Example : "hello"

string

Error

Name Description Schema

code
optional

Example : 400

integer (int32)

errors
optional

< ErrorDetail > array

message
optional

Example : "Invalid string value"

string

ErrorDetail

Name Description Schema

domain
optional

Example : "global"

string

message
optional

Example : "String 'abc' not a valid integer"

string

reason
optional

Example : "badRequest"

string

ErrorResponse

Name Schema

error
optional

GachaItem

ガチャアイテム

Name Description Schema

free
optional

初回無料アイテムなら真

boolean

itemId
optional

引き当てられたアイテムのID

integer (int64)

thumbnailUrl
optional

引き当てられたアイテムのサムネイル画像URL

string

GachaSession

ガチャのセッション情報

Name Description Schema

currencyId
optional

通貨ID

integer (int64)

gachaId
optional

ガチャID

integer (int64)

items
optional

< GachaItem > array

price
optional

number (float)

Item

アイテムの情報

Name Description Schema

have
optional

指定したアバターIDのユーザが所持しているアイテムなら真。アバターIDを指定していない場合は偽が設定されます。
Example : false

boolean

itemId
optional

アイテムID
Example : 1234567890

integer (int64)

thumbnailUrl
optional

アイテムのサムネイル画像のURL。画像は60x60ピクセルのPNGファイルです。
Example : "https://example.com/thumbnail.png"

string

ItemResult

アイテム付与の結果

Name Description Schema

itemId
optional

アイテムID
Example : 1234567890

integer (int64)

status
optional

結果コード。200:正常に付与完了/409:所持済みのアイテム
Example : 200

integer (int32)

ItemResults

アイテム情報の取得結果

Name Schema

results
optional

< ItemResult > array

Items

アイテムリスト

Name Schema

items
optional

< Item > array

ShopItem

ショップの購入確認画面を構成する際に必要となるアイテム情報

Name Description Schema

itemId
optional

アイテムID

integer (int64)

price
optional

価格。コンソールで設定されている値が返されます。

number (float)

shopId
optional

ショップID

integer (int64)

thumbnailUrl
optional

アイテムのサムネイル画像のURL

string

ShopSession

ショップのセッション情報

Name Description Schema

currencyId
optional

通貨ID

integer (int64)

items
optional

< ShopItem > array

Security

api_key

Type : apiKey
Name : key
In : QUERY