资产 API

*此内容使用人工智能(Beta)翻译,可能包含错误。若要查看英文页面,请点按 此处

您可以发送和接收以下请求和响应 payload 来在 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}'

答复

200 - OK
列出的资产版本成功。
返回: array<object>

必要权限

调用此端点需要以下 API 密钥权限。关于生成正确密钥的更多信息,请查看 【管理 API 密钥】(/cloud/auth/api-keys)。

  • 读取

限制

每个 API 密钥:每个 IP 地址每 60 秒有 100 次请求

返回资产版本

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

将资产滚动到特定的以前版本。

在表单数据中提供资产版本路径。

参数

assetId string

素材的唯一标识。

Path
必填

请求

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}\"}'

答复

200 - OK
资产成功滚回。
返回: object
creationContext object

不属于资产内容的创建上下文,例如元数据和创建者信息。需要用于创建资产

moderationResult object

素材的审核结果。

path string

资产版本的返回资源路径。格式:assets/{assetId}/versions/{version}。例如:assets/2205400862/versions/1

必要权限

调用此端点需要以下 API 密钥权限。关于生成正确密钥的更多信息,请查看 【管理 API 密钥】(/cloud/auth/api-keys)。

  • 读取

  • 写入

限制

每个 API 密钥:每个 IP 地址每 60 秒有 100 次请求

创建资产

POST /v1/assets

创建带有提供内容和元数据的资产。

当你创建素材时,你不能添加 社交链接 对象。取而代之,使用 更新资产

在形式数据中提供 资产、二进制资产文件路径和 内容类型

请求

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 密钥】(/cloud/auth/api-keys)。

  • 读取

  • 写入

限制

每个 API 密钥:每个 IP 地址每 60 秒有 60 次请求

获取资产

GET /v1/assets/{assetId}

检索特定资产内容和元数据。

参数

assetId string

素材的唯一标识。

Path
必填
readMask string

要取回的资产元数据字段,包括描述、显示名称、标志、社交链接和预览。例如:description%2CdisplayNamepreviews%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}'

答复

200 - OK
资产资源成功获取。
返回: object
assetId number

素材的唯一标识。需要用于更新资产

assetType string

资产类输入。只能是 Audio , Decal , 或 Model . 需要用于 创建资产

creationContext object

不属于资产内容的创建上下文,例如元数据和创建者信息。需要用于创建资产

description string

素材的描述。限于 1000 个字符。需要用于 创建资产

displayName string

素材的显示名称。需要用于创建资产

icon string

标志的资源路径。

moderationResult object

素材的审核结果。

path string

素材的返回资源路径。格式:assets/{assetId}。例如:assets/2205400862

previews array<object>

预览列表,每个预览都包含一个资产路径和替换文本。预览必须是 图像 资产。

revisionCreateTime string

当前版本的创建时间戳。

revisionId string

素材的版本 ID。等于 versionNumber .资产的每次更改都会自动提交新版本。格式是一个整数字符串。例子:1

socialLink object

素材的社交媒体链接。每个素材最多三个。对象名称可以是任何: > > > > > > > > > > > > > > > 对于语法,请参阅更新资产下的样本请求。

state string

资产是否激活或归档。未指定的不会被使用。

必要权限

调用此端点需要以下 API 密钥权限。关于生成正确密钥的更多信息,请查看 【管理 API 密钥】(/cloud/auth/api-keys)。

  • 读取

限制

每个 API 密钥:每个 IP 地址每 60 秒有 60 次请求

更新资产

PATCH /v1/assets/{assetId}

使用提供的内容和元数据更新资产,包括描述、显示名称、图标、社交链接和预览。目前只能为 模型 更新内容体。图标和预览必须是 图像 资产。图标必须有正方形尺寸。

在形式数据中提供 资产、二进制资产文件路径和 内容类型

参数

assetId string

素材的唯一标识。

Path
必填
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

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

答复

200 - OK
返回操作 ID 进行更新状态检查/返回更新的元数据字段。
返回: object
application/json

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

如果 false , 操作仍在进行中。如果 true , 操作已完成。

error object

描述错误状态的逻辑错误模型。

metadata object

包含一个随机序列化消息以及一个 @type 描述序列化消信息类型的字符串。

path string

服务器分配的资源路径。默认格式为 operations/{operation_id}

response object

包含一个随机序列化消息以及一个 @type 描述序列化消信息类型的字符串。

必要权限

调用此端点需要以下 API 密钥权限。关于生成正确密钥的更多信息,请查看 【管理 API 密钥】(/cloud/auth/api-keys)。

  • 读取

  • 写入

限制

每个 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}'

答复

200 - OK
资产版本成功获取。
返回: object
creationContext object

不属于资产内容的创建上下文,例如元数据和创建者信息。需要用于创建资产

moderationResult object

素材的审核结果。

path string

资产版本的返回资源路径。格式:assets/{assetId}/versions/{version}。例如:assets/2205400862/versions/1

必要权限

调用此端点需要以下 API 密钥权限。关于生成正确密钥的更多信息,请查看 【管理 API 密钥】(/cloud/auth/api-keys)。

  • 读取

限制

每个 API 密钥:每个 IP 地址每 60 秒有 100 次请求

归档资产

POST /v1/assets/{assetId}:archive

归档资产。归档的资产从网站消失,不再可用或可见于 Roblox 体验中,但您可以 恢复 它们。

参数

assetId string

素材的唯一标识。

Path
必填

请求

Archive Asset

curl --location 'https://apis.roblox.com/assets/v1/assets/{assetid}:archive' \
--header 'x-api-key: {apiKey}' \
--header 'Content-Type: application/json'

答复

200 - OK
资产成功归档。
返回: object
assetId number

素材的唯一标识。需要用于更新资产

assetType string

资产类输入。只能是 Audio , Decal , 或 Model . 需要用于 创建资产

creationContext object

不属于资产内容的创建上下文,例如元数据和创建者信息。需要用于创建资产

description string

素材的描述。限于 1000 个字符。需要用于 创建资产

displayName string

素材的显示名称。需要用于创建资产

icon string

标志的资源路径。

moderationResult object

素材的审核结果。

path string

素材的返回资源路径。格式:assets/{assetId}。例如:assets/2205400862

previews array<object>

预览列表,每个预览都包含一个资产路径和替换文本。预览必须是 图像 资产。

revisionCreateTime string

当前版本的创建时间戳。

revisionId string

素材的版本 ID。等于 versionNumber .资产的每次更改都会自动提交新版本。格式是一个整数字符串。例子:1

socialLink object

素材的社交媒体链接。每个素材最多三个。对象名称可以是任何: > > > > > > > > > > > > > > > 对于语法,请参阅更新资产下的样本请求。

state string

资产是否激活或归档。未指定的不会被使用。

必要权限

调用此端点需要以下 API 密钥权限。关于生成正确密钥的更多信息,请查看 【管理 API 密钥】(/cloud/auth/api-keys)。

  • 读取

  • 写入

限制

每个 API 密钥:每个 IP 地址每 60 秒有 100 次请求

恢复资产

POST /v1/assets/{assetId}:restore

恢复已归档的素材。

参数

assetId string

素材的唯一标识。

Path
必填

请求

Restore Asset

curl --location 'https://apis.roblox.com/assets/v1/assets/{assetid}:restore' \
--header 'x-api-key: {apiKey}' \
--header 'Content-Type: application/json'

答复

200 - OK
资产恢复成功。
返回: object
assetId number

素材的唯一标识。需要用于更新资产

assetType string

资产类输入。只能是 Audio , Decal , 或 Model . 需要用于 创建资产

creationContext object

不属于资产内容的创建上下文,例如元数据和创建者信息。需要用于创建资产

description string

素材的描述。限于 1000 个字符。需要用于 创建资产

displayName string

素材的显示名称。需要用于创建资产

icon string

标志的资源路径。

moderationResult object

素材的审核结果。

path string

素材的返回资源路径。格式:assets/{assetId}。例如:assets/2205400862

previews array<object>

预览列表,每个预览都包含一个资产路径和替换文本。预览必须是 图像 资产。

revisionCreateTime string

当前版本的创建时间戳。

revisionId string

素材的版本 ID。等于 versionNumber .资产的每次更改都会自动提交新版本。格式是一个整数字符串。例子:1

socialLink object

素材的社交媒体链接。每个素材最多三个。对象名称可以是任何: > > > > > > > > > > > > > > > 对于语法,请参阅更新资产下的样本请求。

state string

资产是否激活或归档。未指定的不会被使用。

必要权限

调用此端点需要以下 API 密钥权限。关于生成正确密钥的更多信息,请查看 【管理 API 密钥】(/cloud/auth/api-keys)。

  • 读取

  • 写入

限制

每个 API 密钥:每个 IP 地址每 60 秒有 100 次请求

获取操作

GET /v1/operations/{operationId}

使用返回的操作 ID 获取资产创建或更新的结果。需要 阅读 API 钥匙权限和 素材:阅读 OAuth 2.0 应用程序。

参数

operationId string

操作的唯一标识。

Path
必填

请求

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 密钥】(/cloud/auth/api-keys)。

  • 读取

限制

每个 API 密钥:每个 IP 地址每 60 秒有 100 次请求

对象

下列对象描述了接受或返回的有效载荷。请参阅每个单独的端点,以了解更多关于这些对象用途的信息。

Any

包含一个随机序列化消息以及一个 @type 描述序列化消信息类型的字符串。

属性

@type string

序列化消信息的类型。

Asset

代表一个资素材。

属性

assetId number

素材的唯一标识。需要用于更新资产

assetType string

资产类输入。只能是 Audio , Decal , 或 Model . 需要用于 创建资产

creationContext object

不属于资产内容的创建上下文,例如元数据和创建者信息。需要用于创建资产

description string

素材的描述。限于 1000 个字符。需要用于 创建资产

displayName string

素材的显示名称。需要用于创建资产

icon string

标志的资源路径。

moderationResult object

素材的审核结果。

path string

素材的返回资源路径。格式:assets/{assetId}。例如:assets/2205400862

previews array<object>

预览列表,每个预览都包含一个资产路径和替换文本。预览必须是 图像 资产。

revisionCreateTime string

当前版本的创建时间戳。

revisionId string

素材的版本 ID。等于 versionNumber .资产的每次更改都会自动提交新版本。格式是一个整数字符串。例子:1

socialLink object

素材的社交媒体链接。每个素材最多三个。对象名称可以是任何: > > > > > > > > > > > > > > > 对于语法,请参阅更新资产下的样本请求。

state string

资产是否激活或归档。未指定的不会被使用。

AssetVersion

一个资产版本。

属性

creationContext object

不属于资产内容的创建上下文,例如元数据和创建者信息。需要用于创建资产

moderationResult object

素材的审核结果。

path string

资产版本的返回资源路径。格式:assets/{assetId}/versions/{version}。例如:assets/2205400862/versions/1

CreationContext

不属于资产内容的创建上下文,例如元数据和创建者信息。需要用于创建资产

属性

creator object

代表一个创建创作者。

必填
expectedPrice number

在 Robux 中预期的资产上传费用。当实际价格超出预期时,操作以 400 错误失败。

Creator

代表一个创建创作者。

属性

groupId number

组 ID。如果资产属于集团,则必须填写。

userId number

用户 ID 是创作者建者。如果资产是个人所有的,则必须使用。

ModerationResult

素材的审核结果。

属性

moderationState string

素材的审核状态。可以是 Reviewing , Rejected , 或 Approved .

Operation

该资源代表一个长时间运行的操作,该操作是网络 API 调用的结果。

属性

done boolean

如果 false , 操作仍在进行中。如果 true , 操作已完成。

error object

描述错误状态的逻辑错误模型。

metadata object

包含一个随机序列化消息以及一个 @type 描述序列化消信息类型的字符串。

path string

服务器分配的资源路径。默认格式为 operations/{operation_id}

response object

包含一个随机序列化消息以及一个 @type 描述序列化消信息类型的字符串。

Preview

资产预览。

属性

altText string

预览资产的替换素材。

asset string

预览资产路径。

素材的社交媒体链接。每个素材最多三个。对象名称可以是任何: > > > > > > > > > > > > > > > 对于语法,请参阅更新资产下的样本请求。

属性

title string

社交媒体关联接的可选标题。在创作者中心不使用。

uri string

社交媒体关联接的 URI。必须与关联接类型的期望格式匹配。例如,一个 twitchSocialLink 对象的标题必须为格式 https://twitch.tv/your-channel

State

资产是否激活或归档。未指定的不会被使用。

属性

string (enum): "Unspecified", "Active", "Archived"

Status

描述错误状态的逻辑错误模型。

属性

code number

HTTP 状态代验证码。

details array<object>

一个列表包含错误详情的消息。

message string

错误消信息。