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

Nếu nhóm của bạn đã từng dán cùng một URL hoán đổi khuôn mặt (face-swap) vào ba lệnh gọi API khác nhau, bạn đã hiểu lý do tại sao thư viện tài liệu Seedance tồn tại. Các tài nguyên tham chiếu video có thể tái sử dụng hoạt động hiệu quả hơn dưới dạng các tài sản (assets) có trạng thái vòng đời thay vì là các URL dùng một lần được sao chép từ bảng tính vào mọi yêu cầu tạo video. TokenLab giới hạn các tài sản đó trong tổ chức của bạn, vì vậy bạn có thể lưu trữ, xác minh và tái sử dụng các tài nguyên tham chiếu trên nhiều lệnh gọi. Chúng tôi đã thử nghiệm hình thái quy trình: các nhóm (groups) tổ chức tài liệu về người thật, các tài sản (assets) giữ tài nguyên tham chiếu thực tế và các lệnh gọi tạo video chỉ sử dụng ID sau khi trạng thái đạt ACTIVE. Ví dụ, một nhóm từng giữ bảng tính các liên kết hình ảnh và tải lên lại cùng một video tham chiếu năm lần có thể thay thế thói quen đó bằng một ID tài sản tài liệu duy nhất.

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

• Một tài sản tài liệu (material asset) là đối tượng tham chiếu sẵn sàng để tạo video; một nhóm tài liệu (material group) là vùng chứa tổ chức các tài sản liên quan, đặc biệt 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 cho avatar ảo và các tài nguyên tham chiếu không phải người thật có thể tái sử dụng, và liveness_face 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 là dòng 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 độ (tier) cụ thể.

Thư viện tài liệu Seedance: Tài sản và Nhóm

Tài liệu Seedance là một tài nguyên 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 giới hạn trong tổ chức thay vì URL giới hạn trong yêu cầu. Thay vì truyền 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 nguyên 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 đố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 ban đầu lưu trữ chúng. Một tài sản tài liệu do TokenLab quản lý không có sự mong manh đó. Thứ ba, và quan trọng nhất đối với các nhóm 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. Rất dễ nhầm lẫn giữa chúng 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ống động (liveness-verified), 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ẽ truyề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. Chúng là yêu cầu bắt buộc về mặt 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 đó.

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. Sử dụng sai trường ở sai vị trí là lỗi tích hợp phổ biến nhất mà các nhóm 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 nguyên tham chiếu có thể tái sử dụng đơn lẻ	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ẻ	Truyề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	Truyền vào create-video khi cần nhiều tài nguyên tham chiếu

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ỹ trước khi đưa vào mã nguồn sản xuất. Tài liệu bao gồm 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. 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 nguyên tham chiếu không phải người thật

Loại aigc_avatar bao gồm các tài nguyên 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: 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ự. Bạn có thể tạo chúng 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. Đây là 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 quy trình xác minh trước khi các tài sản có thể được tải lên 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ống động thông qua quy trình web được lưu trữ. H5 đề cập đến giao diện xác minh trên 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. Ràng buộc kết quả — danh tính đã xác minh được ràng buộc với nhóm tài liệu.
5. Tải lên theo phạm vi nhóm — chỉ sau khi ràng buộc thành công, các tài sản tài liệu mới có thể được tải lên nhóm cụ thể đó.

Điều này có nghĩa là các tài liệu về người thật vốn dĩ ưu tiên nhóm. Bạn không thể bỏ qua bước tạo tài sản như cách bạn làm 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ỳ tài sản nào được tải lên đó là hợp lệ.

Danh sách kiểm tra: Chọn đúng loại thư viện

• Tài nguyên 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 nguyên tham chiếu có phải là tổng hợp, minh họa hoặc 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 nguyên 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 về mô hình video Seedance trước khi cam kết với một kiến trúc.

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 nguyên 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. Điều đó 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 dạng để chuẩn bị tự động là:

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

Nếu bạn truyề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. Bạn không cần phải 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 quá trình chuẩn bị mất hơn 60 giây

Quá trình chuẩn bị thường diễn ra nhanh chó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 quá trình 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. 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ếp tục tạo video bằng các ID đó.

Trong quy trình của chúng tôi, chúng tôi coi trạng thái này giống như việc giảm tải khi bị giới hạn tốc độ (rate-limit backoff): 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 hiển thị cho người dùng. Chúng tôi khuyến nghị một vòng lặp thử lại nhỏ, không chỉ là một lần thử/bắt lỗi (try/catch).

Sử dụng Thư viện tài liệu Seedance 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ư thế này:

1. Quyết định xem tài nguyên 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 cho phù hợp.
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à ràng buộc 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 để quá trình 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. Đừng truyền ID tài sản vào việc tạo video cho đến khi nó báo cá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 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ên lại tài nguyên tham chiếu.

Đây cũng là nơi quản lý tác vụ trở nên quan trọng. Một lệnh gọi tạo video được xây dựng trên một tài sản tài liệu được tái sử dụng có thể cần dừng lại giữa chừng. Điều đó có thể xảy ra do kiểm soát chi phí, bản tóm tắt sáng tạo bị thay đổi hoặc một câu lệnh (prompt) không tốt. Xem bài viết đi kèm 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 nguyên 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 xác minh nào cần 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 → ràng buộc) như một phần quan trọng trong quá trình giới thiệu người dùng (onboarding), 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ằng cách đó, bạn không phải suy luận 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 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. Tài liệu 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ảng điều khiển tài sản Seedance hiển thị 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.

Giá cước hiện tại trong tổng quan giá API video AI 2026 của chúng tôi giúp bạn hiểu cách chi phí mở rộ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 và nhóm tài liệu khác nhau như thế nào?

Một tài sản tài liệu là một đối tượng tham chiếu có thể tái sử dụng đơn lẻ — một hình ảnh avatar, một khuôn mặt đã xác minh độ sống động, một clip video tham chiếu. id của nó trở thành material_asset_id khi đạt trạng thái ACTIVE. Một nhóm 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 và là yêu cầu bắt buộc cho các quy trình liveness_face. Tóm lại: group_id dùng để tổ chức; material_asset_id dùng để tạo video.

Tại sao lệnh gọi tạo video trả về 409 seedance_material_preparing?

Quá trình 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, có thể mất hơn 60 giây. Khi điều đó xảy ra, API trả về 409 seedance_material_preparing với auto_material_asset_ids. Hãy truy vấn các ID đó, đợi trạng thái ACTIVE và thử lại việc tạo video. Nó báo hiệu một trạng thái tạm thời đang thực hiện, không phải là lỗi.

Các tài nguyên tham chiếu người thật có luôn cần xác minh không?

Có. 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 nguyên 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ống động H5, callback và bước ràng buộc trước khi bất kỳ tài sản nào có thể được tải lên nhóm đó. Các tài nguyên 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 này.

Tôi có thể tái sử dụng một tài sản tài liệu trên nhiều công việc video Seedance không?

Có, sau khi tài sản đạt trạng thái ACTIVE. Sử dụng id của nó làm material_asset_id hoặc bên trong material_asset_ids trong lệnh gọi create-video. 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ên lại tài nguyên tham chiếu. Nếu bạn cần dừng một công việc đang thực hiện, hãy xem hủy tác vụ Seedance.

Nguồn và Độ mới

• Hướng dẫn về mô hình video Seedance — 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 — /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ại 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 từng 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 nguyên tham chiếu ổn định, có thể tái sử dụng, hãy bắt đầu với Hướng dẫn về mô hình video Seedance. Đó 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ợ.