> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensorslab.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 资产管理

> 使用官方 Action 协议和 AK/SK 签名管理资产组、资产及真人活体校验

## 在线调用

在 [Actions](https://docs.tensorslab.com/zh/api-reference/seedance/actions.md) 中选择操作，填写 AK/SK 和请求参数即可调用。签名自动生成，也可复制 cURL 到 Postman。

## 请求地址与鉴权

```text theme={null}
POST https://api.tensorslab.com/v1/video/?Action=<ACTION>&Version=2024-01-01
Content-Type: application/json
```

替换现有客户端的资产管理 URL、AK、SK，即可沿用官方 Action 调用方式。使用 TensorAI 签发的资产管理凭据；视频生成使用同一账号的 API Key。

签名采用官方 HMAC-SHA256（V4），服务名 `ark`，默认签名地域 `ap-southeast-1`：

```text theme={null}
HMAC-SHA256 Credential=<AK>/<YYYYMMDD>/<REGION>/ark/request, SignedHeaders=content-type;host;x-date, Signature=<SIGNATURE>
```

至少签入 `content-type`、`host`、`x-date`，按名称排序。`X-Date` 为 UTC `YYYYMMDDTHHMMSSZ`，与服务端时差不超过 15 分钟。若发送 `X-Content-Sha256`，须匹配实际请求体。建议使用下方 SDK 自动签名。

## 支持的 Action

均使用 POST，`Version=2024-01-01`，字段区分大小写。所有 Action 均接受可选 `ProjectName`；省略或空字符串为 `default`，须在凭据授权范围内。

| Action | 请求参数（\* 为必填） | `Result` |
| - | - | - |
| `CreateAssetGroup` | `Name`\*、`Description`、`GroupType`（默认且仅支持 `AIGC`） | `Id` |
| `GetAssetGroup` | `Id`\* | `Id`、`Name`、`Description`、`GroupType`、`ProjectName` 等 |
| `UpdateAssetGroup` | `Id`\*、`Name`、`Description` | `Id` |
| `DeleteAssetGroup` | `Id`\* | 空对象；删除组及组内资产 |
| `CreateAsset` | `GroupId`*、`URL`*、`AssetType`\*、`Name`、`Moderation` | `Id` |
| `GetAsset` | `Id`\* | `Id`、`GroupId`、`Name`、`AssetType`、`Status`、`URL`、`ProjectName`、`Error` 等 |
| `UpdateAsset` | `Id`\*、`Name` | `Id` |
| `DeleteAsset` | `Id`\* | 空对象；仅删除指定资产 |
| `CreateVisualValidateSession` | 可选 `CallbackURL` | `H5Link`、`BytedToken` |
| `GetVisualValidateResult` | `BytedToken`\* | 未完成时 `Status: Pending`；完成后返回 `GroupId` |

`Name` 最多 64 字符，`Description` 最多 300 字符。更新字段未传时保持原值，显式空字符串表示置空。`AssetType` 支持 `Image`、`Video`、`Audio`，`URL` 为可公开访问的 HTTP(S) 地址。`Moderation` 格式为 `{"Strategy":"Default"}` 或 `{"Strategy":"Skip"}`，具体能力取决于实际通道。请求体上限 1 MiB，传递素材 URL，无需在此上传媒体文件。

## 官方 Python SDK 示例

安装依赖，并设置 `ASSET_AK`、`ASSET_SK` 为平台签发的资产凭据。`ASSET_REGION` 默认 `ap-southeast-1`，如接入信息不同则同步调整。

```bash theme={null}
pip install volcengine
```

```python theme={null}
import json
import os
import time
from urllib.parse import urlsplit
from volcengine.ApiInfo import ApiInfo
from volcengine.Credentials import Credentials
from volcengine.ServiceInfo import ServiceInfo
from volcengine.base.Service import Service

endpoint = urlsplit("https://api.tensorslab.com/v1/video/")
region = os.getenv("ASSET_REGION", "ap-southeast-1")
actions = [
    "CreateAssetGroup", "GetAssetGroup", "UpdateAssetGroup", "DeleteAssetGroup",
    "CreateAsset", "GetAsset", "UpdateAsset", "DeleteAsset",
    "CreateVisualValidateSession", "GetVisualValidateResult",
]
sdk = Service(
    ServiceInfo(endpoint.netloc, {}, Credentials("", "", "ark", region),
                10, 60, scheme=endpoint.scheme),
    {action: ApiInfo("POST", endpoint.path, {
        "Action": action, "Version": "2024-01-01"
    }, {}, {}) for action in actions},
)
sdk.set_ak(os.environ["ASSET_AK"])
sdk.set_sk(os.environ["ASSET_SK"])

def call(action, body):
    response = json.loads(sdk.json(action, {}, json.dumps(body)))
    if response["ResponseMetadata"].get("Error"):
        raise RuntimeError(response["ResponseMetadata"]["Error"])
    return response["Result"]

group_id = call("CreateAssetGroup", {
    "Name": "Reference library", "GroupType": "AIGC", "ProjectName": "default"
})["Id"]
asset_id = call("CreateAsset", {
    "GroupId": group_id, "URL": "https://example.com/reference.png",
    "AssetType": "Image", "Name": "Reference image"
})["Id"]
# Save both IDs; replace the URL above with your accessible media URL.
for _ in range(120):
    asset = call("GetAsset", {"Id": asset_id})
    if asset["Status"] == "Active":
        print("asset://" + asset_id)
        break
    if asset["Status"] == "Failed":
        raise RuntimeError(asset.get("Error", asset))
    time.sleep(3)
else:
    raise TimeoutError("Asset is not ready; retain its ID and query again later")
```

请把示例 URL 替换为真实素材地址，并保存 `group_id`、`asset_id`。创建返回 ID 仅代表受理，需等待 `Status=Active` 后再引用。`Processing` 表示处理中；`Failed` 时查看 `Error`。轮询超时后仍可继续查询同一 ID。

## 视频中引用资产

在 [Seedance 2.0](https://docs.tensorslab.com/zh/api-reference/seedance/seedance-2-0.md) 或 [Seedance 2.5](https://docs.tensorslab.com/zh/api-reference/seedance/seedance-2-5.md) 的 `content[]` 中传入：

```json theme={null}
{"type":"image_url","image_url":{"url":"asset://<ASSET_ID>"},"role":"reference_image"}
```

音频、视频分别使用 `audio_url` / `video_url` 和 `reference_audio` / `reference_video`。平台校验用户归属、项目、通道、媒体类型和 Active 状态。请使用当前账号创建的资产，同一任务引用的素材须在兼容通道中。

## 真人活体校验

真人素材组不能直接通过 `CreateAssetGroup` 创建：

1. 调用 `CreateVisualValidateSession` 获取 `H5Link`、`BytedToken`。
2. 终端用户在可使用摄像头的设备上打开 `H5Link` 完成校验。
3. 使用 `BytedToken` 调用 `GetVisualValidateResult`，`Status=Pending` 时继续轮询。
4. 取得 `GroupId` 后调用 `CreateAsset` 登记真人素材。

`CallbackURL` 可省略或为空；非空时须为不超过 2048 字符的 HTTPS 绝对 URL，上游仍可能要求必填。凭据需具备对应活体 Action 权限。请妥善保管会话链接和 Token。

## 返回与错误

成功示例：

```json theme={null}
{"ResponseMetadata":{"RequestId":"request-example","Action":"CreateAsset","Version":"2024-01-01","Service":"ark","Region":"ap-southeast-1"},"Result":{"Id":"asset-example"}}
```

| HTTP | 常见错误码 | 处理方式 |
| - | - | - |
| 400 | `InvalidActionOrVersion`、`InvalidVersion`、`MissingParameter`、`InvalidParameter` | 检查 Action、版本、大小写和必填字段 |
| 403 | `SignatureDoesNotMatch`、`RequestExpired`、`AccessDenied` | 检查凭据、签名地域、时间与 Action / 项目权限 |
| 404 | `ResourceNotFound` | 检查当前账号的资源 ID 与项目 |
| 409 | `ResourceConflict` | 核对资源状态，保留 RequestId 联系支持 |
| 429 / 5xx | 以 `ResponseMetadata.Error` 为准 | 保留 RequestId 排查；创建结果不明确时避免直接重复创建 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.