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
2. Get an API Key: Go to the API Keys management page, 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, 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

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

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

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:

{
  "code": 200,
  "data": {
    "group_id": "XXXX"
  },
  "msg": ""
}

2.2 Upload a File to an Asset Group

Endpoint: POST /v1/asset/upload Content-Type: multipart/form-data

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:

{
  "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>

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

curl "https://powertokens.ai/api/v1/asset/jobs/get-asset-id?task_id=XXXX"

Response:

{
  "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:

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

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

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

curl -X POST https://powertokens.ai/api/v1/asset/get-authorize-url \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "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) to query your real-person asset group and obtain the group_id:

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:

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:

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:

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)

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)

This endpoint does not require authentication.

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)

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)

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)

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)

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)

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)

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