资产使用指南

Open Cloud 的资产 API 允许您使用单个 HTTP 请求上传和更新资产，而不是手动导入到 Studio。该 API 支持：

正在上传新资产。
使用版本控制更新现有资产。
更新资产元数据，包括描述、显示名称、图标和预览。
管理资产版本，例如退回到指定的以前版本。
检查素材的现有信息，包括元数据、版本和任何正在进行的更新操作。

该 API 包含可能在未来版本中进行更改的测试端点。

支持的资产类型和限制

对于不创建新资产或不更新现有资产内容的终端，没有限制和限制。然而，由创建资产和更新资产端点驱动的资产内容上传功能仅支持有限类型的资产，带有限制。对于每个调用，您只能创建或更新一个资产，文件大小不超过 20MB，具有以下限制：

使用更新资产端点更新资产元数据不受以下限制。

资产类输入	格式	内容类输入	限制
音频	.mp3 .ogg	audio/mpeg audio/ogg	长达 7 分钟的时长。: 如果您已验证身份，每月最多可上传 100 个文件。: 如果您未通过身份验证，每月最多可上传 10 个文件。: 不适用于更新。
图标	.png .jpeg .bmp .tga	image/png image/jpeg image/bmp image/tga	不适用于更新。必须小于 8000x8000 像素。
模型	.fbx	model/fbx	根据您的使用案例，考虑手动上传某些模型，使用 3D 导入器。: 3D导入器提供 3D预览、各种错误检查和许多可定制的导入设置。
视频	.mp4 .mov	video/mp4 video/mov	长达 60 秒的时间。: 最高分辨率为 4096x2160。: 最多 750 MB。: 目前，只允许英语、西班牙语、葡萄牙语、印度尼西亚语、中文（简体和传统）、日语和/或韩语的音频和文本。: 如果你是 13+ 且经过身份验证，每月最多可上传 10 个文件。

安全权限

API支持第一方使用与API密钥授权和第三方使用在OAuth 2应用程序中。每种方式都需要不同的安全权限设置。

API 钥匙

要在自己的脚本或工具中使用 API，您需要创建 API 密钥进行授权和安全。要管理您个人拥有的资产，请在帐户下创建 API 钥匙。要管理集团拥有的资产，在目标群组下创建 API 钥匙。了解有关群拥有API钥匙的更多信息，请参阅群拥有API钥匙权限。

一旦您创建了 API 钥键，您无法在个人或组之间切换其所有权，因此如果您在自己的帐户下创建 API 钥匙，则无法用于管理群组资产。

要创建群组的 API 钥匙或创建群组素材，您必须拥有相应的权限。了解有关授予群组权限的更多信息，请参阅群组角色和权限。

无论您是为自己还是为群组创建 API 钥匙，请务必添加以下权限：

将资产添加到访问权限。
向您选择的体验添加阅读和写入操作权限，取决于您计划调用的端点所需的范围。

一旦你拥有 API 钥键，将其复制到 x-api-key 请求头。所有端点都需要 x-api-key 请求头。

Example API Request Header
--header 'x-api-key: ${ApiKey}' \

OAuth 2.0 应用

要使用 API 为第三方 OAuth 2.0 应用程序，在 asset:read 时添加 asset:write 和权限范围。根据您计划使用的终端的需求选择这些范围。

创建一个新素材

通过 HTTP 请求上传新资产：

复制 API 钥匙到创建资产端点的请求头。

在您的请求中：

指定目标资产类型。
添加您的资产名称和描述。
添加创建者信息。
- 如果您想在自己的名义下创建资产 **** ，请添加您的用户 ID。您可以在 Roblox 个人资料的 URL 上找到您的用户 ID。例如，对于 https://www.roblox.com/users/1234567/profile , 您的用户ID是 1234567 .
- 如果您想将资产创建为群组资产，请添加您组的群组 ID。您可以在群组页面的 URL 上找到群组 ID。例如，对于 https://www.roblox.com/groups/7654321/example-group#!/ , 群组 ID 是 7654321 .
添加您资产的文件路径和内容类型。

Example Request for Create Asset
curl --location '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}\" # 使用 groupId 创建群组素材
    }
  }
}"' \
--form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

更新现有素材

资产更新由可能在未来版本中进行更改的测试端点驱动。

通过 HTTP 请求更新现有资产：

复制 API 钥匙到更新资产端点的请求头。
在请求中添加资产类型和资产 ID。要复制您的资产 ID：
1. 导航到创建页面的创建者仪表板。
2. 选择开发项目类别。
3. 选择资产类别并找到目标素材。
4. 将鼠标悬停在目标资产的缩略图上，然后单击 ⋯ 按钮显示选项列表，然后从列表中选择复制资产ID 。

目前，你只能为 .fbx 文件更新资产内容。更新会创建新版本。

Example Request for Updating Asset Content
curl --location --request PATCH 'https://apis.roblox.com/assets/v1/assets/{assetId}' \
--header 'x-api-key: {apiKey}' \
--form 'request={
    \"assetType\": \"{assetType}\",
    \"assetId\": \"{assetId}\",
    \"creationContext\": {
        \"creator\": {
            \"userId\": {userId}
        },
        \"expectedPrice\":{expectedPrice}
    },
}' \
--form 'fileContent=@"{file-path}"'

检索资产操作状态

如果您创建新资产或更新现有资产的请求成功，它将返回一个操作ID 在 { "path": "operations/${operationId}" } 格式中。您可以使用它来检查上传的状态和结果，以下步骤：

复制 API 钥匙到 x-api-key 获取操作方法的请求头并发送请求，如下代码示例：

Example Request for Get Operation
curl --location 'https://apis.roblox.com/assets/v1/operations/{operationId}' \
--header 'x-api-key: {$ApiKey}'

如果您的请求成功，它将返回一个对象，其中包含代表上传的资产信息的或解释为什么资产上传失败的代码示例如下所示：

Example Response for Get Operation
{
  "path": "operations/{operationId}",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/roblox.open_cloud.assets.v1.Asset",
    "path": "assets/2205400862",
    "revisionId": "1",
    "revisionCreateTime": "2023-03-02T22:27:04.062164400Z",
    "assetId": "2205400862",
    "displayName": "Name",
    "description": "This is a description",
    "assetType": "ASSET_TYPE_DECAL",
    "creationContext": {
      "creator": {
        "userId": "11112938575"
      }
    },
    "moderationResult": {
      "moderationState": "MODERATION_STATE_APPROVED"
    }
  }
}

(可选) 检查您的 Roblox 帐户上创建的资产。
1. 导航到您的 Roblox 帐户的库存页面。
2. 选择您想要检查的资产的类别。
3. 找到目标资产，然后单击其缩略图查看素材。

将资产 API 添加到 OAuth 2.0 应用

您可以创建 OAuth 2.0 应用程序支持资产 API，以允许用户将资产上传到 Roblox 并更新资产。

通过 OAuth 2.0 支持第三方应用是一个可能在未来版本中进行更改的 Beta 功能。

要使用资产 API 为应用程序提供服务并向用户请求权限，请执行以下设置：

当注册您的应用时，在权限下，选择素材：阅读和素材：写入范围。

当实现授权流程时，包括 asset:read 和 asset:write 作为转向用户返回到您应用程序的授权 URL 的范围参数，如以下示例：


https://authorize.roblox.com?client_id=819547628404595165403873012&redirect_uri=https://my-app.com/redirect&scope=asset:read+asset:write&response_type=Code&prompts=login+consent&nonce=12345&state=6789

发送请求时，包括访问代币在授权头中和资产内容的表单数据在请求 URI 中创建或更新。以下示例显示了上传新素材的样本请求：

示例请求
curl --location --request POST 'https://apis.roblox.com/assets/v1/assets' \

--header 'Authorization: Bearer <access_token>' \

--header 'Content-Type: application/json' \

--form 'request="{

  \"assetType\": \"Decal\",

  \"displayName\": \"DecalDemo123\",

  \"description\": \"This is a description\",

  \"creationContext\": {

    \"creator\": {

    \"userId\": \"<user_id>\"

    }
  }

}"' \

--form 'fileContent=@"/filepath/p1.png"'

在此页面