Overview

Version information

Version : 1.0.0

URI scheme

Host : api.avatarplay3d.com
BasePath : /
Schemes : HTTPS

Consumes

  • application/x-www-form-urlencoded

Produces

  • application/json

Paths

POST /avatar/v1/AccessToken

Description

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

Parameters

Type Name Description Schema

Query

codeVerifier
required

ConnectUrlのcodeChallengeの生成で利用したcodeVerifier Example: 4hmLHty5K6P…

string

Query

redirectUri
required

ConnectUrlで指定したリダイレクトURI Example: https://example.com/oauth_callback

string

Query

requestDate
required

ConnectUrlのcodeChallengeの生成で利用したリクエスト日時 Example: 1552356284

integer (int64)

Query

scope
required

ConnectUrlで指定したスコープ Example: AvatarLoad,ItemGrant

string

Query

token
required

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

string

Responses

HTTP Code Description Schema

200

成功

default

エラー

Security

Type Name

apiKey

GET /avatar/v1/Avatar/{avatarId}

Description

ひとつのアバターIDを指定して、アバター画像のURLなどを取得するAPIです。複数のアバター画像を取得するには、Avatars API を利用します。

Parameters

Type Name Description Schema

Path

avatarId
required

アバターID

integer (int64)

Responses

HTTP Code Description Schema

200

成功

default

エラー

Security

Type Name

apiKey

GET /avatar/v1/Avatar/{avatarId}/FittingRoom

Description

着せ替え中のアバターと所持アイテムリストを取得するAPIです。着せ替え用のAPI(FittingRoom以下のAPI)は、ユーザーの操作と連動して利用する必要があります。

Parameters

Type Name Description Schema

Path

avatarId
required

アバターID

integer (int64)

Query

limit
optional

取得するアイテム個数。指定しない場合、10個として扱わます。最大50個まで指定できます。

integer (int32)

Query

page
optional

取得するページ。最初のページは0から始まります。指定しない場合、0ページ目として扱われます。最大99ページまで指定できます。

integer (int32)

Responses

HTTP Code Description Schema

200

成功

default

エラー

Security

Type Name

apiKey

POST /avatar/v1/Avatar/{avatarId}/FittingRoom/Commit

Description

着せ替えを完了し、完了したコーデをメインのアバターへ反映します。

Parameters

Type Name Description Schema

Path

avatarId
required

アバターID

integer (int64)

Responses

HTTP Code Description Schema

200

成功

No Content

default

エラー

Security

Type Name

apiKey

POST /avatar/v1/Avatar/{avatarId}/FittingRoom/Select

Description

着せ替えルーム内でアイテムを選択します。選択したアイテムを着るまたは外すアクションの両方を実現します。Commit API を呼び出すまでは、メインのアバターは変更されません。着せ替え後のアバター画像は FittingRoom API 経由で取得します。ユーザが所持していないアイテムや利用可能でないアイテムを指定するとエラーとなります。

Parameters

Type Name Description Schema

Path

avatarId
required

アバターID

integer (int64)

Query

item_id
required

アイテムID。FittingRoom API で取得したアイテムリストのうち、利用可能であるアイテムを指定できます。

integer (int64)

Responses

HTTP Code Description Schema

200

成功

No Content

default

エラー

Security

Type Name

apiKey

POST /avatar/v1/Avatar/{avatarId}/Items

Description

指定したアバターIDを持つユーザに、指定したアイテムを付与します。前提として、アイテム付与の権限を持つアクセストークンが有効となっている必要があります。

Parameters

Type Name Description Schema

Path

avatarId
required

アバターID

integer (int64)

Query

itemId
required

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

< integer (int64) > array(multi)

Responses

HTTP Code Description Schema

200

成功

default

エラー

Security

Type Name

apiKey

GET /avatar/v1/Avatars

Description

アバターIDを指定して、アバター画像のURLなどを取得するAPIです。全身のアバター画像と、サムネイル表示などに使えるバストアップ画像のURLを取得できます。

全身のアバター画像には、テイストに応じたアニメーションが付きます。バストアップ画像にはアニメーションは付きません。

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

エラー

Security

Type Name

apiKey

GET /avatar/v1/ConnectUrl

Description

ID連携(OAuth認証)用のURLを取得します。

このURLへ遷移すると、Avatar Play 着せ替えアプリのインストールを経て、最後には付与トークンが付加されたリダイレクトURIへユーザーを誘導します。

Parameters

Type Name Description Schema

Query

avatarId
optional

アップグレードの場合、ゲストとして割り振ったアバターID。アップグレードする場合は必ず指定してください。ゲストユーザの所持アイテム正規ユーザが引き継がれます。AccessToken API では新しいアバターIDが割り振られ、ゲスト時のアバターID(ここで指定されたアバターID)は無効となります。ここに正規ユーザやアップグレード済みのゲストユーザのアバターIDを指定しても、無視されます。

integer (int64)

Query

codeChallenge
required

認証で利用するチャレンジ値。アプリID、応答種類(「grant_token」で固定)、リダイレクトURI、スコープ、リクエスト日時(UnixTime秒)、APIキー、検証用コードをこの順序でコロン「:」区切りに連結した文字列を、SHA256でハッシュ化した文字列になります。 Example: f39cbe206…

string

Query

redirectUri
required

最後にユーザを誘導するURL。URLの最後に、「token」パラメータが付与され、値に付与トークンが引き渡されます。この付与トークンは、AccessToken APIにそのまま引き渡します。 Example: https://example.com/oauth_callback

string

Query

scope
required

スコープ。パーミッション名をカンマ区切りで連結した文字列。 Example: AvatarLoad,ItemGrant

string

Responses

HTTP Code Description Schema

200

成功

default

失敗

Security

Type Name

apiKey

GET /avatar/v1/Coords

Description

アプリ内コーデの画像URLを取得するAPIです。コーデ画像はアニメーションしません。

Parameters

Type Name Description Schema

Query

coordId
optional

コーデID。複数指定可能です。事前にアプリ内で利用できるコーデとして割り当てられている必要があります。指定したコーデIDが見つからない場合、エラーを返します。この点は Avatars APIと挙動が異なるため、注意してください。

コーデIDを指定しなかった場合、アプリが初期コーデとして利用可能な全てのコーデ画像のリストを返します。

< integer (int64) > array(multi)

Responses

HTTP Code Description Schema

200

成功。コーデ画像のURLリストを返します。

default

失敗

Security

Type Name

apiKey

GET /avatar/v1/Echo

Description

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

Parameters

Type Name Description Schema

Query

message
optional

出力するメッセージ

string

Responses

HTTP Code Description Schema

200

成功

default

失敗

Security

Type Name

apiKey

POST /avatar/v1/Guest

Description

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

Parameters

Type Name Description Schema

Query

coordId
optional

ゲストアバターのコーデIDを指定します。指定しない場合、デフォルトアバターのコーデになります。

integer (int64)

Query

scope
optional

スコープ。パーミッション名をカンマ区切りで連結した文字列。指定しなかった場合、アバターをロードする権限(AvatarLoad)のみのスコープを要求します。ゲストユーザに対してアイテム付与するためには、アイテム付与権限(ItemGrant)を指定する必要があります。この指定が可能なのは、アプリが iOS/Android アプリであり、かつ着せ替えアプリとの連携が正しく実装され審査に通過している必要があります。Example: AvatarLoad,ItemGrant

< string > array(multi)

Responses

HTTP Code Description Schema

200

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

default

失敗

Security

Type Name

apiKey

GET /avatar/v1/Items

Description

アプリで利用可能なアイテムの情報(サムネイル画像URLなど)をを取得します。

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

失敗

Security

Type Name

apiKey

GET /avatar/v1/OpenUrl

Description

Avatar Play の起動URLを取得します。 このURLへ遷移すると、アプリインストール済みの場合はアプリが起動し、アプリ未インストールならアプリのインストール画面が開きます。 このURLは、リダイレクトの途中では利用できません。必ずWebページ内に埋め込む形でリンクしてください。

Responses

HTTP Code Description Schema

200

成功

default

失敗

Security

Type Name

apiKey

Definitions

AccessToken

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

Name Description Schema

accessToken
optional

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

string

avatarId
optional

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

integer (int64)

scope
optional

スコープ。ConnectUrl APIで渡したスコープと同じです。
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

avatarNonAnimationImageUrl
optional

アバター全身画像のURLですが、アニメーションは付きません。画像は240x320ピクセルサイズのGIFファイルです。
Example : "https://example.com/avatar.gif"

string

faceImageUrl
optional

アバターバストアップ画像のURL。画像は60x80ピクセルサイズの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

ConnectUrl

ID連携用のURL

Name Description Schema

url
optional

ID連携用のURL
Example : "https://sdk.avatarplay3d.com/fit/lp"

string

Coord

コーデ画像URLのリスト

Name Description Schema

coordId
optional

コーデID
Example : 1234567890

integer (int64)

coordImageUrl
optional

コーデ画像のURL
Example : "https://example.com/coord.gif"

string

Coords

Coord のリストです。

Name Schema

coordImages
optional

< Coord > array

Echo

エコー出力

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

FittingRoom

着せ替えルーム。着せ替え中のアバターと所持アイテムリストを保持します。

Name Description Schema

avatarImageUrl
optional

着せ替え中のコーデの画像URL
Example : "https://example.com/fitting_room.gif"

string

items
optional

所持アイテムのリスト。メインコーデに設定したものが先頭に配置されます。

< FittingRoomItem > array

FittingRoomItem

FittingRoom API で得られるアイテム情報

Name Description Schema

itemId
optional

アイテムID
Example : 1234567890

integer (int64)

selectable
optional

選択可能なアイテムなら真。外せない着用中アイテムや、利用範囲が限定されているアイテムなどの理由で着用できない場合、偽が設定されます。偽となっているアイテムは、ユーザが選択できないようUIを設計する必要があります。
Example : true

boolean

thumbnailUrl
optional

アイテムのサムネイル画像URL
Example : "https://example.com/thumbnail.png"

string

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

OpenUrl

Avatar Play の着せ替えアプリを起動するURL

Name Description Schema

url
optional

Avatar Play の着せ替えアプリを起動するURL
Example : "https://avatarplay3d.page.link/"

string

Security

api_key

Type : apiKey
Name : key
In : QUERY