资产 API

*此内容使用人工智能(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 密钥】(/cloud/open-cloud/managing-api-keys)。

  • 读取

若要使用此端点,你的 OAuth 2.0 应用程序需要以下范围。关于如何注册 OAuth 2.0 应用程序的更多信息,请查看【应用程序注册及评价】(/cloud/open-cloud/app-registration)。

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

  • 读取
  • 写入

若要使用此端点,你的 OAuth 2.0 应用程序需要以下范围。关于如何注册 OAuth 2.0 应用程序的更多信息,请查看【应用程序注册及评价】(/cloud/open-cloud/app-registration)。

  • asset:read
  • asset:write

限制

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

获取资产

GET /v1/assets

恢复特定资产内容和数据。

参数

assetId

素材的唯一标识。

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

答复

必要权限

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

  • 读取

若要使用此端点,你的 OAuth 2.0 应用程序需要以下范围。关于如何注册 OAuth 2.0 应用程序的更多信息,请查看【应用程序注册及评价】(/cloud/open-cloud/app-registration)。

  • 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。请参阅内容类型

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

  • 读取
  • 写入

若要使用此端点,你的 OAuth 2.0 应用程序需要以下范围。关于如何注册 OAuth 2.0 应用程序的更多信息,请查看【应用程序注册及评价】(/cloud/open-cloud/app-registration)。

  • asset:read
  • asset:write

限制

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

更新资产

PATCH /v1/assets/{assetId}

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

参数

request

发送作为以下示例请求的形式数据。

FormData
必填
fileContent string

二进制资源文件路径和内容输入。格式:fileContent=@"/filepath/{File}";type={ContentType}。示例:fileContent=@"/filepath/model.fbx";type=model/fbx。请参阅内容类型

FormData
updateMask string

资产描述、显示名称、图标志和预览更新。示例:description%2CdisplayNamepreviews%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\": [\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 密钥】(/cloud/open-cloud/managing-api-keys)。

  • 读取
  • 写入

若要使用此端点,你的 OAuth 2.0 应用程序需要以下范围。关于如何注册 OAuth 2.0 应用程序的更多信息,请查看【应用程序注册及评价】(/cloud/open-cloud/app-registration)。

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

  • 读取

若要使用此端点,你的 OAuth 2.0 应用程序需要以下范围。关于如何注册 OAuth 2.0 应用程序的更多信息,请查看【应用程序注册及评价】(/cloud/open-cloud/app-registration)。

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

  • 读取

若要使用此端点,你的 OAuth 2.0 应用程序需要以下范围。关于如何注册 OAuth 2.0 应用程序的更多信息,请查看【应用程序注册及评价】(/cloud/open-cloud/app-registration)。

  • asset:read

限制

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

对象

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

Any

包含一个任意串化消息以及一个 @type 描述串化消信息类型的内部机制。

属性

@type string

串行消信息的类型。

Asset

代表一个资素材。

属性

assetId number

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

assetType string

资源类输入。只能是 AudioDecalModel 。需要用于 2>创建资产2> 。

creationContext object

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

description string

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

displayName string

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

icon string

标志的资源路径。

moderationResult object

素材的审核结果。

path string

资产的返回资源路径。格式:assets/{assetId}。示例:assets/2205400862

previews array<object>

一个列表预览,每个列表都有一个资产路径和 alt 文本。预览必须是 图像 资产。

revisionCreateTime string

当前版本的创建时间戳。

revisionId string

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

socialLink object

社交媒体链接素材。最多三个素材。对象名称可以是: facebookS

CreationContext

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

属性

creator object

代表一个创建创作者。

必填
expectedPrice number

在 Robux 中期待资产上传费。 当实际价格超过预期时,操作会发生 400 错误。

Creator

代表一个创建创作者。

属性

groupId number

Group ID。 如果资产是群组拥有的,则需要。

userId number

创建创作者的用户ID。 如果资产是单独的用户拥有的,则需要。

ModerationResult

素材的审核结果。

属性

moderationState string

素材的审核状态。可以 MODERATION_STATE_REVIEWINGMODERATION_STATE_REJECTEDMODERATION_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

预览资源路径。

社交媒体链接素材。最多三个素材。对象名称可以是: facebookS

属性

title string

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

uri string

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

Status

说明错误状态的逻辑错误模型。

属性

code number

HTTP状态代验证码。

details array<object>

带有错误详细信息的列表。

message string

错误消信息。