素材组管理

1. 概述

本接口提供素材资产的完整生命周期管理，支持以下 10 个操作：

类别	Action	说明
素材组	`CreateAssetGroup`	创建素材分组
素材组	`ListAssetGroups`	列出当前用户所有素材组
素材组	`GetAssetGroup`	查询单个素材组详情
素材组	`UpdateAssetGroup`	修改素材组名称或描述
素材组	`DeleteAssetGroup`	删除素材组
素材	`CreateAsset`	上传素材（传入公网 URL）
素材	`ListAssets`	列出指定分组下的素材
素材	`GetAsset`	查询素材处理状态
素材	`UpdateAsset`	更新素材信息
素材	`DeleteAsset`	删除素材

数据隔离：接口按 access_token 标识用户，数据在用户维度严格隔离，不同用户无法访问彼此的素材组与素材。

2. 请求规范

Base URL

区域	Base URL
国内	`https://identity.xmsmartlink.com/api/asset-management`

请求格式

所有接口统一使用 POST 方法，通过 Action 查询参数指定操作：

POST {Base URL}?Action={ActionName}

请求头

Header	必填	说明
`X-Access-Token`	是	用户身份凭证
`Content-Type`	是	固定为 `application/json`
`X-Track-Id`	否	自定义链路追踪 ID；不传由服务端生成

注意事项

请求体中无需传 ProjectName，服务端会自动填充。
素材组名称 Name 请传业务原始名（无需添加任何前缀）。

3. 响应规范

成功响应（HTTP 200）

json

{
  "ResponseMetadata": {
    "Action": "CreateAsset",
    "Region": "cn-beijing",
    "RequestId": "20250101T120000XXXXXXXXXXXXXXXXXXXXXXXX",
    "Service": "ark",
    "Version": "2024-01-01"
  },
  "Result": {
    ...
  }
}

错误响应

场景	HTTP 状态码	响应体
参数错误、业务限制	400	`{"Code":"ErrorCode","Message":"描述","TrackId":"xxx"}`
无权限	403	`{"Code":"ErrorCode","Message":"描述","TrackId":"xxx"}`
请求过于频繁	429	`{"Code":"RateLimitExceeded","Message":"请求过于频繁","TrackId":"xxx"}`
上游服务异常	502	`{"Code":"VolcengineCallFailed","Message":"上游服务调用失败，请稍后重试","TrackId":"xxx"}`

4. 素材组接口

4.1 CreateAssetGroup – 创建素材组

创建一个新的素材分组，用于归类管理素材。

约束：

每个用户在同一部署环境下最多创建 100 个素材组（含系统默认组，可联系管理员调整上限）。
名称仅允许：中文、字母、数字、-、_，且不超过 50 个字符。

请求示例

bash

curl -X POST 'https://identity.xmsmartlink.com/api/asset-management?Action=CreateAssetGroup' \
  -H 'X-Access-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "Name": "广告素材组",
    "Description": "存放广告投放相关素材"
  }'

参数	类型	必填	说明
`Name`	string	是	素材组名称
`Description`	string	否	描述备注

成功响应

json

{
  "ResponseMetadata": {
    "Action": "CreateAssetGroup",
    "Region": "cn-beijing",
    "RequestId": "20250101T120000XXXXXXXXXXXXXXXXXXXXXXXX",
    "Service": "ark",
    "Version": "2024-01-01"
  },
  "Result": {
    "Id": "group-yyyymmddHHmmss-xxxxx",
    "Name": "广告素材组",
    "Description": "存放广告投放相关素材"
  }
}

错误码

Code	HTTP	说明
`MissingField`	400	`Name` 未提供
`InvalidGroupName`	400	名称包含非法字符或超长
`QuotaExceeded`	400	已达素材组数量上限

4.2 ListAssetGroups – 列出素材组

查询当前用户在本部署环境下的全部素材组（含系统默认组、业务方创建的组及真人授权组；不调用上游服务，直接从本地数据库返回）。

请求示例

bash

curl -X POST 'https://identity.xmsmartlink.com/api/asset-management?Action=ListAssetGroups' \
  -H 'X-Access-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'

请求体可省略、传空字符串或传 {}，均返回全部素材组。如需按类型筛选，可传 Filter.GroupType：

bash

curl -X POST 'https://identity.xmsmartlink.com/api/asset-management?Action=ListAssetGroups' \
  -H 'X-Access-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "Filter": {
      "GroupType": "AIGC"
    }
  }'

参数	类型	必填	说明
`Filter.GroupType`	string	否	按素材组类型过滤：`AIGC`（虚拟人像组）或 `LivenessFace`（真人授权组）；不传返回全部

成功响应

json

{
  "Result": {
    "AssetGroups": [
      {
        "Id": "group-yyyymmddHHmmss-xxxxx",
        "Name": "广告素材组",
        "Description": "存放广告投放相关素材",
        "GroupType": "AIGC",
        "CreateTime": "2025-01-01T12:00:00+08:00",
        "UpdateTime": "2025-01-01T12:00:00+08:00"
      },
      {
        "Id": "group-yyyymmddHHmmss-yyyyy",
        "Name": "张三",
        "Description": "品牌代言人真人素材组",
        "GroupType": "LivenessFace",
        "CreateTime": "2025-01-01T00:00:00+08:00",
        "UpdateTime": "2025-01-01T00:00:00+08:00"
      }
    ],
    "Total": 2
  }
}

响应字段	类型	说明
`Id`	string	素材组 ID
`Name`	string	业务方视角的组名（无前缀）
`Description`	string	描述备注
`GroupType`	string	素材组类型，见下表
`CreateTime`	string	创建时间（RFC3339）
`UpdateTime`	string	更新时间（RFC3339）

GroupType 取值说明：

GroupType	含义
`AIGC`	虚拟人像组（系统默认组、业务方通过 CreateAssetGroup 创建的组）
`LivenessFace`	真人授权组（H5 人脸核身授权流程创建，不可通过 CreateAssetGroup 创建）

4.3 GetAssetGroup – 查询素材组

查询指定素材组的详情。

请求示例

bash

curl -X POST 'https://identity.xmsmartlink.com/api/asset-management?Action=GetAssetGroup' \
  -H 'X-Access-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "Id": "<group_id>"
  }'

参数	类型	必填	说明
`Id`	string	是	素材组 ID

成功响应

json

{
  "ResponseMetadata": {
    "Action": "GetAssetGroup",
    "Region": "cn-beijing",
    "RequestId": "20250101T120000XXXXXXXXXXXXXXXXXXXXXXXX",
    "Service": "ark",
    "Version": "2024-01-01"
  },
  "Result": {
    "Id": "group-yyyymmddHHmmss-xxxxx",
    "Name": "广告素材组",
    "Description": "存放广告投放相关素材",
    "CreateTime": "2025-01-01T12:00:00Z",
    "UpdateTime": "2025-01-01T12:00:00Z"
  }
}

错误码

Code	HTTP	说明
`MissingField`	400	`Id` 未提供
`GroupNotOwned`	403	素材组不属于当前用户

4.4 UpdateAssetGroup – 更新素材组

修改素材组的名称或描述。

约束：

系统默认组（自动创建）的 Name 不可修改。
真人授权组（H5 授权流程创建）的 Name 不可修改。
Name 与 Description 可分别单独修改，仅传需要修改的字段即可。

请求示例

bash

curl -X POST 'https://identity.xmsmartlink.com/api/asset-management?Action=UpdateAssetGroup' \
  -H 'X-Access-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "Id": "<group_id>",
    "Name": "Q2广告素材组",
    "Description": "Q2 投放专用"
  }'

参数	类型	必填	说明
`Id`	string	是	素材组 ID
`Name`	string	否	新名称
`Description`	string	否	新描述

成功响应

json

{
  "ResponseMetadata": {
    "Action": "UpdateAssetGroup",
    "Region": "cn-beijing",
    "RequestId": "20250101T120000XXXXXXXXXXXXXXXXXXXXXXXX",
    "Service": "ark",
    "Version": "2024-01-01"
  },
  "Result": {}
}

错误码

Code	HTTP	说明
`MissingField`	400	`Id` 未提供
`InvalidGroupName`	400	新名称包含非法字符或超长
`DefaultGroupImmutable`	400	默认组禁止改名
`RealPersonGroupImmutable`	400	真人授权组禁止改名
`GroupNotOwned`	403	素材组不属于当前用户

4.5 DeleteAssetGroup – 删除素材组

删除指定素材组。

约束：

系统默认组不可删除。
组内存在素材时不可删除，需先删除组内所有素材。

请求示例

bash

curl -X POST 'https://identity.xmsmartlink.com/api/asset-management?Action=DeleteAssetGroup' \
  -H 'X-Access-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "Id": "<group_id>"
  }'

参数	类型	必填	说明
`Id`	string	是	素材组 ID

成功响应

json

{
  "ResponseMetadata": {
    "Action": "DeleteAssetGroup",
    "Region": "cn-beijing",
    "RequestId": "20250101T120000XXXXXXXXXXXXXXXXXXXXXXXX",
    "Service": "ark",
    "Version": "2024-01-01"
  },
  "Result": {}
}

错误码

Code	HTTP	说明
`MissingField`	400	`Id` 未提供
`DefaultGroupImmutable`	400	默认组禁止删除
`GroupNotEmpty`	400	组内仍有素材，请先删除
`GroupNotOwned`	403	素材组不属于当前用户

5. 素材接口

5.1 CreateAsset – 创建素材

上传一个素材到指定分组。需提供素材的公网可访问 URL，服务端不做二次下载或审核，由上游服务直接处理。

注意：CreateAsset 为异步操作。接口返回后素材处于处理中状态，需通过 GetAsset 轮询直至状态变为终态（Active / Failed）。

请求示例

bash

curl -X POST 'https://identity.xmsmartlink.com/api/asset-management?Action=CreateAsset' \
  -H 'X-Access-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "GroupId": "<group_id>",
    "URL": "https://example.com/photo.png",
    "AssetType": "Image",
    "Name": "产品主图"
  }'

参数	类型	必填	说明
`GroupId`	string	是	目标素材组 ID
`URL`	string	是	素材公网 URL，需可被上游服务直接访问
`AssetType`	string	是	素材类型：`Image` / `Video` / `Audio`（首字母大写，也接受全小写如 `image`）
`Name`	string	否	素材名称

成功响应

json

{
  "ResponseMetadata": {
    "Action": "CreateAsset",
    "Region": "cn-beijing",
    "RequestId": "20250101T120000XXXXXXXXXXXXXXXXXXXXXXXX",
    "Service": "ark",
    "Version": "2024-01-01"
  },
  "Result": {
    "Id": "asset-yyyymmddHHmmss-xxxxx"
  }
}

Result.Id 即素材 ID，保存此 ID 用于后续 GetAsset 查询。

错误码

Code	HTTP	说明
`MissingField`	400	`GroupId` 或 `URL` 未提供
`GroupNotOwned`	403	素材组不属于当前用户

5.2 ListAssets – 列出素材

查询指定素材组下的素材列表。

请求示例

bash

curl -X POST 'https://identity.xmsmartlink.com/api/asset-management?Action=ListAssets' \
  -H 'X-Access-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "Filter": {
      "GroupIds": ["<group_id>"]
    },
    "PageNumber": 1,
    "PageSize": 20
  }'

参数	类型	必填	说明
`Filter.GroupIds`	[]string	否	按素材组 ID 过滤；不传则查询当前用户全部素材
`PageNumber`	int	否	页码，默认 1
`PageSize`	int	否	每页条数，默认 20

成功响应

json

{
  "ResponseMetadata": {
    "Action": "ListAssets",
    "Region": "cn-beijing",
    "RequestId": "20250101T120000XXXXXXXXXXXXXXXXXXXXXXXX",
    "Service": "ark",
    "Version": "2024-01-01"
  },
  "Result": {
    "Assets": [
      {
        "Id": "asset-yyyymmddHHmmss-xxxxx",
        "Name": "产品主图",
        "AssetType": "Image",
        "GroupId": "group-yyyymmddHHmmss-xxxxx",
        "Status": "Active",
        "URL": "https://cdn.example.com/assets/photo.png",
        "CreateTime": "2025-01-01T12:00:00Z",
        "UpdateTime": "2025-01-01T12:00:02Z"
      }
    ],
    "Total": 1
  }
}

若传入的 GroupIds 中包含不属于当前用户的组，服务端会自动过滤，仅返回当前用户有权限的分组数据。

5.3 GetAsset – 查询素材状态

查询素材的处理状态，通常用于 CreateAsset 后轮询直至素材进入终态。

素材状态说明

Status	含义	是否终态
`Pending`	处理中	否，需继续轮询
`Active`	处理成功，可正常使用	是
`Failed`	处理失败	是
`Deleted`	已删除	是

请求示例

bash

curl -X POST 'https://identity.xmsmartlink.com/api/asset-management?Action=GetAsset' \
  -H 'X-Access-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "Id": "<asset_id>"
  }'

参数	类型	必填	说明
`Id`	string	是	素材 ID（`CreateAsset` 返回的 `Result.Id`）

成功响应

json

{
  "ResponseMetadata": {
    "Action": "GetAsset",
    "Region": "cn-beijing",
    "RequestId": "20250101T120000XXXXXXXXXXXXXXXXXXXXXXXX",
    "Service": "ark",
    "Version": "2024-01-01"
  },
  "Result": {
    "Id": "asset-yyyymmddHHmmss-xxxxx",
    "Name": "产品主图",
    "AssetType": "Image",
    "GroupId": "group-yyyymmddHHmmss-xxxxx",
    "Status": "Active",
    "URL": "https://cdn.example.com/assets/photo.png?signature=...",
    "CreateTime": "2025-01-01T12:00:00Z",
    "UpdateTime": "2025-01-01T12:00:02Z"
  }
}

Result.URL 为带时效签名的访问地址，有效期约 12 小时。素材进入 Active 状态后建议通过定期调用 GetAsset 刷新 URL。

轮询建议

建议轮询间隔 ≥ 500ms，单 access_token 限速 10 次/秒，超过返回 429。
素材通常在 5–30 秒内进入终态，如超过 5 分钟仍为 Pending，请联系技术支持。

错误码

Code	HTTP	说明
`MissingField`	400	`Id` 未提供
`AssetNotOwned`	403	素材不属于当前用户
`RateLimitExceeded`	429	请求过于频繁，请降低轮询频率

5.4 UpdateAsset – 更新素材

更新素材的名称等信息。

请求示例

bash

curl -X POST 'https://identity.xmsmartlink.com/api/asset-management?Action=UpdateAsset' \
  -H 'X-Access-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "Id": "<asset_id>",
    "Name": "产品主图-最终版"
  }'

参数	类型	必填	说明
`Id`	string	是	素材 ID
`Name`	string	否	新名称

成功响应

json

{
  "ResponseMetadata": {
    "Action": "UpdateAsset",
    "Region": "cn-beijing",
    "RequestId": "20250101T120000XXXXXXXXXXXXXXXXXXXXXXXX",
    "Service": "ark",
    "Version": "2024-01-01"
  },
  "Result": {}
}

错误码

Code	HTTP	说明
`MissingField`	400	`Id` 未提供
`AssetNotOwned`	403	素材不属于当前用户

5.5 DeleteAsset – 删除素材

删除指定素材。

请求示例

bash

curl -X POST 'https://identity.xmsmartlink.com/api/asset-management?Action=DeleteAsset' \
  -H 'X-Access-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "Id": "<asset_id>"
  }'

参数	类型	必填	说明
`Id`	string	是	素材 ID

成功响应

json

{
  "ResponseMetadata": {
    "Action": "DeleteAsset",
    "Region": "cn-beijing",
    "RequestId": "20250101T120000XXXXXXXXXXXXXXXXXXXXXXXX",
    "Service": "ark",
    "Version": "2024-01-01"
  },
  "Result": {}
}

错误码

Code	HTTP	说明
`MissingField`	400	`Id` 未提供
`AssetNotOwned`	403	素材不属于当前用户

6. 错误码参考

Code	HTTP	说明
`UnsupportedAction`	400	Action 不存在或为空
`MissingField`	400	必填参数缺失或请求体格式错误
`InvalidGroupName`	400	素材组名称包含非法字符或超过长度限制
`DefaultGroupImmutable`	400	系统默认素材组不可删除或改名
`RealPersonGroupImmutable`	400	真人授权素材组不可改名
`GroupNotEmpty`	400	素材组内仍有素材，无法删除
`QuotaExceeded`	400	素材组数量已达上限
`GroupNotOwned`	403	素材组不属于当前用户
`AssetNotOwned`	403	素材不属于当前用户
`RateLimitExceeded`	429	GetAsset 请求频率超限（> 10次/秒）
`VolcengineCallFailed`	502	上游服务调用失败，请稍后重试

7. 附录：典型调用流程

完整的素材上传与使用流程

1. 创建素材组（一次性）
   POST ?Action=CreateAssetGroup
   → 获得 GroupId

2. 上传素材
   POST ?Action=CreateAsset  { GroupId, URL, AssetType }
   → 获得 AssetId（素材处于 Pending 状态）

3. 轮询素材状态（间隔 ≥ 500ms）
   POST ?Action=GetAsset  { Id: AssetId }
   → Result.Status == "Active" 时表示处理完成

4. 使用素材
   → Result.URL 为可访问的素材地址（有效期约 12 小时）
   → 需要刷新时重新调用 GetAsset 获取最新 URL

5. 素材管理（可选）
   - 更新名称：POST ?Action=UpdateAsset
   - 查看列表：POST ?Action=ListAssets
   - 删除素材：POST ?Action=DeleteAsset

代码示例（Python）

python

import time
import requests

HOST = "https://identity.xmsmartlink.com"
TOKEN = "YOUR_TOKEN"
HEADERS = {"X-Access-Token": TOKEN, "Content-Type": "application/json"}

def call(action, body):
    r = requests.post(f"{HOST}/api/asset-management?Action={action}", json=body, headers=HEADERS)
    r.raise_for_status()
    return r.json()

# 1. 创建素材组
group = call("CreateAssetGroup", {"Name": "我的素材组"})
group_id = group["Result"]["Id"]
print(f"素材组 ID：{group_id}")

# 2. 上传素材
asset = call("CreateAsset", {
    "GroupId": group_id,
    "URL": "https://example.com/photo.png",
    "AssetType": "Image",
    "Name": "示例图片"
})
asset_id = asset["Result"]["Id"]
print(f"素材 ID：{asset_id}")

# 3. 轮询状态
for _ in range(60):
    time.sleep(1)
    result = call("GetAsset", {"Id": asset_id})
    status = result["Result"]["Status"]
    print(f"状态：{status}")
    if status in ("Active", "Failed", "Deleted"):
        break

# 4. 获取最终 URL
if status == "Active":
    url = result["Result"]["URL"]
    print(f"素材 URL：{url}")

API Reference

查看素材组与素材管理底层接口定义

素材组管理 ​

1. 概述 ​

2. 请求规范 ​

Base URL ​

请求格式 ​

请求头 ​

注意事项 ​

3. 响应规范 ​

成功响应（HTTP 200） ​

错误响应 ​

4. 素材组接口 ​

4.1 CreateAssetGroup – 创建素材组 ​

4.2 ListAssetGroups – 列出素材组 ​

4.3 GetAssetGroup – 查询素材组 ​

4.4 UpdateAssetGroup – 更新素材组 ​

4.5 DeleteAssetGroup – 删除素材组 ​

5. 素材接口 ​

5.1 CreateAsset – 创建素材 ​

5.2 ListAssets – 列出素材 ​

5.3 GetAsset – 查询素材状态 ​

5.4 UpdateAsset – 更新素材 ​

5.5 DeleteAsset – 删除素材 ​

6. 错误码参考 ​

7. 附录：典型调用流程 ​

完整的素材上传与使用流程 ​

代码示例（Python） ​

API Reference ​

素材组管理

1. 概述

2. 请求规范

Base URL

请求格式

请求头

注意事项

3. 响应规范

成功响应（HTTP 200）

错误响应

4. 素材组接口

4.1 CreateAssetGroup – 创建素材组

4.2 ListAssetGroups – 列出素材组

4.3 GetAssetGroup – 查询素材组

4.4 UpdateAssetGroup – 更新素材组

4.5 DeleteAssetGroup – 删除素材组

5. 素材接口

5.1 CreateAsset – 创建素材

5.2 ListAssets – 列出素材

5.3 GetAsset – 查询素材状态

5.4 UpdateAsset – 更新素材

5.5 DeleteAsset – 删除素材

6. 错误码参考

7. 附录：典型调用流程

完整的素材上传与使用流程

代码示例（Python）

API Reference