資產 API

*此內容是使用 AI（Beta 測試版）翻譯，可能含有錯誤。若要以英文檢視此頁面，請按一下這裡。

您可以發送並接收以下請求和回應載入來在 Roblox 上創建資產。對於 API 的使用，請參閱使用指南。

Assets

https://apis.roblox.com/assets

列出資產版本

GET /assets/v1/assets/{assetId}/versions

列出特定素材的所有版本，並提供可選的頁面。

參數

assetId string

素材的獨一標識。

Path

需要

maxPageSize number

指定要包含在回應中的資產版本數量。有效值範圍為 1 至 50 (包括)。預設值為 8 ，當未提供時。

pageToken string

頁面標識。值是從以前的請求中取得的，允許擷取資產版本的下一頁。

請求

List Asset Versions

curl --location 'https://apis.roblox.com/assets/v1/assets/{assetid}/versions?pageToken=&maxPageSize=' \
--header 'x-api-key: {apiKey}'

回應

其他狀態碼

需要權限

呼叫此端點需要以下 API 金鑰權限。有關如何產生正確金鑰的更多資訊，請查看管理 API 金鑰。

讀取

若想使用此端點，您的 OAuth 2.0 應用程式需要以下範圍。有關如何註冊 OAuth 2.0 應用程式的更多資訊，請查看應用程式註冊和審查。

asset:read

限制

每個 API 金鑰：每個 IP 位址每 60 秒 60 個請求

滾回資產版本

POST /assets/v1/assets/{assetId}/versions:rollback

擷回資產到特定的舊版本。

參數

assetId string

素材的獨一標識。

Path

需要

assetVersion string

資產版本路徑以 assets/{assetId}/versions/{versionNumber} 格式。

FormData

需要

請求

Rollback Asset Versions

curl --location 'https://apis.roblox.com/assets/v1/assets/{assetid}/versions:rollback' \
--header 'x-api-key: {apiKey}' \
--header 'Content-Type: application/json' \
--data '{\"assetVersion\":\"assets/{assetId}/versions/{versionNumber}\"}'

回應

其他狀態碼

需要權限

呼叫此端點需要以下 API 金鑰權限。有關如何產生正確金鑰的更多資訊，請查看管理 API 金鑰。

讀取
寫入

若想使用此端點，您的 OAuth 2.0 應用程式需要以下範圍。有關如何註冊 OAuth 2.0 應用程式的更多資訊，請查看應用程式註冊和審查。

asset:read
asset:write

限制

每個 API 金鑰：每個 IP 位址每 60 秒 60 個請求

取得資產

GET /v1/assets

取回特定資產內容和標籤。

參數

assetId

素材的獨一標識。

Path

需要

readMask string

資產標籤欄可取擷取，包括說明、顯示名稱、圖示、社交連結和預覽。範例: description%2CdisplayName , previews%2CtwitchSocialLink 。

請求

Get Asset without readMask

curl --location --request GET 'https://apis.roblox.com/assets/v1/assets/{assetId}' \
--header 'x-api-key: {apiKey}'

Get Asset with readMask

curl --location --request GET 'https://apis.roblox.com/assets/v1/assets/{assetId}?readMask={read_mask}' \
--header 'x-api-key: {apiKey}'

回應

其他狀態碼

需要權限

呼叫此端點需要以下 API 金鑰權限。有關如何產生正確金鑰的更多資訊，請查看管理 API 金鑰。

讀取

若想使用此端點，您的 OAuth 2.0 應用程式需要以下範圍。有關如何註冊 OAuth 2.0 應用程式的更多資訊，請查看應用程式註冊和審查。

asset:read

限制

每個 API 金鑰：每個 IP 位址每 60 秒 60 個請求

創建資產

POST /v1/assets

建立一個提供內容和資料的資產。

當你創建素材時，你不能添加社交連結對象。相反，你可以使用更新資產。

參數

request

資產屬性可以創建或更新。以下是示例請求的形式數據。

FormData

需要

fileContent string

二進資產檔案路徑和內容輸入。格式：fileContent=@"/filepath/{File}";type={ContentType}；類型fileContent=@"/filepath/model.fbx";type=model/fbx；範例：fileContent=@"/FilePath/model.fbx"; type=model/fbx 。參閱「內容類型」。

FormData

需要

請求

Create Asset

curl --location --request POST 'https://apis.roblox.com/assets/v1/assets' \
--header 'x-api-key: {apiKey}' \
--form 'request="{ 
  \"assetType\": \"Model\",  
  \"displayName\": \"Name\", 
  \"description\": \"This is a description\", 
  \"creationContext\": { 
    \"creator\": { 
      \"userId\": \"${userId}\" 
    } 
  } 
}"' \
--form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

回應

200 - OK

返回操作 ID 以檢查創建狀態。

傳回： object

done boolean

如果 false ，操作仍在進行中。如果 true ，操作已完成。

error object

說明錯誤狀態的論理錯誤模型。

metadata object

包含一個隨機串化訊息，以及一個 @type 表示訊息的類型。

path string

資源路徑。預設格式為 operations/{operation_id}。

response object

包含一個隨機串化訊息，以及一個 @type 表示訊息的類型。

其他狀態碼

需要權限

呼叫此端點需要以下 API 金鑰權限。有關如何產生正確金鑰的更多資訊，請查看管理 API 金鑰。

讀取
寫入

若想使用此端點，您的 OAuth 2.0 應用程式需要以下範圍。有關如何註冊 OAuth 2.0 應用程式的更多資訊，請查看應用程式註冊和審查。

asset:read
asset:write

限制

每個 API 金鑰：每個 IP 位址每 60 秒 60 個請求

更新資產

PATCH /v1/assets/{assetId}

更新資產，包括內容、顯示名稱、圖示、社交連結和預覽。目前只能更新資產體內的內容。圖示和預覽必須為模型。圖示必須有正方形尺寸。

參數

request

以下是一些像這些範例請求的形式資料。

FormData

需要

fileContent string

FormData

updateMask string

資產標籤欄可更新，包括說明、顯示名稱、圖示和預覽。範例： description%2CdisplayName， previews%2CtwitchSocialLink。

請求

Update Content Only and Create a New Version

curl --location --request PATCH 'https://apis.roblox.com/assets/v1/assets/{assetId}' \
--header 'x-api-key: {apiKey}' \
--form 'request="{\"assetId\": {assetId} }"' \
--form 'fileContent="@\"{file-path}\""'

Update Content and Metadata

curl --location --request PATCH 'https://apis.roblox.com/assets/v1/assets/{assetId}?updateMask=description%2CdisplayName' \
--header 'x-api-key: {apiKey}' \
--form 'request="{
    \"assetType\": \"{assetType}\",
    \"assetId\": {assetId},
    \"displayName\": \"{new display name}\",
    \"description\": \"{new description}\",    
    \"creationContext\": { 
        \"creator\": {
            \"userId\": {userId}
        },
        \"expectedPrice\":{expectedPrice}
    },
}"' \
--form 'fileContent=@\"{file-path}\"'

Update a List of Previews

curl --location --request PATCH 'https://apis.roblox.com/assets/v1/assets/{assetId}?updateMask=previews' \
--header 'x-api-key: {apiKey}' \
--form 'request="{\"assetId\": \"{assetId}\", \"previews\": [{\"asset\": \"assets/123\", \"altText\": \"Your alt text.\"}]}"'

Update Social Links

curl --location --request PATCH 'https://apis.roblox.com/assets/v1/assets/{assetId}?updateMask=twitchSocialLink%2CgithubSocialLink' \
--header 'x-api-key: {apiKey}' \
--form 'request="{\"assetId\": \"{assetId}\", \"twitchSocialLink\": {\"title\": \"Optional title\", \"uri\": \"https://twitch.tv/your-channel\"}, \"githubSocialLink\": {\"title\": \"Optional title\", \"uri\": \"https://github.com/your-repo\"}}"'

回應

200 - OK

返回運作ID以檢查更新狀態/ 返回已更新的元數據欄。

傳回： object

application/json

{\"previews\": [\n    {\"asset\": \"assets/123\", \"altText\": \"preview 1\"},\n    {\"asset\": \"assets/456\", \"altText\": \"preview 2\"}\n]}

done boolean

如果 false ，操作仍在進行中。如果 true ，操作已完成。

error object

說明錯誤狀態的論理錯誤模型。

metadata object

包含一個隨機串化訊息，以及一個 @type 表示訊息的類型。

path string

資源路徑。預設格式為 operations/{operation_id}。

response object

包含一個隨機串化訊息，以及一個 @type 表示訊息的類型。

其他狀態碼

需要權限

呼叫此端點需要以下 API 金鑰權限。有關如何產生正確金鑰的更多資訊，請查看管理 API 金鑰。

讀取
寫入

若想使用此端點，您的 OAuth 2.0 應用程式需要以下範圍。有關如何註冊 OAuth 2.0 應用程式的更多資訊，請查看應用程式註冊和審查。

asset:read
asset:write

限制

每個 API 金鑰：每個 IP 位址每 60 秒 60 個請求

取得資產版本

GET /v1/assets/{assetId}/versions/{versionNumber}

取回特定資產版本的資產 ID 和版本號。

參數

assetId string

素材的獨一標識。

Path

需要

versionNumber string

版本號。

Path

需要

請求

Get Asset Version

curl --location 'https://apis.roblox.com/assets/v1/assets/{assetId}/versions/{versionNumber}' \
--header 'x-api-key: {apiKey}'

回應

其他狀態碼

需要權限

呼叫此端點需要以下 API 金鑰權限。有關如何產生正確金鑰的更多資訊，請查看管理 API 金鑰。

讀取

若想使用此端點，您的 OAuth 2.0 應用程式需要以下範圍。有關如何註冊 OAuth 2.0 應用程式的更多資訊，請查看應用程式註冊和審查。

asset:read

限制

每個 API 金鑰：每個 IP 位址每 60 秒 60 個請求

獲得操作

GET /v1/operations/{operationId}

使用返回的操作 ID 取得資產創建或更新的結果。需要閱讀對於 API 鑰匙權限的許可，和素材:閱讀對於 OAuth 2.0 應用程式的許可。

請求

Get Operation

curl --location 'https://apis.roblox.com/assets/v1/operations/{operationId}' \
--header 'x-api-key: {apiKey}'

回應

200 - OK

傳回： object

done boolean

如果 false ，操作仍在進行中。如果 true ，操作已完成。

error object

說明錯誤狀態的論理錯誤模型。

metadata object

包含一個隨機串化訊息，以及一個 @type 表示訊息的類型。

path string

資源路徑。預設格式為 operations/{operation_id}。

response object

包含一個隨機串化訊息，以及一個 @type 表示訊息的類型。

其他狀態碼

需要權限

呼叫此端點需要以下 API 金鑰權限。有關如何產生正確金鑰的更多資訊，請查看管理 API 金鑰。

讀取

若想使用此端點，您的 OAuth 2.0 應用程式需要以下範圍。有關如何註冊 OAuth 2.0 應用程式的更多資訊，請查看應用程式註冊和審查。

asset:read

限制

每個 API 金鑰：每個 IP 位址每 60 秒 60 個請求

物件

以下物件描述被接受或退回的負載。若要獲得更多關於物件使用時機的資訊，請查看個別終點。

Any

包含一個隨機串化訊息，以及一個 @type 表示訊息的類型。

特性

@type string

串化訊息的類型。

Asset

代表資產。

特性

assetId number

素材的獨一標識。需要於更新資產。

assetType string

資產類輸入。只能是 Audio、Decal 或 Model。需要 1>創建資產1> 。

creationContext object

不屬於資產內容的創建上下文，例如資料庫資訊和創作者資訊。需要在建立資產上使用。

description string

素材的說明。最多 1000 個字符。需要創建資產。

displayName string

顯示素材的名稱。需要用於建立資產。

icon string

圖示的資源路徑。

moderationResult object

素材的Moderation結果。

path string

資產的返回資源路徑。格式：assets/{assetId}。範例：assets/2205400862。

previews array<object>

一個預覽清單，每個都有資產路徑和 alt 文字。預覽必須是圖像資產。

revisionCreateTime string

目前版本的創建時間。

revisionId string

素材的修訂ID。與 versionNumber 相同。每次資產的變更都會自動提交新版本。格式是整數字串。範例： 1 。

socialLink object

資產的社交媒體連結。最多三個素材結 per 資產。對象名稱可以是任何：<

CreationContext

不屬於資產內容的創建上下文，例如資料庫資訊和創作者資訊。需要在建立資產上使用。

特性

creator object

代表創作者。

需要

expectedPrice number

在 Robux 中預期的資產上傳費。當實際價格超過預期時，運行會發生 400 錯誤。

Creator

代表創作者。

特性

groupId number

團體ID。需要資產是團體擁有。

userId number

資產擁有創作者的使用者ID。需要，如果資產是單個使用者擁有的。

ModerationResult

素材的Moderation結果。

特性

moderationState string

素材的審核狀態。可以 MODERATION_STATE_REVIEWING， MODERATION_STATE_REJECTED 或 MODERATION_STATE_APPROVED 。

Operation

這個資源代表一個長時間運行的操作，是網路 API 呼叫的結果。

特性

done boolean

如果 false ，操作仍在進行中。如果 true ，操作已完成。

error object

說明錯誤狀態的論理錯誤模型。

metadata object

包含一個隨機串化訊息，以及一個 @type 表示訊息的類型。

path string

資源路徑。預設格式為 operations/{operation_id}。

response object

包含一個隨機串化訊息，以及一個 @type 表示訊息的類型。

Preview

資產預覽。

特性

altText string

預覽資素材的 alt 文字。

asset string

預覽資產路徑。

SocialLink

資產的社交媒體連結。最多三個素材結 per 資產。對象名稱可以是任何：<

特性

title string

可選的社交媒體綁定結標題。不在創作者中心使用。

uri string

社交媒體綁定結的 URL。必須與預期的綁定式一致。例如，twitchSocialLink 對象的標題必須為https://twitch.tv/your-channel 。

Status

說明錯誤狀態的論理錯誤模型。

特性

code number

HTTP 狀態碼。

details array<object>

一個含有錯誤細節的訊息列表。

message string

錯誤訊息。