TokenLab Seedance Materials: Reusable Video References for Production Workflows

If your team has ever pasted the same face-swap URL into three different API calls, you already know why the Seedance material library exists. Reusable video references work better as assets with lifecycle status than as one-off URLs copied from a spreadsheet into every generation request. TokenLab scopes those assets to your organization, so you can store, verify, and reuse references across calls. We tested the workflow shape: groups organize real-person material, assets hold the actual reference, and generation calls consume IDs only after status reaches ACTIVE. For example, a team that once kept a spreadsheet of image links and re-uploaded the same reference video five times can replace that habit with one material asset ID.

Key Takeaways

Seedance Material Library: Assets and Groups

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. It is 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. 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. 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. The docs cover the workflow shape, not every request parameter.

Virtual-Avatar and Real-Person Workflows

Seedance materials support two library types. 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. You can create these 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. This is 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. 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 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. That 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. You do not need to call the material asset endpoint separately first.

What Happens When Preparation Takes Longer Than 60 Seconds

Preparation is usually fast. 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.

In our pipeline, we treat this status like rate-limit backoff: expected, transient, and handled in code rather than reported as a user-facing error. We recommend a small retry loop, not just a single try/catch.

Using the Seedance Material Library 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 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. A generation call built on a reused material asset may need to stop mid-run. That can happen 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. That way you are not re-deriving which asset maps to which character or product.
• Review the material asset and material asset group API references directly. The docs describe the workflow shape, and exact request/response fields should be confirmed against current docs before you write integration code.

The Seedance assets dashboard shows status, library type, and group relationships for assets you've already created.

Current rates in our AI video API pricing 2026 overview help you 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

How do material assets and material groups differ?

A material asset is a single reusable reference object — one avatar image, one liveness-verified face, one reference video clip. Its id becomes material_asset_id once ACTIVE. A material group is a container identified by group_id. Groups organize related assets and are required for liveness_face workflows. In short: group_id organizes; material_asset_id generates.

Why does a generation call return 409 seedance_material_preparing?

Automatic material preparation, triggered by compatible image fields like image_url or start_image, can take longer than 60 seconds. When that happens, the API returns 409 seedance_material_preparing with auto_material_asset_ids. Poll those IDs, wait for ACTIVE, and retry generation. It signals a transient in-progress state, not a failure.

Do real-person references always need verification?

Yes. Use the liveness_face type and its verification flow whenever the reference 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 path.

Can I reuse one material asset across multiple Seedance video jobs?

Yes, once the asset reaches ACTIVE. Use its id as material_asset_id or within material_asset_ids in a create-video call. Reuse the same asset ID across future generation calls instead of re-uploading the reference. If you need to stop an in-flight job, see Seedance task cancellation.

Sources and Freshness

• Seedance 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 — /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 Video Models guide. It's the fastest way to see current parameter names and confirm what your target model tier actually supports.