Tài liệu Seedance của TokenLab: Tài liệu tham khảo video có thể tái sử dụng cho quy trình sản xuất

Các tài nguyên video có thể tái sử dụng sẽ dễ quản lý hơn khi chúng là các tài sản có trạng thái vòng đời, thay vì là các URL dùng một lần được sao chép vào mọi yêu cầu tạo video. Nếu bạn đã từng phải duy trì một bảng tính chứa các liên kết hình ảnh, tải lại cùng một video tham chiếu năm lần, hoặc nhập đi nhập lại một URL hoán đổi khuôn mặt vào ba lệnh gọi API khác nhau, thì bạn đã hiểu vấn đề mà các tài liệu Seedance được xây dựng để giải quyết.

Thư viện tài liệu Seedance của TokenLab cung cấp cho các đội ngũ sản xuất video một cách thức lưu trữ, xác minh và tái sử dụng các tài liệu tham chiếu trong phạm vi tổ chức cho các lệnh gọi tạo video. Bài viết này giải thích tài sản tài liệu (material asset) thực chất là gì, các nhóm tài liệu (material group) liên quan đến từng tài sản riêng lẻ như thế nào, cách thức chuẩn bị tự động hoạt động ra sao và việc xác minh người thật phù hợp ở đâu trong quy trình làm việc.

Những điểm chính cần lưu ý

• Tài sản tài liệu (material asset) là đối tượng tham chiếu sẵn sàng để tạo video; nhóm tài liệu (material group) là vùng chứa giúp tổ chức các tài sản liên quan, đặc biệt là cho các quy trình làm việc với người thật.
• Chỉ sử dụng id của tài sản tài liệu làm material_asset_id (hoặc bên trong material_asset_ids) sau khi trạng thái của nó đạt ACTIVE.
• Có hai loại thư viện tồn tại: aigc_avatar dành cho avatar ảo và các tài liệu tham chiếu không phải người thật có thể tái sử dụng, và liveness_face dành cho các nhóm tài liệu người thật yêu cầu xác minh.
• TokenLab có thể tự động chuẩn bị các đầu vào hình ảnh tương thích (image, image_url, image_urls, reference_images, start_image, end_image) thành các tài sản tài liệu mà không cần bước tải lên riêng biệt.
• Nếu quá trình chuẩn bị kéo dài hơn 60 giây, API sẽ trả về 409 seedance_material_preparing cùng với auto_material_asset_ids để bạn có thể truy vấn và thử lại.
• Seedance 2.0, Seedance 2.0 Fast và Seedance 2.0 Mini là các mô hình công khai hiện tại mà hệ thống tài liệu này hỗ trợ. Hãy xác minh chi tiết khả năng của từng mô hình trong tài liệu trước khi xây dựng sự phụ thuộc vào một cấp độ cụ thể.

Tài liệu Seedance là gì

Tài liệu Seedance là một tài liệu tham chiếu có thể tái sử dụng — hình ảnh, video hoặc âm thanh — mà TokenLab lưu trữ dưới dạng tài sản trong phạm vi tổ chức thay vì URL trong phạm vi yêu cầu. Thay vì chuyển một liên kết tệp thô vào mỗi lệnh gọi create-video, bạn tải lên hoặc nhập tài liệu tham chiếu một lần, đợi nó sẵn sàng để tạo video, sau đó tham chiếu nó bằng ID trong bao nhiêu lệnh gọi tiếp theo tùy thích.

Điều này quan trọng vì ba lý do thực tế.

Thứ nhất, việc tải lên lặp đi lặp lại gây lãng phí băng thông và làm tăng độ trễ cho mỗi yêu cầu, đặc biệt là đối với các video tham chiếu lớn.

Thứ hai, các URL thô có thể hết hạn, bị thay đổi hoặc bị thu hồi bởi bất kỳ hệ thống lưu trữ nào lưu trữ chúng ban đầu. Một tài sản tài liệu do TokenLab quản lý không gặp phải sự mong manh đó.

Thứ ba, và quan trọng nhất đối với các đội ngũ xây dựng quy trình video nhất quán về nhân vật hoặc thương hiệu, tài liệu cung cấp cho bạn một định danh ổn định mà bạn có thể quản lý phiên bản, kiểm tra và thay thế mà không cần phải thay đổi logic tạo video mỗi lần.

Tài sản tài liệu (Material Assets) so với Nhóm tài liệu (Material Groups)

Hai đối tượng cốt lõi trong hệ thống này là tài sản tài liệu và nhóm tài sản tài liệu, và rất dễ nhầm lẫn nếu bạn chưa đọc kỹ tài liệu tham khảo API.

Một tài sản tài liệu là một đối tượng tham chiếu đơn lẻ — một hình ảnh avatar, một khuôn mặt đã xác minh sự sống, một clip video tham chiếu. Khi bạn tạo nó, API sẽ trả về một id. id đó là thứ bạn sẽ chuyển vào các lệnh gọi tạo video sau khi tài sản đạt trạng thái ACTIVE.

Một nhóm tài sản tài liệu là một vùng chứa được xác định bởi group_id. Các nhóm tổ chức các tài sản liên quan lại với nhau và chúng là yêu cầu bắt buộc về cấu trúc đối với các quy trình làm việc với người thật (liveness_face), nơi việc xác minh diễn ra ở cấp độ nhóm trước khi các tài sản riêng lẻ có thể được tải lên vào đó.

Tóm lại: group_id dùng để tổ chức; material_asset_id dùng để tạo video. Bạn sẽ thấy cả hai trường này ở các phần khác nhau của API, và việc sử dụng sai trường là lỗi tích hợp phổ biến nhất mà các đội ngũ thường gặp phải với hệ thống này.

Trường	Nó xác định cái gì	Nơi bạn sử dụng nó
group_id	Một nhóm tài sản tài liệu (vùng chứa)	Tạo hoặc tham chiếu một nhóm, đặc biệt cho các quy trình xác minh người thật
id (trên một tài sản tài liệu)	Một tài liệu tham chiếu đơn lẻ có thể tái sử dụng	Trở thành material_asset_id khi đạt trạng thái ACTIVE
material_asset_id	Một tham chiếu tài sản đơn lẻ	Được chuyển vào create-video cho một vị trí tham chiếu
material_asset_ids	Một mảng các tham chiếu tài sản	Được chuyển vào create-video khi cần nhiều tham chiếu có thể tái sử dụng

Các định nghĩa trường đầy đủ và các tham số bắt buộc được ghi lại tại tài liệu tham khảo API tạo tài sản tài liệu và tạo nhóm tài sản tài liệu. Hãy đọc kỹ những tài liệu đó trước khi đưa vào mã nguồn sản xuất — bài viết này đề cập đến hình thái quy trình, không phải mọi tham số yêu cầu.

Quy trình làm việc với Avatar ảo và Người thật

Các tài liệu Seedance hỗ trợ hai loại thư viện, và sự khác biệt này không chỉ là hình thức — nó phản ánh hai tư thế bảo mật và đồng thuận khác nhau.

aigc_avatar: Avatar ảo và các tài liệu tham chiếu không phải người thật

Loại aigc_avatar bao gồm các tài liệu tham chiếu có thể tái sử dụng không gắn liền với một người thật đã được xác minh: các nhân vật minh họa, avatar tổng hợp, hình tượng cách điệu, linh vật thương hiệu và các tài sản tương tự. Những tài liệu này có thể được tạo trực tiếp thông qua quy trình tạo tài sản tài liệu mà không cần bước xác minh.

Nếu sản phẩm của bạn tạo video xoay quanh các nhân vật hư cấu hoặc avatar thương hiệu, đây gần như chắc chắn là loại thư viện bạn muốn. Nó có đường dẫn tạo đơn giản hơn vì không có yêu cầu xác minh danh tính đi kèm.

liveness_face: Nhóm tài liệu người thật

Loại liveness_face dành cho các nhóm tài liệu được xây dựng xung quanh hình ảnh của một người thật — loại tham chiếu được sử dụng để tạo video nhất quán về khuôn mặt có sự góp mặt của một cá nhân thực tế. Vì điều này liên quan đến danh tính và sự đồng thuận, TokenLab yêu cầu một quy trình xác minh trước khi các tài sản có thể được tải lên vào nhóm.

Chuỗi xác minh có một vài bước riêng biệt:

1. Tạo phiên — backend của bạn yêu cầu một phiên xác minh cho nhóm.
2. Quy trình H5 — người được xác minh hoàn thành kiểm tra sự sống thông qua một quy trình web được lưu trữ (đây là ý nghĩa của "H5": giao diện xác minh web di động).
3. Callback — TokenLab thông báo cho hệ thống của bạn khi phiên xác minh kết thúc.
4. Liên kết kết quả — danh tính đã xác minh được liên kết với nhóm tài liệu.
5. Tải lên theo nhóm — chỉ sau khi liên kết thành công, các tài sản tài liệu mới có thể được tải lên vào nhóm cụ thể đó.

Điều này có nghĩa là các tài liệu người thật vốn dĩ là ưu tiên nhóm: bạn không thể bỏ qua bước tạo tài sản như với aigc_avatar. Nhóm phải tồn tại và vượt qua xác minh trước khi bất kỳ việc tải lên tài sản nào vào đó là hợp lệ.

Danh sách kiểm tra: Chọn loại thư viện phù hợp

• Tài liệu tham chiếu có phải là khuôn mặt hoặc hình ảnh của một người thật, có thể nhận dạng được không? → Sử dụng liveness_face và lập kế hoạch cho quy trình xác minh.
• Tài liệu tham chiếu có phải là tổng hợp, minh họa hoặc một avatar không phải người thật không? → Sử dụng aigc_avatar và bỏ qua xác minh.
• Sản phẩm của bạn có cần danh tính nhất quán trên nhiều lần tạo cho cùng một người thật không? → Xây dựng nhóm một lần, xác minh một lần, tái sử dụng nhóm cho các tài sản trong tương lai.
• Bạn không chắc chắn loại tài liệu tham chiếu do khách hàng cung cấp thuộc loại nào? → Hãy coi nó là liveness_face cho đến khi được xác nhận ngược lại; hãy kiểm tra trong tài liệu, đừng giả định.

Đừng giả định rằng mọi mô hình tạo video hoặc mọi loại yêu cầu đều hỗ trợ cả hai loại thư viện giống hệt nhau — hãy xác nhận hỗ trợ hiện tại trong Hướng dẫn mô hình video Seedance 2.0 trước khi cam kết với một kiến trúc cụ thể.

Cách thức hoạt động của việc chuẩn bị tài liệu tự động

Không phải mọi tài liệu tham chiếu đều cần bước tải lên thủ công. TokenLab có thể tự động chuẩn bị các đầu vào hình ảnh tương thích thành các tài sản tài liệu như một phần của yêu cầu tạo video, giúp loại bỏ một bước trung gian cho các trường hợp đơn giản.

Các trường mà nó nhận diện để chuẩn bị tự động là:

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

Nếu bạn chuyển bất kỳ trường nào trong số này trực tiếp vào lệnh gọi tạo video, TokenLab sẽ xử lý việc nhập và chuẩn bị ở phía sau thay vì yêu cầu bạn gọi điểm cuối tài sản tài liệu riêng biệt trước.

Điều gì xảy ra khi việc chuẩn bị mất hơn 60 giây

Việc chuẩn bị thường diễn ra nhanh chóng, nhưng các hình ảnh tham chiếu lớn hơn hoặc phức tạp hơn có thể mất nhiều thời gian hơn để xử lý thành tài sản sẵn sàng tạo video. Nếu việc chuẩn bị vượt quá 60 giây, API sẽ phản hồi với:

409 seedance_material_preparing

cùng với trường auto_material_asset_ids chứa ID của các tài sản vẫn đang được chuẩn bị.

Đây không phải là lỗi theo nghĩa thông thường — đó là tín hiệu để thử lại. Việc tích hợp của bạn nên coi 409 seedance_material_preparing là phản hồi "kiểm tra lại sau một lát", không phải là lỗi để hiển thị cho người dùng cuối. Hãy truy vấn các ID tài sản được trả về, đợi trạng thái ACTIVE, sau đó tiến hành tạo video bằng các ID đó.

Trên thực tế, điều này có nghĩa là quy trình tạo video của bạn cần một vòng lặp thử lại nhỏ, không chỉ là một lệnh try/catch đơn lẻ. Các đội ngũ xây dựng quy trình video tự động nên coi trạng thái này giống như cách họ xử lý việc giới hạn tốc độ (rate-limit backoff) — đó là điều dự kiến, tạm thời và được xử lý trong mã nguồn thay vì báo cáo như một lỗi người dùng.

Cách sử dụng tài liệu trong việc tạo video

Khi một tài sản tài liệu — dù được tải lên thủ công hay chuẩn bị tự động — đạt trạng thái ACTIVE, id của nó sẽ trở nên khả dụng dưới dạng material_asset_id (hoặc dưới dạng một mục trong material_asset_ids) trong lệnh gọi tạo video.

Quy trình cốt lõi trông như sau:

1. Quyết định xem tài liệu tham chiếu có phải là người thật hay không. Chọn liveness_face (có xác minh) hoặc aigc_avatar tương ứng.
2. Nếu là người thật: tạo nhóm tài liệu, chạy phiên xác minh và quy trình H5, nhận callback và liên kết kết quả.
3. Tạo hoặc nhập tài sản tài liệu — thông qua lệnh gọi tải lên trực tiếp hoặc bằng cách để việc chuẩn bị tự động xử lý một trường hình ảnh tương thích bên trong yêu cầu tạo video.
4. Kiểm tra trạng thái. Không chuyển ID tài sản vào quá trình tạo video cho đến khi nó báo ACTIVE.
5. Nếu bạn nhận được 409 seedance_material_preparing, hãy truy vấn các auto_material_asset_ids được trả về và thử lại sau khi chúng chuyển sang ACTIVE.
6. Sử dụng id làm material_asset_id hoặc bên trong material_asset_ids trong lệnh gọi create-video của bạn, nhắm mục tiêu vào một mô hình Seedance hiện tại như seedance-2.0, seedance-2.0-fast hoặc seedance-2.0-mini tùy thuộc vào nhu cầu về độ trễ và chất lượng của bạn.
7. Tái sử dụng cùng một ID tài sản trong các lệnh gọi tạo video trong tương lai thay vì tải lại tài liệu tham chiếu.

Đây cũng là nơi quản lý tác vụ trở nên quan trọng. Nếu một lệnh gọi tạo video dựa trên một tài sản tài liệu được tái sử dụng cần phải dừng giữa chừng — để kiểm soát chi phí, thay đổi yêu cầu sáng tạo hoặc do một câu lệnh không tốt — hãy xem bài viết đồng hành của chúng tôi về hủy tác vụ Seedance để biết cách việc hủy tương tác với các công việc video đang thực hiện.

Để có sự so sánh rộng hơn về những gì hiện có trên các mô hình tạo video trên TokenLab, trang danh mục mô hình video liệt kê các tùy chọn hiện tại cạnh nhau.

Các bước tiếp theo thực tế

• Nếu bạn đang tạo mẫu, hãy bắt đầu với tài liệu aigc_avatar — đường dẫn tạo đơn giản hơn và không có sự phụ thuộc vào xác minh để xây dựng xung quanh trước.
• Nếu sản phẩm của bạn yêu cầu sự nhất quán về người thật, hãy xây dựng quy trình xác minh (phiên → H5 → callback → liên kết) như một phần quan trọng trong quá trình onboarding của bạn, không phải là một phần bổ sung.
• Thêm vòng lặp thử lại cho 409 seedance_material_preparing trước khi bạn phát hành bất cứ thứ gì ra sản xuất — hãy coi đó là hành vi dự kiến, không phải là trường hợp ngoại lệ.
• Lưu trữ ID tài sản tài liệu cùng với hồ sơ tham chiếu nội bộ của riêng bạn để bạn không phải xác định lại tài sản nào ánh xạ tới nhân vật hoặc sản phẩm nào.
• Xem lại trực tiếp các tài liệu tham khảo API tài sản tài liệu và nhóm tài sản tài liệu — bài viết này mô tả hình thái quy trình, và các trường yêu cầu/phản hồi chính xác nên được xác nhận dựa trên tài liệu hiện tại trước khi bạn viết mã tích hợp.

Bạn có thể duyệt thư viện tài liệu trực tiếp trong bảng điều khiển tài sản Seedance để xem trạng thái, loại thư viện và mối quan hệ nhóm cho các tài sản bạn đã tạo.

Trước khi cam kết với quy trình sản xuất, bạn nên xem lại mức giá hiện tại trong tổng quan giá API video AI 2026 của chúng tôi để hiểu cách chi phí tăng theo mức sử dụng. Bạn cũng có thể theo dõi và xuất dữ liệu sử dụng của riêng mình bằng cách sử dụng hướng dẫn trong xuất dữ liệu sử dụng bảng điều khiển TokenLab.

Câu hỏi thường gặp

Tài sản tài liệu Seedance là gì? Tài sản tài liệu là một tài liệu tham chiếu tạo video có thể tái sử dụng — hình ảnh, video hoặc âm thanh — được lưu trữ dưới dạng đối tượng trong phạm vi tổ chức với trạng thái vòng đời riêng. Khi nó đạt trạng thái ACTIVE, bạn có thể tham chiếu nó bằng ID trong nhiều lệnh gọi tạo video thay vì cung cấp lại URL thô mỗi lần.

Sự khác biệt giữa group_id và material_asset_id là gì? group_id xác định một nhóm tài sản tài liệu, là một vùng chứa được sử dụng chủ yếu để tổ chức các tài sản người thật (liveness_face) và quản lý xác minh ở cấp độ nhóm. material_asset_id xác định một tài liệu tham chiếu có thể tái sử dụng đơn lẻ — id được trả về khi một tài sản tài liệu được tạo — và là thứ bạn chuyển vào các lệnh gọi tạo video.

Khi nào tôi nên sử dụng xác minh người thật? Sử dụng loại liveness_face và quy trình xác minh của nó bất cứ khi nào tài liệu tham chiếu liên quan đến khuôn mặt hoặc hình ảnh của một người thật có thể nhận dạng được. Quy trình yêu cầu tạo phiên, kiểm tra sự sống H5, callback và bước liên kết trước khi bất kỳ tài sản nào có thể được tải lên vào nhóm đó. Các tài liệu tham chiếu không phải người thật, chẳng hạn như avatar minh họa hoặc tổng hợp, sử dụng aigc_avatar và không yêu cầu quy trình xác minh này.

seedance_material_preparing có nghĩa là gì? Đó là phản hồi 409 được trả về khi việc chuẩn bị tài liệu tự động — được kích hoạt bởi các trường hình ảnh tương thích như image_url hoặc start_image trong yêu cầu tạo video — mất hơn 60 giây để hoàn thành. Phản hồi bao gồm auto_material_asset_ids để bạn có thể truy vấn các ID đó và thử lại việc tạo video sau khi chúng trở thành ACTIVE. Nó báo hiệu một trạng thái đang tiến hành tạm thời, không phải là lỗi.

Nguồn và độ mới

• Hướng dẫn mô hình video Seedance 2.0 — https://docs.tokenlab.sh/guides/seedance-2-video — quan sát ngày 2026-07-09
• Tạo tài sản tài liệu Seedance (tham khảo API) — https://docs.tokenlab.sh/api-reference/video/create-material-asset — quan sát ngày 2026-07-09
• Tạo nhóm tài sản tài liệu Seedance (tham khảo API) — https://docs.tokenlab.sh/api-reference/video/create-material-asset-group — quan sát ngày 2026-07-09
• Tạo video (tham khảo API) — https://docs.tokenlab.sh/api-reference/video/create-video — quan sát ngày 2026-07-09
• Bảng điều khiển tài sản Seedance của TokenLab — https://tokenlab.sh/en/dashboard/seedance-assets — quan sát ngày 2026-07-09

Hành vi API, tên trường và ngữ nghĩa trạng thái được mô tả ở đây phản ánh tài liệu công khai và bản sao bảng điều khiển tính đến ngày quan sát. Hệ thống tài liệu Seedance của TokenLab đang được phát triển tích cực — hãy xác nhận tên tham số hiện tại, giá trị trạng thái và hỗ trợ cụ thể cho mô hình trong các tài liệu được liên kết trước khi hoàn thiện mã tích hợp sản xuất.

Nếu bạn đang xây dựng một quy trình video phụ thuộc vào các tài liệu tham chiếu ổn định, có thể tái sử dụng, hãy bắt đầu với Hướng dẫn mô hình video Seedance 2.0 — đó là cách nhanh nhất để xem tên tham số hiện tại và xác nhận những gì cấp độ mô hình mục tiêu của bạn thực sự hỗ trợ.