> ## 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.

# Asset Management

> Use official Action requests and AK/SK signing for groups, assets and visual verification

## Try it

Choose an operation in [Actions](https://docs.tensorslab.com/api-reference/seedance/actions.md), then enter AK/SK and request fields. Signing is automatic; you can also copy cURL into Postman.

## Endpoint and authentication

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

Replace your asset client's URL, AK and SK with TensorAI connection details. Use platform-issued asset credentials; videos use an API key for the same account.

Use official HMAC-SHA256 (V4) signing, service `ark`, and default region `ap-southeast-1`:

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

Sign at least `content-type`, `host` and `x-date`, sorted by name. `X-Date` uses UTC `YYYYMMDDTHHMMSSZ`; clock skew must be within 15 minutes. If sent, `X-Content-Sha256` must match the body. The SDK below signs requests automatically.

## Supported Actions

All use POST and `Version=2024-01-01`; fields are case-sensitive. Every Action accepts optional `ProjectName`; omitted or empty means `default`, subject to credential permissions.

| Action | Request fields (\* required) | `Result` |
| - | - | - |
| `CreateAssetGroup` | `Name`\*, `Description`, `GroupType` (defaults to `AIGC`, the only supported value) | `Id` |
| `GetAssetGroup` | `Id`\* | `Id`, `Name`, `Description`, `GroupType`, `ProjectName`, etc. |
| `UpdateAssetGroup` | `Id`\*, `Name`, `Description` | `Id` |
| `DeleteAssetGroup` | `Id`\* | Empty object; deletes group and its assets |
| `CreateAsset` | `GroupId`*, `URL`*, `AssetType`\*, `Name`, `Moderation` | `Id` |
| `GetAsset` | `Id`\* | `Id`, `GroupId`, `Name`, `AssetType`, `Status`, `URL`, `ProjectName`, `Error`, etc. |
| `UpdateAsset` | `Id`\*, `Name` | `Id` |
| `DeleteAsset` | `Id`\* | Empty object; deletes specified asset |
| `CreateVisualValidateSession` | Optional `CallbackURL` | `H5Link`, `BytedToken` |
| `GetVisualValidateResult` | `BytedToken`\* | `Status: Pending` while incomplete; `GroupId` on completion |

`Name` allows 64 characters; `Description` allows 300. Omitted update fields retain their values; empty strings clear them. `AssetType` accepts `Image`, `Video`, `Audio`. `URL` must be publicly accessible over HTTP(S). `Moderation` accepts `{"Strategy":"Default"}` or `{"Strategy":"Skip"}`, subject to channel support. The request body limit is 1 MiB; submit a media URL rather than the media file.

## Official Python SDK example

Install the SDK and set `ASSET_AK` / `ASSET_SK` to platform-issued credentials. `ASSET_REGION` defaults to `ap-southeast-1`; update it if your connection details differ.

```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")
```

Replace the example URL with an accessible media URL and save `group_id` / `asset_id`. A returned ID means creation was accepted; wait for `Status=Active` before referencing the asset. `Processing` means it is being prepared; inspect `Error` on `Failed`. If polling times out, retain the ID and query it later.

## Reference assets in videos

Pass a reference in `content[]` when calling [Seedance 2.0](https://docs.tensorslab.com/api-reference/seedance/seedance-2-0.md) or [Seedance 2.5](https://docs.tensorslab.com/api-reference/seedance/seedance-2-5.md):

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

For audio and video, use `audio_url` / `video_url` with `reference_audio` / `reference_video`. The platform checks ownership, project, channel, media type and Active status. Use assets registered under your current account; media in one task must use compatible channels.

## Visual verification for real-person groups

Real-person groups require visual verification rather than `CreateAssetGroup`:

1. Call `CreateVisualValidateSession` to obtain `H5Link` / `BytedToken`.
2. Have the end user open `H5Link` on a camera-enabled device and complete verification.
3. Poll `GetVisualValidateResult` with `BytedToken`; continue while `Status=Pending`.
4. Use the resulting `GroupId` with `CreateAsset` to register real-person media.

`CallbackURL` may be omitted or empty; nonempty values must be absolute HTTPS URLs within 2048 characters. A provider may still require this field. Credentials need permission for both visual Actions. Keep session links and tokens private.

## Responses and errors

Success:

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

| HTTP | Common error codes | Next step |
| - | - | - |
| 400 | `InvalidActionOrVersion`, `InvalidVersion`, `MissingParameter`, `InvalidParameter` | Check Action, version, casing and required fields |
| 403 | `SignatureDoesNotMatch`, `RequestExpired`, `AccessDenied` | Check credentials, region, clock and Action/project permissions |
| 404 | `ResourceNotFound` | Check resource ID, account and project |
| 409 | `ResourceConflict` | Check state; provide RequestId to support |
| 429 / 5xx | See `ResponseMetadata.Error` | Retain RequestId; avoid blindly recreating resources if creation results are uncertain |


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