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

# Asset Library — Quick Start

The Asset Library allows you to upload images, videos, and audio files to the PowerTokens platform and obtain a permanent `asset_id`. You can then directly reference this `asset_id` in any generation request without needing to pass the original file URL each time.

The Asset Library is divided into three types of assets for different scenarios:

| Type                   | Description                                                      | Who Can Use                                       |
| ---------------------- | ---------------------------------------------------------------- | ------------------------------------------------- |
| **Official Assets**    | Official assets provided by ByteDance, preloaded on the platform | Authorized customers only                         |
| **Virtual Assets**     | User-created asset libraries with free upload and management     | All users                                         |
| **Real Person Assets** | Assets that require real-person verification before uploading    | Users who have completed real-person verification |

***

## Prerequisites

Before calling any Asset Library API, complete the following steps:

1. **Sign up / Log in**: Register and log in at [powertokens.ai](https://powertokens.ai)
2. **Get an API Key**: Go to the [API Keys management page](https://powertokens.ai/api-keys), click to create a new key, copy and store it securely (it will not be visible again after closing the page)
3. **Enable Asset Library**: Go to the [Asset Library page](https://powertokens.ai/zh-Hans/assets-library?tab=1), read and agree to the Asset Library User Agreement before using

> **Note:** Using the Asset Library **does not require a top-up** — it's free to use once enabled. However, if you need to call generation models like Seedance 2.0, you will need to top up first.

### Authentication

All endpoints are authenticated via HTTP headers in the following format:

```
Authorization: <YOUR_API_KEY>
```

Every request must include this header (except for the Get Asset ID endpoint), otherwise a 401 Unauthorized error will be returned.

***

## Supported File Types

| Type      | Format                                | Limits                                                  |
| --------- | ------------------------------------- | ------------------------------------------------------- |
| **Image** | JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC | \< 30 MB, aspect ratio 0.4–2.5, single side 300–6000 px |
| **Video** | MP4, MOV                              | 480p or 720p, duration 2–15 seconds, ≤ 50 MB, 24–60 fps |
| **Audio** | WAV, MP3                              | Duration 2–15 seconds, ≤ 15 MB                          |

***

## 1. Official Assets

Official Assets are provided by ByteDance and include high-quality assets preloaded on the platform. Official assets belong to the virtual asset type (`group_type: 0`), but are **only visible to authorized customers** — ordinary users will not see official asset groups when calling the API.

### Workflow

```
Get asset group list ──→ Find official asset group ──→ Get asset list under that group ──→ Use asset_id
```

### 1.1 Get Official Asset Groups

**Endpoint:** [`POST /v1/asset/groups/list`](https://docs.powertokens.ai/en/assetLibrary/group-list)

```bash theme={null}
curl -X POST https://powertokens.ai/api/v1/asset/groups/list \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "page_size": 20,
    "group_type": 0
  }'
```

> Official asset groups share `group_type: 0` with user-created virtual asset groups. If you are not an authorized customer, the returned list will not include official asset groups.

### 1.2 Get Asset List Under a Group

After obtaining an official `group_id`, query all assets under that group:

**Endpoint:** [`POST /v1/asset/groups/assets`](https://docs.powertokens.ai/en/assetLibrary/group-asset-list)

```bash theme={null}
curl -X POST https://powertokens.ai/api/v1/asset/groups/assets \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "page_size": 12,
    "group_id": "XXXX"
  }'
```

Each asset in the response includes an `asset_id`, which can be used directly in generation requests.

Supported filter parameters:

| Parameter  | Type    | Description                                             |
| ---------- | ------- | ------------------------------------------------------- |
| `type`     | integer | Filter by type: 1=Image, 2=Video, 3=Audio               |
| `status`   | integer | Filter by status: 1=Under review, 2=Succeeded, 3=Failed |
| `name`     | string  | Fuzzy search by name                                    |
| `asset_id` | string  | Exact search by asset ID                                |

***

## 2. Virtual Assets

Virtual Assets are user-created asset libraries where you can freely create asset groups, upload files, and manage assets.

### Workflow

```
Create asset group ──→ Upload file (specify group_id) ──→ Get task_id ──→ Poll to get asset_id ──→ Use
```

### 2.1 Create a Virtual Asset Group

**Endpoint:** [`POST /v1/asset/groups/create`](https://docs.powertokens.ai/en/assetLibrary/group-create)

```bash theme={null}
curl -X POST https://powertokens.ai/api/v1/asset/groups/create \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "group_name": "My Project Assets"
  }'
```

**Response:**

```json theme={null}
{
  "code": 200,
  "data": {
    "group_id": "XXXX"
  },
  "msg": ""
}
```

### 2.2 Upload a File to an Asset Group

**Endpoint:** [`POST /v1/asset/upload`](https://docs.powertokens.ai/en/assetLibrary/upload-file)
**Content-Type:** `multipart/form-data`

```bash theme={null}
curl -X POST https://powertokens.ai/api/v1/asset/upload \
  -H "Authorization: YOUR_API_KEY" \
  -F "file=@/path/to/your-image.jpg" \
  -F "group_id=XXXX"
```

> You can also omit `group_id` and pass `group_name` instead — the system will automatically create or reuse a virtual group with the same name.

**Response:**

```json theme={null}
{
  "code": 200,
  "data": {
    "task_id": "XXXX"
  },
  "msg": ""
}
```

### 2.3 Get Asset ID

Uploading is asynchronous. Use the returned `task_id` to poll and obtain a permanent `asset_id`:

**Endpoint:** [`GET /v1/asset/jobs/get-asset-id?task_id=<TASK_ID>`](https://docs.powertokens.ai/en/assetLibrary/get-asset-id)

> **Note:** This endpoint **does not require authentication** — no `Authorization` header is needed.

```bash theme={null}
curl "https://powertokens.ai/api/v1/asset/jobs/get-asset-id?task_id=XXXX"
```

**Response:**

```json theme={null}
{
  "code": 200,
  "data": {
    "asset_id": "XXXX"
  },
  "msg": ""
}
```

> **Tip:** If the file is still processing, it's recommended to poll every 2–3 seconds until an `asset_id` is returned. Small images usually complete within seconds; videos may take longer.

### 2.4 Manage Asset Groups

**List virtual asset groups:**

```bash theme={null}
curl -X POST https://powertokens.ai/api/v1/asset/groups/list \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "page_size": 20,
    "group_type": 0
  }'
```

**Rename an asset group:** [`POST /v1/asset/groups/rename`](https://docs.powertokens.ai/en/assetLibrary/group-rename)

```bash theme={null}
curl -X POST https://powertokens.ai/api/v1/asset/groups/rename \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "XXXX",
    "group_name": "New Name"
  }'
```

**Delete an asset group:** [`POST /v1/asset/groups/delete`](https://docs.powertokens.ai/en/assetLibrary/group-delete)

```bash theme={null}
curl -X POST https://powertokens.ai/api/v1/asset/groups/delete \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "XXXX"
  }'
```

***

## 3. Real Person Assets

Real Person Assets require completing real-person verification first. Only after successful verification can you upload assets of that real person. This ensures compliance and authorization for asset usage.

### Workflow

```
Get authorization URL ──→ Complete real-person verification ──→ Obtain asset group ID ──→ Upload real person assets to that group ──→ Get asset_id ──→ Use
```

### 3.1 Get Real-Person Authorization URL

**Endpoint:** [`POST /v1/asset/get-authorize-url`](https://docs.powertokens.ai/en/assetLibrary/get-authorize-url)

```bash theme={null}
curl -X POST https://powertokens.ai/api/v1/asset/get-authorize-url \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

**Response:**

```json theme={null}
{
  "code": 200,
  "data": "https://baze.powerbuyin.top/auth/real-human-authorization?uuid=9eff6f20-87c0-4f04-a158-30c145126eee",
  "msg": ""
}
```

### 3.2 Complete Real-Person Verification

Open the returned authorization URL in a browser and follow the on-screen instructions to complete identity verification. Once verified, the system will automatically create a real-person asset group.

### 3.3 Query Real-Person Asset Group to Get group\_id

After successful verification, use the Asset Group List endpoint (the same endpoint used in [1. Official Assets](#1-official-assets)) to query your real-person asset group and obtain the `group_id`:

```bash theme={null}
curl -X POST https://powertokens.ai/api/v1/asset/groups/list \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "page_size": 20,
    "group_type": 1,
    "real_human_type": 2
  }'
```

`group_type` and `real_human_type` parameter descriptions:

| Parameter         | Value | Description                                                             |
| ----------------- | ----- | ----------------------------------------------------------------------- |
| `group_type`      | `0`   | Virtual asset group (default); official assets also belong to this type |
| `group_type`      | `1`   | Real person asset group                                                 |
| `real_human_type` | `1`   | Real-person group created by yourself                                   |
| `real_human_type` | `2`   | Real-person group obtained through verification authorization           |

Find your real-person asset group from the response `list` and take its `group_id` for the next upload step.

### 3.4 Upload Real Person Assets

After obtaining the real-person asset group's `group_id`, upload that real person's assets:

```bash theme={null}
curl -X POST https://powertokens.ai/api/v1/asset/upload \
  -H "Authorization: YOUR_API_KEY" \
  -F "file=@/path/to/real-person-video.mp4" \
  -F "group_id=XXXX"
```

Subsequent steps (obtaining `asset_id`, using it in generation) are the same as Virtual Assets — see step 3 in Section 2.

***

## Using in Generation Requests

Once you have an `asset_id` (regardless of the asset type), you can reference it in any generation request that supports media input:

```bash theme={null}
curl -X POST https://powertokens.ai/api/v1/videos \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan-2.1-video",
    "prompt": "A cherry blossom avenue in spring, petals drifting in the wind",
    "images": ["XXXX"]
  }'
```

### Using in Playground

In the Playground interface, uploaded assets appear in the Asset Library panel. Type **`@`** in the prompt input area to browse and insert assets. The interface automatically adapts based on the selected model:

* **Reference image models** (e.g., `wan2.7-r2v`): freely `@` any number of reference images in the prompt
* **Keyframe models** (e.g., `wan2.1-kf2v`): displays two fixed slots — **Start Frame** and **End Frame** — each slot accepts one `@` image

***

## Complete Workflow — Python

Below is a complete example from creating a virtual asset group to generation:

```python theme={null}
import requests
import time

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://powertokens.ai/api"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


# ── Create Virtual Asset Group ─────────────────────────────
def create_group(group_name):
    resp = requests.post(
        f"{BASE_URL}/v1/asset/groups/create",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"group_name": group_name},
    )
    resp.raise_for_status()
    return resp.json()["data"]["group_id"]


# ── Upload File ────────────────────────────────────────────
def upload_asset(file_path, group_id):
    with open(file_path, "rb") as f:
        files = {"file": (file_path.split("/")[-1], f)}
        data = {"group_id": group_id}
        resp = requests.post(
            f"{BASE_URL}/v1/asset/upload",
            headers=HEADERS,
            files=files,
            data=data,
        )
    resp.raise_for_status()
    return resp.json()["data"]["task_id"]


# ── Poll to Get asset_id (no auth required) ──────────────────
def get_asset_id(task_id, timeout=60, interval=3):
    start = time.time()
    while time.time() - start < timeout:
        resp = requests.get(
            f"{BASE_URL}/v1/asset/jobs/get-asset-id",
            params={"task_id": task_id},
        )
        data = resp.json()
        if data["code"] == 200 and data["data"].get("asset_id"):
            return data["data"]["asset_id"]
        time.sleep(interval)
    raise TimeoutError(f"Asset processing did not complete within {timeout} seconds")


# ── List Assets in Group ─────────────────────────────────────
def list_group_assets(group_id, page=1, page_size=12):
    resp = requests.post(
        f"{BASE_URL}/v1/asset/groups/assets",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"page": page, "page_size": page_size, "group_id": group_id},
    )
    resp.raise_for_status()
    return resp.json()["data"]


# ── Use in Generation Request ────────────────────────────────
def generate_video(asset_id, prompt):
    resp = requests.post(
        f"{BASE_URL}/v1/videos",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={
            "model": "wan-2.1-video",
            "prompt": prompt,
            "images": [asset_id],
        },
    )
    resp.raise_for_status()
    return resp.json()


# ── Run ─────────────────────────────────────────────────
group_id = create_group("demo-project")
print(f"Asset group created → group_id: {group_id}")

task_id = upload_asset("start_frame.jpg", group_id)
print(f"Uploaded → task_id: {task_id}")

asset_id = get_asset_id(task_id)
print(f"Processing complete → asset_id: {asset_id}")

assets = list_group_assets(group_id)
print(f"Total assets in group: {assets['total']}")

result = generate_video(asset_id, "Cyberpunk-style Tokyo nightscape")
print(f"Generation task submitted → task_id: {result['data']['task_id']}")
```

***

## API Quick Reference

> **Base URL:** `https://powertokens.ai/api` — ensure all requests include the `/api` prefix; do not concatenate directly to `powertokens.ai/v1/...`.

### Asset Operations

#### Upload File — `POST /v1/asset/upload` ([API Reference](https://docs.powertokens.ai/en/assetLibrary/upload-file))

```bash theme={null}
curl -X POST https://powertokens.ai/api/v1/asset/upload \
  -H "Authorization: YOUR_API_KEY" \
  -F "file=@/path/to/file.jpg" \
  -F "group_id=XXXX"
```

#### Get Asset ID — `GET /v1/asset/jobs/get-asset-id` ([API Reference](https://docs.powertokens.ai/en/assetLibrary/get-asset-id))

> This endpoint **does not require authentication**.

```bash theme={null}
curl "https://powertokens.ai/api/v1/asset/jobs/get-asset-id?task_id=XXXX"
```

#### Get Real-Person Authorization URL — `POST /v1/asset/get-authorize-url` ([API Reference](https://docs.powertokens.ai/en/assetLibrary/get-authorize-url))

```bash theme={null}
curl -X POST https://powertokens.ai/api/v1/asset/get-authorize-url \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

### Asset Group Management

#### Create Virtual Asset Group — `POST /v1/asset/groups/create` ([API Reference](https://docs.powertokens.ai/en/assetLibrary/group-create))

```bash theme={null}
curl -X POST https://powertokens.ai/api/v1/asset/groups/create \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group_name": "My Project Assets"}'
```

#### List Asset Groups — `POST /v1/asset/groups/list` ([API Reference](https://docs.powertokens.ai/en/assetLibrary/group-list))

```bash theme={null}
curl -X POST https://powertokens.ai/api/v1/asset/groups/list \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page": 1, "page_size": 20, "group_type": 0}'
```

#### List Assets in Group — `POST /v1/asset/groups/assets` ([API Reference](https://docs.powertokens.ai/en/assetLibrary/group-asset-list))

```bash theme={null}
curl -X POST https://powertokens.ai/api/v1/asset/groups/assets \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page": 1, "page_size": 12, "group_id": "XXXX"}'
```

#### Rename Asset Group — `POST /v1/asset/groups/rename` ([API Reference](https://docs.powertokens.ai/en/assetLibrary/group-rename))

```bash theme={null}
curl -X POST https://powertokens.ai/api/v1/asset/groups/rename \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group_id": "XXXX", "group_name": "New Name"}'
```

#### Delete Asset Group — `POST /v1/asset/groups/delete` ([API Reference](https://docs.powertokens.ai/en/assetLibrary/group-delete))

```bash theme={null}
curl -X POST https://powertokens.ai/api/v1/asset/groups/delete \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group_id": "XXXX"}'
```

***

*For the complete API reference, visit [docs.powertokens.ai](https://docs.powertokens.ai)*