# 创建素材

URL: http://localhost:3000/docs/zh-cn/api/asset-library/CreateAsset

从公网 URL 异步入库一个素材。入库后需轮询 GetAsset 直到 Status 变为 Active。



从公网 URL 入库一个素材。本接口**异步**，只接受**公网可访问的 URL**（不支持文件直传 / Base64）；返回的 `Id` 初始为 `Processing`，需轮询 [GetAsset](/zh-cn/api/asset-library/GetAsset) 直到 `Active`。上传流程与素材限制见[素材库总览](/zh-cn/api/asset-library#上传素材的流程)。

<ArkOperation>
  <div>
    ## 请求参数 [#请求参数]

    | 参数            | 类型     | 必填 | 说明                                 |
    | ------------- | ------ | -- | ---------------------------------- |
    | `GroupId`     | string | 是  | 素材所属素材组的 Id                        |
    | `URL`         | string | 是  | 素材的公网可访问地址                         |
    | `AssetType`   | string | 是  | 素材类型，`Image` / `Video` / `Audio`   |
    | `Name`        | string | 否  | 素材名称，最多 64 个字符，仅用于 ListAssets 模糊搜索 |
    | `ProjectName` | string | 否  | 资源所属项目，默认 `default`，需与素材组一致        |

    ## 响应参数 [#响应参数]

    `Result` 结构：

    | 字段   | 类型     | 说明                                      |
    | ---- | ------ | --------------------------------------- |
    | `Id` | string | 新建素材的 Id（形如 `maas-…`），初始状态 `Processing` |

    ## 错误码 [#错误码]

    | Code                             | 说明                                         |
    | -------------------------------- | ------------------------------------------ |
    | `MissingParameter.GroupId`       | 未传 `GroupId`                               |
    | `MissingParameter.URL`           | 未传 `URL`                                   |
    | `MissingParameter.AssetType`     | 未传 `AssetType`                             |
    | `InvalidParameter.AssetType`     | `AssetType` 不是 `Image` / `Video` / `Audio` |
    | `AccessDenied`                   | 无该项目成员权限                                   |
    | `OperationDenied.ServiceNotOpen` | 租户未开通素材库能力                                 |

    入库后若处理失败，`GetAsset` 的 `Error.Code` 会给出原因（如 `DownloadFailed`、`FormatUnsupported`）。其余通用错误码见[素材库总览](/zh-cn/api/asset-library#错误码)。
  </div>

  <div>
    ## 在线调试 [#在线调试]

    <ArkTryIt method="POST" action="CreateAsset" body="{ GroupId: 'grp_0a1b2c3d4e5f', URL: 'https://cdn.example.com/portrait.png', AssetType: 'Image', Name: '示例素材', ProjectName: 'default' }" />

    ## 请求示例 [#请求示例]

    ```json
    {
      "GroupId": "grp_0a1b2c3d4e5f",
      "URL": "https://cdn.example.com/portrait.png",
      "AssetType": "Image",
      "Name": "示例素材",
      "ProjectName": "default"
    }
    ```

    ## 响应示例 [#响应示例]

    ```json
    {
      "ResponseMetadata": {
        "RequestId": "202603280000000000000000000000",
        "Action": "CreateAsset",
        "Version": "2024-01-01",
        "Service": "ark",
        "Region": "cn-beijing"
      },
      "Result": {
        "Id": "maas-abc123def456"
      }
    }
    ```
  </div>
</ArkOperation>

## 官方文档 [#官方文档]

[创建素材资产（CreateAsset）](https://docs.volcengine.com/docs/82379/2318271?lang=zh)