Skip to content

Seedance 2.0 - Asset Library (Digital Human Asset Management APIs)

These APIs provide asset container creation (real-person and virtual), file upload, listing, status sync (polling), update, and deletion capabilities for digital-human video generation workflows.

0. Authentication & Conventions

  • Auth: Authorization: Bearer {new-api-token}
  • Content-Type: application/json unless stated otherwise
  • Common response:
  • success: boolean
  • message: string (may be empty)
  • data: object | null

1. Concepts

1.1 Asset Container (Group)

A container holds a collection of asset files (image/video/audio, etc.).

  • group_type
  • 1: Real-person avatar (LivenessFace) — created via face verification flow
  • 2: Virtual avatar (AIGC) — create container directly then upload assets

1.2 Asset File (Asset)

An asset file is a leaf node under a container. After upload, status is typically Processing(0); you should poll until it becomes Active(1) or Failed(2).

2. Data Model

2.1 UserAssetResponse

Unified response object for both containers and assets (key fields):

  • id: resource_id
  • asset_type:
  • 0: Unknown
  • 1: Container
  • 2: Video
  • 3: Image
  • 4: Audio
  • group_type: container type (0/1/2)
  • name / description
  • status:
  • 0: Processing
  • 1: Active
  • 2: Failed (see fail_reason)
  • is_leaf:
  • 0: Container
  • 1: Asset file
  • created_at / updated_at: Unix timestamp (seconds)

3. Real-person Avatar (GroupType=1 / LivenessFace)

3.1 Create face verification session

  • POST /v1/asset/human/session
  • Purpose: creates a verification session and returns a URL to open the verification page. After completion, the user is redirected to redirect_url with result parameters:
  • Success: status=success&group_id={groupId}
  • Failure: status=failed&reason={reason}

Request body

Required: redirect_url

{
  "name": "Real-person avatar of Zhang San",
  "description": "For digital human video generation",
  "redirect_url": "https://your-app.com/asset/callback-result"
}

Response example

{
  "success": true,
  "data": {
    "Url": "https://xxx.volccdn.com/verify?token=xxx",
    "H5Link": "https://xxx.volccdn.com/verify?token=xxx",
    "BytedToken": "byted_token_abc123"
  }
}

4. Virtual Avatar (GroupType=2 / AIGC)

4.1 Create virtual avatar container

  • POST /v1/asset/human/aigc
  • Purpose: creates a container and returns GroupId. Upload assets to this container via /v1/asset/human/upload.

Request body

Required: name

{
  "name": "Virtual host A",
  "description": "AIGC assets for live commerce"
}

Response example

{
  "success": true,
  "data": {
    "GroupId": "group_abc123"
  }
}

5. Common APIs (list / status sync / update / delete)

5.1 Upload an asset file

  • POST /v1/asset/human/upload
  • Purpose: upload a file (image/video/audio) into a container.
  • Notes:
  • After upload, status becomes Processing(0); poll until Active(1) or Failed(2)
  • group_id must belong to the current token’s user

Request body

Required: group_id, url, asset_type

asset_type enum: - Image - Video - TrainingVideo - Script - Audio

{
  "group_id": "group_abc123",
  "url": "https://cdn.example.com/video/demo.mp4",
  "asset_type": "Video",
  "name": "Demo video",
  "description": "For digital human video generation"
}

Response example

data is a UserAssetResponse (initial status is typically Processing).

{
  "success": true,
  "message": "",
  "data": {
    "id": "asset_xyz789",
    "asset_type": 2,
    "group_type": 1,
    "name": "Demo video",
    "description": "For digital human video generation",
    "status": 0,
    "fail_reason": "",
    "is_leaf": 1,
    "created_at": 1714000000,
    "updated_at": 1714000000
  }
}

5.2 List assets

  • GET /v1/asset/human/list
  • Purpose: list assets for the current user; optionally filter by group_id.
  • Query params:
  • group_id (optional)
  • is_leaf (optional): 1 assets (default), 0 containers
  • p (optional): page number (default 1)
  • page_size (optional): page size (default 20)

Request example

curl "https://api.agtcloud.ai/v1/asset/human/list?group_id=group_abc123&is_leaf=1&p=1&page_size=20" \
  -H "Authorization: Bearer $API_KEY"

Response example

{
  "success": true,
  "data": {
    "total": 5,
    "items": [
      {
        "id": "asset_xyz789",
        "asset_type": 2,
        "group_type": 1,
        "name": "Demo video",
        "description": "For digital human video generation",
        "status": 1,
        "fail_reason": "",
        "is_leaf": 1,
        "created_at": 1714000000,
        "updated_at": 1714001000
      }
    ]
  }
}

5.3 Sync asset status (polling)

  • GET /v1/asset/human/get/{id}
  • Purpose: query and refresh the latest status for a single asset (useful for polling after upload).
  • Path param:
  • id: asset resource_id (the id field in responses)

Request example

curl "https://api.agtcloud.ai/v1/asset/human/get/asset_xyz789" \
  -H "Authorization: Bearer $API_KEY"

5.4 Update asset metadata

  • PUT /v1/asset/human/update/{id}
  • Purpose: update name and/or description.

Request body example

{
  "name": "Updated demo video",
  "description": "New description"
}

5.5 Delete an asset or container

  • DELETE /v1/asset/human/delete/{id}
  • Purpose: delete an asset file or a container.
  • Behavior (based on the target resource’s is_leaf):
  • is_leaf=0 (container): deletes the container and all child assets
  • is_leaf=1 (asset file): deletes a single asset

Request example

curl -X DELETE "https://api.agtcloud.ai/v1/asset/human/delete/group_abc123" \
  -H "Authorization: Bearer $API_KEY"