TokenLab Seedance Materials: Reusable Video References for Production Workflows

Reusable video references are easier to manage when they are assets with lifecycle status, not one-off URLs copied into every generation request. If you have ever maintained a spreadsheet of image links, re-uploaded the same reference video five times, or re-typed a face-swap URL into three different API calls, you already understand the problem Seedance materials are built to solve.

TokenLab's Seedance material library gives video teams an organization-scoped way to store, verify, and reuse references across generation calls. This article explains what a material asset actually is, how material groups relate to individual assets, how automatic preparation works, and where real-person verification fits into the workflow.

Key Takeaways

What a Seedance Material Is

A Seedance material is a reusable reference — image, video, or audio — that TokenLab stores as an organization-scoped asset rather than a request-scoped URL. Instead of passing a raw file link into every create-video call, you upload or import the reference once, wait for it to become generation-ready, and then reference it by ID in as many subsequent calls as you need.

This matters for three practical reasons.

First, repeated uploads waste bandwidth and add latency to every request, especially for large reference videos.

Second, raw URLs expire, get rotated, or get revoked by whatever storage system originally hosted them. A material asset that TokenLab manages does not have that fragility.

Third, and most relevant for teams building character-consistent or brand-consistent video pipelines, materials give you a stable identifier you can version, audit, and swap without touching your generation logic each time.

Material Assets vs. Material Groups

The two core objects in this system are the material asset and the material asset group, and it's easy to conflate them if you have not read the API reference closely.

A material asset is a single reference object — one avatar image, one liveness-verified face, one reference video clip. When you create it, the API returns an id. That id is what you eventually pass into video generation calls once the asset reaches ACTIVE status.

A material asset group is a container identified by group_id. Groups organize related assets together, and they are structurally required for real-person (liveness_face) workflows, where verification happens at the group level before individual assets can be uploaded into it.

In short: group_id organizes; material_asset_id generates. You will see both fields in different parts of the API, and using the wrong one in the wrong place is the most common integration mistake teams make with this system.

Field	What it identifies	Where you use it
group_id	A material asset group (container)	Creating or referencing a group, especially for real-person verification flows
id (on a material asset)	A single reusable reference	Becomes material_asset_id once ACTIVE
material_asset_id	A single asset reference, singular	Passed into create-video for one reference slot
material_asset_ids	An array of asset references	Passed into create-video when multiple reusable references are needed

Full field definitions and required parameters are documented at the create material asset and create material asset group API references. Read those before wiring this into production code — this article covers the workflow shape, not every request parameter.

Virtual-Avatar and Real-Person Workflows

Seedance materials support two library types, and the distinction is not cosmetic — it reflects two different safety and consent postures.

aigc_avatar: Virtual Avatars and Non-Real-Person References

The aigc_avatar type covers reusable references that are not tied to a verified real person: illustrated characters, synthetic avatars, stylized figures, product mascots, and similar assets. These can be created directly through the material asset creation flow without a verification step.

If your product generates videos around fictional characters or brand avatars, this is almost certainly the library type you want. It has a simpler creation path because there is no identity-verification requirement attached to it.

liveness_face: Real-Person Material Groups

The liveness_face type is for material groups built around a real person's likeness — the kind of reference used for face-consistent video generation featuring an actual individual. Because this touches identity and consent, TokenLab requires a verification flow before assets can be uploaded into the group.

The verification sequence has several distinct steps:

1. Session creation — your backend requests a verification session for the group.
2. H5 flow — the person being verified completes a liveness check through a hosted web flow (this is what "H5" refers to: a mobile-web verification interface).
3. Callback — TokenLab notifies your system when the verification session concludes.
4. Bind result — the verified identity is bound to the material group.
5. Group-scoped uploads — only after binding succeeds can material assets be uploaded into that specific group.

This means real-person materials are inherently group-first: you cannot skip straight to creating an asset the way you can with aigc_avatar. The group has to exist and pass verification before any asset upload into it is valid.

Checklist: Choosing the Right Library Type

• Is the reference a real, identifiable person's face or likeness? → Use liveness_face and plan for the verification flow.
• Is the reference synthetic, illustrated, or a non-real-person avatar? → Use aigc_avatar and skip verification.
• Does your product need consistent identity across multiple generations for the same real person? → Build the group once, verify once, reuse the group for future assets.
• Are you unsure which type a given customer-supplied reference falls into? → Treat it as liveness_face until confirmed otherwise; verify in docs, do not assume.

Do not assume every generation model or every request type supports both library types identically — confirm current support in the Seedance 2.0 Video Models guide before committing to an architecture.

How Automatic Material Preparation Works

Not every reference needs a manual upload step. TokenLab can automatically prepare compatible image inputs into material assets as part of a generation request, which removes a round trip for simple cases.

The fields it recognizes for automatic preparation are:

• image
• image_url
• image_urls
• reference_images
• start_image
• end_image

If you pass any of these directly into a generation call, TokenLab handles the import and preparation behind the scenes rather than requiring you to call the material asset endpoint separately first.

What Happens When Preparation Takes Longer Than 60 Seconds

Preparation is usually fast, but larger or more complex reference images can take longer to process into a generation-ready asset. If preparation exceeds 60 seconds, the API responds with:

409 seedance_material_preparing

along with an auto_material_asset_ids field containing the IDs of the assets still being prepared.

This is not an error in the conventional sense — it is a signal to retry. Your integration should treat 409 seedance_material_preparing as a "check back shortly" response, not a failure to surface to the end user. Poll the returned asset IDs, wait for ACTIVE status, and then proceed with generation using those IDs.

Practically, this means your generation pipeline needs a small retry loop, not just a single try/catch. Teams building automated video pipelines should treat this status the same way they'd treat rate-limit backoff — expected, transient, and handled in code rather than reported as a user-facing error.

How to Use Materials in Generation

Once a material asset — whether manually uploaded or automatically prepared — reaches ACTIVE status, its id becomes usable as material_asset_id (or as an entry in material_asset_ids) in a create video call.

The core workflow looks like this:

1. Decide whether the reference is real-person or not. Choose liveness_face (with verification) or aigc_avatar accordingly.
2. If real-person: create the material group, run the verification session and H5 flow, receive the callback, and bind the result.
3. Create or import the material asset — either through a direct upload call, or by letting automatic preparation handle a compatible image field inside a generation request.
4. Check status. Do not pass the asset ID into generation until it reports ACTIVE.
5. If you get 409 seedance_material_preparing, poll the returned auto_material_asset_ids and retry once they resolve to ACTIVE.
6. Use the id as material_asset_id or within material_asset_ids in your create-video call, targeting a current Seedance model such as seedance-2.0, seedance-2.0-fast, or seedance-2.0-mini depending on your latency and quality needs.
7. Reuse the same asset ID across future generation calls instead of re-uploading the reference.

This is also where task management matters. If a generation call built on a reused material asset needs to be stopped mid-run — for cost control, a changed creative brief, or a bad prompt — see our companion piece on Seedance task cancellation for how cancellation interacts with in-flight video jobs.

For a broader comparison of what's currently available across video generation models on TokenLab, the video models category page lists current options side by side.

Practical Next Steps

• If you are prototyping, start with aigc_avatar materials — the creation path is simpler and there's no verification dependency to build around first.
• If your product requires real-person consistency, build the verification flow (session → H5 → callback → bind) as a first-class part of your onboarding, not a bolt-on.
• Add a retry loop for 409 seedance_material_preparing before you ship anything to production — treat it as expected behavior, not an edge case.
• Store material asset IDs alongside your own internal reference records so you're not re-deriving which asset maps to which character or product.
• Review the material asset and material asset group API references directly — this article describes the workflow shape, and exact request/response fields should be confirmed against current docs before you write integration code.

You can browse the material library directly in the Seedance assets dashboard to see status, library type, and group relationships for assets you've already created.

Before committing to a production workflow, it's worth reviewing current rates in our AI video API pricing 2026 overview to understand how costs scale with usage. You can also track and export your own usage data using the guidance in TokenLab dashboard usage exports.

FAQ

What is a Seedance material asset? A material asset is a reusable video generation reference — image, video, or audio — stored as an organization-scoped object with its own lifecycle status. Once it reaches ACTIVE, you can reference it by ID across multiple generation calls instead of re-supplying a raw URL each time.

What is the difference between group_id and material_asset_id? group_id identifies a material asset group, which is a container used primarily to organize real-person (liveness_face) assets and manage verification at the group level. material_asset_id identifies a single reusable reference — the id returned when a material asset is created — and is what you pass into video generation calls.

When should I use real-person verification? Use the liveness_face type and its verification flow whenever the reference material involves an actual identifiable person's face or likeness. The flow requires session creation, an H5 liveness check, a callback, and a bind step before any assets can be uploaded into that group. Non-real-person references, such as illustrated or synthetic avatars, use aigc_avatar and do not require this verification path.

What does seedance_material_preparing mean? It's a 409 response returned when automatic material preparation — triggered by compatible image fields like image_url or start_image in a generation request — takes longer than 60 seconds to complete. The response includes auto_material_asset_ids so you can poll those IDs and retry generation once they become ACTIVE. It signals a transient in-progress state, not a failure.

Sources and Freshness

• Seedance 2.0 Video Models guide — https://docs.tokenlab.sh/guides/seedance-2-video — observed 2026-07-09
• Create Seedance material asset (API reference) — https://docs.tokenlab.sh/api-reference/video/create-material-asset — observed 2026-07-09
• Create Seedance material asset group (API reference) — https://docs.tokenlab.sh/api-reference/video/create-material-asset-group — observed 2026-07-09
• Create video (API reference) — https://docs.tokenlab.sh/api-reference/video/create-video — observed 2026-07-09
• TokenLab Seedance assets dashboard — https://tokenlab.sh/en/dashboard/seedance-assets — observed 2026-07-09

API behavior, field names, and status semantics described here reflect public documentation and dashboard copy as of the observed date. TokenLab's Seedance material system is under active development — confirm current parameter names, status values, and model-specific support in the linked docs before finalizing production integration code.

If you're building a video pipeline that depends on stable, reusable references, start with the Seedance 2.0 Video Models guide — it's the fastest way to see current parameter names and confirm what your target model tier actually supports.