# 查询素材

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

按 Id 查询单个素材，确认其 Status 与产物 URL。素材失败时以 Status=Failed + Error 返回，HTTP 仍为 200。



按 Id 查询单个素材，用于确认处理状态。素材处理失败时以 `Status=Failed` + `Error` 返回，HTTP 仍为 200；只有读取本身失败（不存在 / 跨项目）才是 HTTP 错误。返回的 `URL` 有效期 12 小时。接入信息与鉴权见[素材库总览](/zh-cn/api/asset-library)。

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

    | 参数            | 类型     | 必填 | 说明                  |
    | ------------- | ------ | -- | ------------------- |
    | `Id`          | string | 是  | 素材 Id               |
    | `ProjectName` | string | 否  | 资源所属项目，默认 `default` |

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

    `Result` 结构：

    | 字段                    | 类型     | 说明                                 |
    | --------------------- | ------ | ---------------------------------- |
    | `Id`                  | string | 素材 Id                              |
    | `Name`                | string | 名称                                 |
    | `URL`                 | string | 重新托管的签名下载地址，有效期 12 小时              |
    | `GroupId`             | string | 所属素材组 Id                           |
    | `AssetType`           | string | `Image` / `Video` / `Audio`        |
    | `Status`              | string | `Active` / `Processing` / `Failed` |
    | `Moderation.Strategy` | string | 内容审核策略，固定为 `Default`               |
    | `Error.Code`          | string | 失败错误码，仅 `Status=Failed` 时非空        |
    | `Error.Message`       | string | 失败描述，仅 `Status=Failed` 时非空         |
    | `ProjectName`         | string | 所属项目                               |
    | `CreateTime`          | string | 创建时间，ISO8601 UTC                   |
    | `UpdateTime`          | string | 更新时间，ISO8601 UTC                   |

    `Status=Failed` 时的 `Error.Code` 常见取值：`DownloadFailed`（URL 无法下载）、`TypeMismatch`（内容类型与 `AssetType` 不符）、`FormatUnsupported`（格式不支持）、`FileSizeTooLarge`（超出大小上限）。

    ## 错误码 [#错误码]

    | Code                       | 说明                               |
    | -------------------------- | -------------------------------- |
    | `MissingParameter.AssetID` | 未传 `Id`（该接口的缺参错误码参数名为 `AssetID`） |
    | `NotFound`                 | 素材不存在或无权访问                       |
    | `AccessDenied`             | 无该项目成员权限                         |

    其余通用错误码见[素材库总览](/zh-cn/api/asset-library#错误码)。
  </div>

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

    <ArkTryIt method="POST" action="GetAsset" body="{ Id: 'maas-abc123def456', ProjectName: 'default' }" />

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

    ```json
    {
      "Id": "maas-abc123def456",
      "ProjectName": "default"
    }
    ```

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

    ```json
    {
      "ResponseMetadata": {
        "RequestId": "202603280000000000000000000000",
        "Action": "GetAsset",
        "Version": "2024-01-01",
        "Service": "ark",
        "Region": "cn-beijing"
      },
      "Result": {
        "Id": "maas-abc123def456",
        "Name": "示例素材",
        "URL": "https://maas-ark.stringx.top/assets/abc123?sign=…",
        "GroupId": "grp_0a1b2c3d4e5f",
        "AssetType": "Image",
        "Status": "Active",
        "Moderation": { "Strategy": "Default" },
        "Error": { "Code": "", "Message": "" },
        "ProjectName": "default",
        "CreateTime": "2026-03-28T00:00:00Z",
        "UpdateTime": "2026-03-28T00:00:00Z"
      }
    }
    ```
  </div>
</ArkOperation>

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

[查询素材资产信息（GetAsset）](https://docs.volcengine.com/docs/82379/2318274?lang=zh)