経験はさまざまなアイコン/サムネイルメディアに関連付けられています。プレイスアイコンは単一の正方形画像です。経験詳細ページのサムネイルはゲームページ上の順序付きリストです。ホームページのサムネイルはRobloxがホームページで回転させることができる画像です。「サムネイル」と「プレビュー」という用語は互換的に使用されます。
| 画像 | 識別子 | リクエスト |
|---|---|---|
| プレイスアイコン | プレイスID | アセットの更新をupdateMask=iconで |
| 翻訳されたアイコン | ユニバースIDと言語コード | ゲームのアイコンを更新 |
| 経験詳細ページのサムネイル | プレイスID | アセットの更新をupdateMask=previewsで |
| ホームページのサムネイル | ユニバースIDとホームページサムネイルID | サムネイルパーソナライズAPI |
APIを呼び出す前に
APIキーを作成し、x-api-keyヘッダーに送信します。
- プレイスアイコンと経験詳細ページのサムネイルについては、アセットをアクセス許可に追加し、ゲームに対して読み取りと書き込みを付与します。これらの呼び出しはasset:readおよびasset:writeスコープを使用します。
- ホームページのサムネイル呼び出しには、そのゲームに対してuniverse.thumbnail:readおよびuniverse.thumbnail:writeスコープが必要です。
- 翻訳されたアイコ呼び出しにはlegacy-universe:manageスコープが必要です。
アイコンと詳細ページの呼び出しにはプレイスIDが必要です。ホームページの呼び出しにはユニバースIDが必要です。両方をクリエイターダッシュボードからコピーします：
- ゲームのサムネイルにカーソルを合わせ、**⋯**ボタンをクリックし、ユニバースIDをコピーを選択します。
- ゲームを開き、次に設定 > プレイスを開きます。
- スタートプレイスを開きます。プレイスIDはURLにあります。例えば、https://create.roblox.com/dashboard/creations/experiences/0000000/places/111111/configure,ではプレイスIDは111111`です。
同じアイコンとプレビューの呼び出しは、スタートプレイス以外のプレイスでも機能します。その画像がそのプレイスに属する場合は、そのプレイスのIDを渡します。
画像をアップロードする
プレイスアイコンと経験詳細ページのサムネイルは、既存の画像アセットへのパスを保存します。例えば、assets/2205400862のように。ファイルをアセットを作成でアップロードし、doneがtrueになるまで操作を取得をポーリングします。その操作からresponse.assetIdを読み取ります。アップロードフロー、制限、グループ所有権の詳細については、アセットの使用ガイドを参照してください。
ゲームを所有している場合はuserIdを使用します。グループが所有している場合は代わりにgroupIdを使用します。
curl --location 'https://apis.roblox.com/assets/v1/assets' \
--header 'x-api-key: ${ApiKey}' \
--form 'request="{
\"assetType\": \"Image\",
\"displayName\": \"経験画像\",
\"description\": \"経験アイコンまたはサムネイル用の画像\",
\"creationContext\": {
\"creator\": {
\"userId\": \"${UserId}\"
},
\"assetPrivacy\": \"OpenUse\"
}
}";type=application/json' \
--form 'fileContent=@"/filepath/image.png";type=image/png'アップロードする前にファイルを準備します。プレイスアイコンは正方形でなければならず、非正方形のファイルは拒否されます。推奨サイズやその他の画像要件については、アイコンおよびサムネイルを参照してください。
画像はオープン使用に設定されている必要があります。アセットプライバシーが有効でない場合、画像はデフォルトでオープン使用です。新しい画像をオープン使用にするには、リクエストのcreationContext.assetPrivacyをOpenUseに設定します。既存の画像を変更するには、オープン権限を参照してください。
プレイヤーは、モデレーションが承認した後に画像を見ることができます。操作の応答にはmoderationResult.moderationStateが含まれます。
プレイスアイコンを更新する
メイン記事: アイコン
プレイスに対してアセットを更新を送信します。updateMaskをiconに設定し、iconを画像アセットパスに設定します。fileContentは省略します。この呼び出しは、ソース言語のアイコンを置き換えます。
curl --location --request PATCH 'https://apis.roblox.com/assets/v1/assets/${PlaceId}?updateMask=icon' \
--header 'x-api-key: ${ApiKey}' \
--form 'request="{
\"assetId\": \"${PlaceId}\",
\"icon\": \"assets/${ImageAssetId}\"
}";type=application/json'アイコンを削除するには、iconを空の文字列に設定して同じリクエストを送信します。
翻訳されたアイコンを更新する
メイン記事: アイコン
ローカライズされたゲームアイコンエンドポイントは、ソース言語以外の言語のアイコンを更新します。ソース言語のリクエストは拒否されます。プレイヤーが翻訳前に見るアイコンにはプレイスアイコンを更新するを使用します。
gameIdはユニバースIDです。Filesは正方形のアイコン画像です。
curl --location --request POST 'https://apis.roblox.com/legacy-game-internationalization/v1/game-icon/games/${UniverseId}/language-codes/${LanguageCode}' \
--header 'x-api-key: ${ApiKey}' \
--form 'Files=@"/filepath/icon.png"'経験詳細ページのサムネイルを更新する
メイン記事: サムネイル
詳細ページのサムネイルは、プレイスアセットのpreviewsリストです。各エントリは画像アセットパスとオプションのaltテキストです。配列の順序はゲームページ上の順序です。
updateMask=previewsはリスト全体を置き換えます。残すべきすべてのサムネイルを含め、位置が変更されるサムネイルも含めます。サムネイルを省略すると、それが削除されます。1つのエントリを送信すると、その画像が唯一の詳細ページサムネイルになります。
変更する前に現在のリストを読み取ります：
curl --location 'https://apis.roblox.com/assets/v1/assets/${PlaceId}?readMask=previews' \
--header 'x-api-key: ${ApiKey}'新しいファイルをアップロードした後、フルリストを送信します：
curl --location --request PATCH 'https://apis.roblox.com/assets/v1/assets/${PlaceId}?updateMask=previews' \
--header 'x-api-key: ${ApiKey}' \
--form 'request="{
\"assetId\": \"${PlaceId}\",
\"previews\": [
{
\"asset\": \"assets/${FirstImageAssetId}\",
\"altText\": \"プレイヤーが街をレースしている\"
},
{
\"asset\": \"assets/${SecondImageAssetId}\",
\"altText\": \"新しい車両のクローズアップ\"
}
]
}";type=application/json'このリクエストは画像リストを更新します。ゲームが表示できる画像や動画の数、動画サムネイルやaltテキストについてはサムネイルを参照してください。
ホームページのサムネイルを更新する
メイン記事: ホームページのパーソナライズ
ホームページのサムネイルは、previewsではなくサムネイルパーソナライズAPIを使用します。そのAPIを通じてアップロードし、ホームページサムネイルIDを待ってから、アクティブセットを保存します。homepageThumbnailIdsのIDはホームページサムネイルIDであり、画像アセットIDやassets/2205400862のようなパスではありません。
ホームページのパーソナライズで画像要件とアクティベーションルールに従ってください。
ホームページサムネイルをアップロードする
curl --location --request POST 'https://apis.roblox.com/thumbnail-personalization-api/v1/universes/${UniverseId}/thumbnails/uploads' \
--header 'x-api-key: ${ApiKey}' \
--form 'files=@"/filepath/thumbnail.png"'応答は各ファイル名をfileToOperationIdDictの操作IDにマッピングします。その操作をポーリングして、uploadThumbnailStatusDictに含まれるまで待ち、次にhomepageThumbnailIdをコピーします：
curl --location 'https://apis.roblox.com/thumbnail-personalization-api/v1/universes/${UniverseId}/thumbnails/uploads/status?operationIds=${OperationId}' \
--header 'x-api-key: ${ApiKey}'すでにホームページにあるサムネイルを再利用するには、それらをリストし、assetIdを一致させます。承認された動画サムネイルは、画像と同じ方法で含まれます：リストエントリのassetIdは動画アセットであり、homepageThumbnailIdsはそのエントリのhomepageThumbnailIdを取ります。このAPIのアップロードリクエストは画像ファイルを受け入れます。動画のルールや月間のクォータについてはサムネイルを参照してください。
curl --location 'https://apis.roblox.com/thumbnail-personalization-api/v1/universes/${UniverseId}/thumbnails' \
--header 'x-api-key: ${ApiKey}'アクティブなホームページサムネイルを選択する
新しいアクティブセットが必要な場合は構成を作成します。これにより、以前の構成が非アクティブになり、新しい統計が開始されます。リストには最大5つのホームページサムネイルIDを含めることができます。この例では、1つのサムネイルをアクティブにします：
curl --location --request POST 'https://apis.roblox.com/thumbnail-personalization-api/v1/universes/${UniverseId}/personalization/create' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
"homepageThumbnailIds": ["${HomepageThumbnailId}"]
}'アクティブ構成を更新して、統計をリセットせずにアクティブセットを変更します。最初にアクティブ構成を読み取り、そのidを返します：
curl --location 'https://apis.roblox.com/thumbnail-personalization-api/v1/universes/${UniverseId}/personalization?status=Active' \
--header 'x-api-key: ${ApiKey}'curl --location --request POST 'https://apis.roblox.com/thumbnail-personalization-api/v1/universes/${UniverseId}/personalization/update' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
"id": "${ConfigurationId}",
"homepageThumbnailIds": ["${HomepageThumbnailId}"]
}'homepageThumbnailIdsはアクティブなサムネイルを指定します。リスト内の順序は重要ではありません。パーソナライズは、各プレイヤーが見るアクティブなサムネイルを選択します。