≡ All docs

Model API / Material Library

Material Library

Updated: 2026-08-21

Overview

The material library registers images, videos and audio with the platform so you can reference them from video generation as asset://<assetId> instead of re-uploading large files on every call. It has two levels: create an asset group first, then add assets to it.

Material library endpoints only require an API Key and do not consume quota.

Asset groups come in two types: aigc for regular or AI-generated material, and real_person for real-person material. Real-person material involves facial data and requires face consent plus a liveness check first — see Real-Person Assets below.

About external_user_id

Asset group and asset endpoints accept an optional external_user_id so you can separate material per end user inside your own account. The platform automatically prefixes the value with your account scope before storing it, so the ExternalUserId in responses is longer than what you sent; two different accounts never see each other's material even when they send the same value. Omit it to use your account's default namespace.

external_user_id accepts letters, digits, underscore, hyphen, dot and colon only, 1-64 characters; anything else returns 400. Always send the same value for the same end user, otherwise you will not find previously created material.

Asset Groups

Create an asset group

POST/asset-groups

Parameter	Type	Required	Description
name	string	Required	Asset group name
description	string	Optional	Asset group description
type	string	Optional	aigc (default) for regular / AI-generated material; real_person requires face consent and a liveness check first
external_user_id	string	Optional	End-user identifier used to separate material inside your account; omit to use the default namespace

curl -X POST "https://www.starunion.net/v1/asset-groups" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My AIGC material",
    "description": "Style references",
    "type": "aigc",
    "external_user_id": "user_12345"
  }'

JSON

{
  "Id": "group-20260526175953-z9nfc",
  "Name": "My AIGC material",
  "Description": "Style references",
  "GroupType": "aigc",
  "ExternalUserId": "bm-u1024-user_12345",
  "CreateTime": "2026-05-26T17:59:53Z"
}

List asset groups

GET/asset-groups

Accepts two optional query parameters, type (aigc / real_person) and external_user_id. Omitting external_user_id returns the groups in your account's default namespace.

cURL

curl "https://www.starunion.net/v1/asset-groups?type=aigc&external_user_id=user_12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "Result": {
    "Items": [
      {
        "Id": "group-20260526175953-z9nfc",
        "Name": "My AIGC material",
        "Description": "Style references",
        "GroupType": "aigc",
        "ExternalUserId": "bm-u1024-user_12345",
        "CreateTime": "2026-05-26T17:59:53Z"
      }
    ]
  }
}

Rename an asset group

PUT/asset-groups/{group_id}

cURL

curl -X PUT "https://www.starunion.net/v1/asset-groups/group-20260526175953-z9nfc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Renamed group",
    "external_user_id": "user_12345"
  }'

Delete an asset group

DELETE/asset-groups/{group_id}

Deleting a group also deletes every asset inside it. This cannot be undone.

cURL

curl -X DELETE "https://www.starunion.net/v1/asset-groups/group-20260526175953-z9nfc?external_user_id=user_12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

Assets

Add an asset

POST/assets

Parameter	Type	Required	Description
group_id	string	Required	Target asset group ID
url	string	Required	Asset location: a public HTTP/HTTPS link, a platform URL returned by the upload endpoint, or asset://<assetId> to reference an existing asset
asset_type	string	Optional	Asset type: Image (default) / Video / Audio
name	string	Optional	Asset name
external_user_id	string	Optional	End-user identifier; keep it consistent with the owning asset group

curl -X POST "https://www.starunion.net/v1/assets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "group-20260526175953-z9nfc",
    "url": "https://example.com/reference.jpg",
    "asset_type": "Image",
    "name": "Style reference",
    "external_user_id": "user_12345"
  }'

JSON

{
  "Id": "asset-20260528191439-8grtf",
  "Name": "Style reference",
  "URL": "https://cdn.starunion.net/assets/xxx.jpg",
  "AssetType": "Image",
  "GroupId": "group-20260526175953-z9nfc",
  "Status": "Active",
  "CreateTime": "2026-05-28T19:14:39Z"
}

Status Active means the asset is ready to use; Processing means the platform is still working on it, so check again shortly; Failed means the asset is unusable (for example the source URL could not be fetched).

List assets in a group

GET/assets

group_id is required. Returns every asset in the group with status Active or Failed.

cURL

curl "https://www.starunion.net/v1/assets?group_id=group-20260526175953-z9nfc&external_user_id=user_12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "Result": {
    "Items": [
      {
        "Id": "asset-20260528191439-8grtf",
        "Name": "Style reference",
        "URL": "https://cdn.starunion.net/assets/xxx.jpg",
        "AssetType": "Image",
        "GroupId": "group-20260526175953-z9nfc",
        "Status": "Active",
        "CreateTime": "2026-05-28T19:14:39Z"
      }
    ]
  }
}

Retrieve a single asset

GET/assets/{asset_id}

You can only read your own assets. An asset that does not belong to the current API Key (or to the external_user_id namespace you passed) returns 404.

cURL

curl "https://www.starunion.net/v1/assets/asset-20260528191439-8grtf?external_user_id=user_12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

Delete an asset

DELETE/assets/{asset_id}

cURL

curl -X DELETE "https://www.starunion.net/v1/assets/asset-20260528191439-8grtf?external_user_id=user_12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

Uploading Files

When a local file has no public URL, upload it first to get a platform URL, then pass that URL to the add-asset endpoint. Images, video and audio are supported, up to 200MB per file.

POST/material-files

cURL

curl -X POST "https://www.starunion.net/v1/material-files" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/reference.jpg"

JSON

{
  "url": "https://cdn.starunion.net/materials/reference.jpg"
}

Real-Person Assets

Real-person material involves facial data. Before integrating, make sure you have obtained separate consent from the end user for processing facial information, and keep the authorization record in your own product.

A real-person asset group takes three steps: submit face consent, create a liveness session for the user to scan, then poll for the resulting real-person group ID. Adding assets to that group afterwards works exactly like a regular group.

1. Check and submit face consent

GET/face-consent

cURL

curl "https://www.starunion.net/v1/face-consent" \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "valid": false,
  "need_versions": {
    "policy": "2026-04-17",
    "volc": "v1-2025-09-01"
  }
}

When valid is false, submit consent using the need_versions from the response. Always read the version numbers from the response rather than hard-coding them — hard-coded values are rejected once the versions change.

POST/face-consent

cURL

curl -X POST "https://www.starunion.net/v1/face-consent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "policy_version": "2026-04-17",
    "volc_rule_version": "v1-2025-09-01"
  }'

2. Create a liveness session

POST/asset-groups/validate-session

Returns a QR code and a BytedToken. Show QRCodeDataURL (a Base64 PNG) for the user to scan, or send them straight to H5Link to complete the liveness capture. callback_url is optional and must be allow-listed in advance.

cURL

curl -X POST "https://www.starunion.net/v1/asset-groups/validate-session" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "user_12345"
  }'

JSON

{
  "Result": {
    "BytedToken": "20260607000000000000000000000000",
    "QRCodeDataURL": "data:image/png;base64,...",
    "H5Link": "https://kyc.byteintl.com/..."
  }
}

3. Poll for the result

POST/asset-groups/validate-result

Poll with the BytedToken from the previous step, roughly every 3 seconds for up to 2 minutes. status active with a non-empty GroupId means the check passed, and that GroupId is the real-person asset group.

cURL

curl -X POST "https://www.starunion.net/v1/asset-groups/validate-result" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bytedToken": "20260607000000000000000000000000"
  }'

JSON

{
  "GroupId": "group-20260526180000-abcde",
  "status": "active"
}

Using Assets in Video

Once you have an asset ID, use asset://<assetId> as the URL inside the content array of a video generation request — no public URL needed.

cURL

curl -X POST "https://www.starunion.net/v1/video/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "prompt": "The person turns around and smiles, cinematic camera",
    "content": [
      {
        "type": "image_url",
        "image_url": { "url": "asset://asset-20260528191439-8grtf" }
      }
    ]
  }'

See the Video Generation page for parameters and polling; referencing an asset does not change how the other fields work.

Didn't find what you were looking for?Contact us →