# 查询素材资产信息

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

`POST https://ark.cn-beijing.volcengineapi.com/?Action=GetAsset&Version=2024-01-01`

查询素材资产状态，确认素材是否已完成预处理并可用于推理。

> **注意**
>
> 当 GetAsset API 查询到上传失败资产时，接口可能仍返回 200，您需通过响应中的 *Status* = `Failed` 和 *Error.Code* / *Error.Message* 获取失败原因。

## 鉴权

本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](/docs/base-url-and-authentication)。

* Access Key 鉴权，请在 [Access Key 管理](https://console.volcengine.com/iam/keymanage) 页面，获取 Access Key。本接口仅支持 Access Key 鉴权。

---

<span id="request-parameters"></span>
## 请求参数

### Body 参数

**Id** `string` `必选` | 素材 ID

Asset（素材资产）的 Id。通过创建素材资产接口 (CreateAsset) 返回, 或通过 ListAssets 接口查询获取。

**ProjectName** `string` `默认值 default` | 所属项目

需要查询的 Asset（素材资产）所属的项目名称。若资源不在默认项目中，需填写正确的项目名称。

## 响应参数

**AssetType** `string` | 素材类型

Asset（素材资产）的类型。取值：`Image`；`Video`；`Audio`

**CreateTime** `string` | 创建时间

**Error** `object` | 错误信息

**Code** `string` | 错误码

`Error.Code`

错误码。

| Code | 错误原因 |
| --- | --- |
| FaceMismatch | 真人脸一致性校验失败，素材中的人脸与参考/授权人脸不一致。 |
| TranscodingFailed | 媒体转码或处理失败。 |
| ContentRestricted | 内容安全审核未通过。 |
| DownloadFailed | 无法下载客户提供的素材 URL。 |
| TypeMismatch | 上传素材类型与声明类型不一致，例如声明视频但实际是图片。 |
| FormatUnsupported | 素材格式不支持。 |
| FormatUndetectable | 无法识别素材格式，可能文件损坏或格式异常。 |
| AudioTrackRequired | 要求必须包含音轨，但素材中未检测到音轨。 |
| AudioTrackForbidden | 要求不能包含音轨，但素材中检测到音轨。 |
| DurationTooShort | 素材时长低于业务要求。 |
| DurationTooLong | 素材时长超过业务限制。 |
| WidthTooSmall / HeightTooSmall | 素材宽度或高度低于要求。 |
| WidthTooLarge / HeightTooLarge | 素材宽度或高度超过限制。 |
| AspectRatioTooSmall / AspectRatioTooLarge | 素材宽高比不符合要求。 |
| FileSizeTooLarge | 素材文件大小超过限制。 |
| PixelCountTooSmall / PixelCountTooLarge | 素材总像素数不符合要求。 |
| FpsTooLow / FpsTooHigh | 视频帧率不符合要求。 |
| InputTextSensitiveContentDetected | 文本内容安全审核未通过。 |
| InputImageSensitiveContentDetected | 图片内容安全审核未通过。 |
| InputVideoSensitiveContentDetected | 视频内容安全审核未通过。 |
| InputAudioSensitiveContentDetected | 音频内容安全审核未通过。 |
| InputTextSensitiveContentDetected.PolicyViolation | 文本涉及版权/政策限制。 |
| InputImageSensitiveContentDetected.PolicyViolation | 图片涉及版权/政策限制。 |
| InputVideoSensitiveContentDetected.PolicyViolation | 视频涉及版权/政策限制。 |
| InputAudioSensitiveContentDetected.PolicyViolation | 音频涉及版权/政策限制。 |
| ModerationServiceErrorUploadFailed | 审核服务暂不可用或审核上传失败，建议重新上传。 |
| InternalError | 素材处理过程中出现内部异常。 |

**Message** `string` | 错误信息

`Error.Message`

**GroupId** `string` | 所属素材组 ID

Asset（素材资产）所属的 Asset Group（素材资产组合）的 Id

**Id** `string` | 素材 ID

Asset（素材资产）的 Id

**LastInferenceTime** `string` | 最近推理时间

该素材最近一次被提交至视频生成任务的时间，采用 RFC 3339 格式（精确到秒，不含小数秒），例如 `2026-07-14T02:08:49Z` 或 `2026-07-14T10:08:49+08:00`。

该时间为任务提交时间，非任务处理时间。任务提交成功后，无论后续执行成功或失败，*LastInferenceTime* 都会更新。

对于新提交的任务，在使用 *GetAsset* 与 *ListAssets* 查询相关素材时，该字段更新可能存在 1–2 分钟延迟。若素材在 2026-07-24 之后未被任何任务调用，则不返回该字段。

**Moderation** `object` | 内容审核

内容审核相关信息

**Strategy** `string` | 审核策略

`Moderation.Strategy`

该素材的内容审核策略，该字段返回固定值 `Default`

**Name** `string` | 素材名称

Asset（素材资产）的名称，上限为 64 个字符

**ProjectName** `string` | 所属项目

资源所属的项目名称

**Status** `string` | 素材状态

素材资产状态。取值：
* `Active`：已处理完毕，可以使用；
* `Processing`：正在预处理，无法使用；
* `Failed`：处理失败

**UpdateTime** `string` | 更新时间

**URL** `string` | 访问地址

Asset（素材资产）的访问地址。有效期为 12 小时，请及时保存


## 代码示例

## 默认

### cURL

#### Request

```bash
curl 'https://ark.cn-beijing.volcengineapi.com/?Action=GetAsset&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H 'X-Date: <X-Date>' \
  -H 'X-Content-Sha256: <X-Content-Sha256>' \
  -H 'Authorization: HMAC-SHA256 Credential=<AK>/<X-Date>/cn-beijing/ark/request, SignedHeaders=content-type;host;x-content-sha256;x-date, Signature=<Signature>' \
  -d '{
    "Id": "asset-20240514212750-a3f8k",
    "ProjectName": "default"
}
'
```

#### Response

```
{
    "ResponseMetadata": {
        "RequestId": "20240514213000E5F6789ABCDEF01234",
        "Action": "GetAsset",
        "Version": "2024-01-01",
        "Service": "ark",
        "Region": "cn-beijing"
    },
    "Result": {
        "Id": "asset-20240514212750-a3f8k",
        "Name": "demo-portrait-image",
        "URL": "https://ark-asset.cn-beijing.volcengine.com/asset-20240514212750-a3f8k.jpg?X-Amz-Expires=43200",
        "AssetType": "Image",
        "GroupId": "group-20240514212750-b5e9m",
        "Status": "Active",
        "Moderation": {
            "Strategy": "Default"
        },
        "Error": {
            "Code": "",
            "Message": ""
        },
        "CreateTime": "2024-05-14T21:27:50Z",
        "UpdateTime": "2024-05-14T21:30:00Z",
        "LastInferenceTime": "2024-05-14T22:15:30Z",
        "ProjectName": "default"
    }
}
```