Material Seedance và xác minh người thật

Material Seedance là tham chiếu hình ảnh, video hoặc âm thanh có thể tái sử dụng trong phạm vi tổ chức. Hãy chọn quy trình trước: material avatar thông thường và material người thật đã xác minh có đường tạo khác nhau.

Chọn quy trình material

Mục tiêu	Quy trình bắt buộc
Dùng URL hình ảnh một lần	Gửi URL trực tiếp trong request video; mô hình tương thích tự chuẩn bị material
Tái sử dụng avatar, sản phẩm hoặc phong cách	Tạo nhóm `aigc_avatar` và material, chờ `ACTIVE`, rồi dùng ID
Tái sử dụng người thật	Hoàn tất xác minh hình ảnh, nhận `GroupId`, tạo material, chờ `ACTIVE`, rồi dùng ID
Di chuyển client material Volcengine	Giữ định dạng Action và dùng tài liệu tham chiếu tương thích Volcengine: Action material tương thích Volcengine

Khái niệm về tài nguyên (Material)

Tài nguyên Seedance là các tham chiếu có thể tái sử dụng, thuộc phạm vi tổ chức, có thể được chọn sau này trong quá trình tạo video.

Khái niệm	Trường công khai	Ý nghĩa
Nhóm tài nguyên	`group_id`	Một nhóm TokenLab sở hữu các tài nguyên Seedance liên quan. Sử dụng khi tải lên hoặc liệt kê tài nguyên.
Tài sản tài nguyên	`id`	Một tệp hình ảnh, video hoặc âm thanh đã tải lên. Sử dụng giá trị này làm `material_asset_id` sau khi tài sản chuyển sang trạng thái `ACTIVE`.
Nhóm tài nguyên avatar ảo	`library_type: "aigc_avatar"`	Dành cho người ảo, avatar, sản phẩm, phong cách và các tham chiếu có thể tái sử dụng khác không yêu cầu xác minh người thật.
Nhóm tài nguyên người thật	`library_type: "liveness_face"`	Được tạo thông qua xác minh tài nguyên người thật. Một nhóm đại diện cho một người thật đã được xác minh.

Hãy giữ riêng biệt group_id và id của tài sản tài nguyên. group_id dùng để tổ chức các tệp tải lên; id của tài sản tài nguyên dùng để tạo video. Nếu một yêu cầu video trả về lỗi Seedance material asset not found or not accessible, hãy xác nhận rằng bạn đã truyền id của tài sản tài nguyên chứ không phải group_id, và tài sản đó thuộc cùng một tổ chức, chưa bị xóa và có status: "ACTIVE".

Material hình ảnh tự động

Khi model Seedance đã chọn có thể dùng thư viện material của TokenLab, bạn có thể gửi URL hình ảnh hoặc data URL inline được hỗ trợ trực tiếp trong image, image_url, image_urls, reference_images, start_image hoặc end_image. TokenLab nhập các hình ảnh đó vào nhóm material avatar ảo mặc định của tổ chức và giữ vai trò của chúng là frame đầu, frame cuối hoặc ảnh tham chiếu. Nếu material chuyển sang ACTIVE trong 60 giây, quá trình tạo video tiếp tục trong cùng request. Nếu chưa sẵn sàng, API trả về 409 seedance_material_preparing kèm auto_material_asset_ids; hãy truy vấn các material đó đến khi ACTIVE, rồi thử lại với material_asset_id hoặc material_asset_ids. Nếu model đã chọn không thể dùng thư viện material, URL hình ảnh hoặc data URL thông thường vẫn đi theo luồng hình ảnh thông thường; ID material tường minh sẽ trả về lỗi khả dụng material. Các ID material avatar ảo hoặc người thật đã có sẽ được dùng nguyên trạng và không nhập lại.

Xác minh tài nguyên người thật

Sử dụng xác minh tài nguyên người thật khi sản phẩm của bạn cần sự đồng ý và xác minh khuôn mặt trước khi một người thật có thể được sử dụng làm tham chiếu Seedance có thể tái sử dụng.

Gọi Tạo phiên xác thực trực quan với CallbackURL và lưu Result.BytedToken được trả về.
Mở Result.H5Link cho người cần xác thực. Thêm lng vào liên kết H5 nếu cần ngôn ngữ cụ thể.
Sau khi quy trình H5 hoàn tất, trình duyệt mở Result.CallbackURL với các tên truy vấn chính thức như bytedToken và resultCode.
Thăm dò Lấy kết quả xác thực trực quan bằng BytedToken cho đến khi trả về Result.GroupId.
Lưu GroupId và dùng làm group_id khi tạo tư liệu liveness_face.

BytedToken có hiệu lực trong 30 phút. Dùng cùng ProjectName trong cả hai yêu cầu Action. Xác thực dùng Authorization: Bearer <TOKENLAB_API_KEY>; không chấp nhận chữ ký AK/SK của Volc. Tùy chọn: sử dụng bảng điều khiển kiểm thử để xác minh yêu cầu và quy trình callback của bạn, kiểm tra các nhóm tài nguyên và xem lại lịch sử xác minh. Việc tích hợp trong môi trường production của bạn nên gọi trực tiếp các API.

Tạo nhóm tài nguyên

Sử dụng Tạo Nhóm Tài Nguyên Vật Liệu cho các nhóm aigc_avatar. Các nhóm người thật mới được tạo thông qua quy trình xác minh để người được xác minh và nhóm tài nguyên luôn được liên kết với nhau. Sử dụng Liệt kê các nhóm tài nguyên vật liệu, Lấy Nhóm Tài Nguyên Vật Liệu, Cập nhật Nhóm Tài nguyên Vật liệu và Xóa Nhóm Tài Nguyên Vật Liệu để quản lý các nhóm sau khi chúng đã tồn tại. Việc xóa một nhóm tài nguyên cũng sẽ xóa các tài nguyên TokenLab bên trong nhóm đó và không thể hoàn tác. Nếu thư viện tài nguyên TokenLab không thể hoàn tất việc xóa do trạng thái ủy quyền hiện tại không cho phép, TokenLab sẽ trả về lỗi thư viện tài nguyên trung lập.

Tải lên tài nguyên

Sử dụng Tạo Tài nguyên Vật liệu để nhập từng URL nguồn có thể truy cập công khai. Đối với aigc_avatar, group_id là tùy chọn; TokenLab sẽ sử dụng hoặc tạo nhóm avatar ảo mặc định của tổ chức. Đối với liveness_face, group_id là bắt buộc và phải là nhóm được trả về bởi Lấy kết quả xác thực trực quan.

Loại	Đầu vào hỗ trợ
Hình ảnh	`jpeg`, `png`, `webp`, `bmp`, `tiff`, `gif`, `heic`, `heif`; tỷ lệ khung hình `(0.4, 2.5)`; chiều rộng và chiều cao `(300, 6000)` px; dưới 30 MB.
Video	`mp4`, `mov`; `480p`, `720p`, hoặc `1080p`; 2-15 giây; tỷ lệ khung hình `[0.4, 2.5]`; chiều rộng và chiều cao `[300, 6000]` px; tổng số pixel từ 409600 đến 2068676; tối đa 200 MB; 24-60 FPS.
Âm thanh	`aac`, `wav`, `mp3`; 2-15 giây; tối đa 15 MB.

Việc tiếp nhận tài nguyên là không đồng bộ. Hãy thăm dò Lấy tài nguyên vật liệu (Get Material Asset) cho đến khi status trở thành ACTIVE. Phản hồi HTTP thành công chỉ có nghĩa là yêu cầu đã được chấp nhận; hãy luôn đọc trạng thái nghiệp vụ. Nếu trạng thái là FAILED, hãy kiểm tra error_message, sửa tài nguyên nguồn và tạo tài sản mới. Trong yêu cầu tạo vật liệu, asset_url chỉ là nguồn nhập. TokenLab trả về id tài nguyên vật liệu; hãy dùng id đó để tạo video thay vì dùng lại URL gốc. TokenLab giữ tài nguyên trong thư viện tài nguyên của tổ chức cho đến khi bạn xóa tài nguyên đó hoặc nhóm tài nguyên chứa nó. Đối với các nhóm tài nguyên người thật, một nhóm tương ứng với một người thật. Các tệp tải lên sẽ được kiểm tra đối chiếu với khuôn mặt đã xác minh. Các tài sản có nhiều khuôn mặt hoặc khuôn mặt không khớp với người đã xác minh có thể bị lỗi. Để có kết quả tốt nhất, hãy tải lên cả hình ảnh tham chiếu toàn thân từ phía trước và ảnh cận cảnh khuôn mặt rõ nét từ phía trước.

Sử dụng tài nguyên trong tạo video

Sau khi tài sản ở trạng thái ACTIVE, hãy truyền id tài sản TokenLab được trả về dưới dạng material_asset_id, hoặc đưa nó vào material_asset_ids, khi gọi Tạo video. Các tài sản tài nguyên được tính vào giới hạn tham chiếu của Seedance.

REST hoặc Action Volcengine

Tích hợp TokenLab native có thể tiếp tục dùng API REST snake_case /v1/videos/assets*. Client Volcengine hiện có giữ body PascalCase và dùng Action material tương thích Volcengine. Hai giao diện thao tác cùng dữ liệu material theo tổ chức và project.

Ví dụ về API

Tạo một nhóm avatar ảo, tải lên một hình ảnh, thăm dò cho đến khi nó hoạt động, sau đó sử dụng ID tài sản tài nguyên trong một yêu cầu video.

curl https://api.tokenlab.sh/v1/videos/assets/groups \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"library_type":"aigc_avatar","group_name":"Product references"}'

curl https://api.tokenlab.sh/v1/videos/assets \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"library_type":"aigc_avatar","group_id":"group-20260720123456-abc12","asset_url":"https://example.com/reference.png","asset_type":"Image"}'

curl https://api.tokenlab.sh/v1/videos/assets/asset-20260720123457-def45 \
  -H "Authorization: Bearer $TOKENLAB_API_KEY"

Đối với nhóm tư liệu người thật, hãy tạo phiên xác thực trực quan và lấy kết quả trước khi tải tư liệu lên.

curl 'https://api.tokenlab.sh/api/v3?Action=CreateVisualValidateSession&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"CallbackURL":"https://yourapp.example.com/seedance/callback","ProjectName":"default"}'

curl 'https://api.tokenlab.sh/api/v3?Action=GetVisualValidateResult&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"BytedToken":"ZXhhbXBsZS10b2tlbg","ProjectName":"default"}'

Quy trình Action đầy đủ cho người thật

Truyền GroupId từ kết quả xác minh vào CreateAsset.

curl 'https://api.tokenlab.sh/?Action=CreateAsset&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId":"group-20260720123456-real1",
    "URL":"https://example.com/person-front.png",
    "Name":"Verified front view",
    "AssetType":"Image",
    "ProjectName":"default"
  }'

Polling GetAsset đến khi trạng thái là Active, rồi dùng ID material được trả về để tạo video.

Bắt đầu

Hướng dẫn cốt lõi

Hướng dẫn media

Material Seedance và xác minh người thật

Chọn quy trình material

Khái niệm về tài nguyên (Material)

Material hình ảnh tự động

Xác minh tài nguyên người thật

Tạo nhóm tài nguyên

Tải lên tài nguyên

Sử dụng tài nguyên trong tạo video

REST hoặc Action Volcengine

Ví dụ về API

Quy trình Action đầy đủ cho người thật

​Chọn quy trình material

​Khái niệm về tài nguyên (Material)

​Material hình ảnh tự động

​Xác minh tài nguyên người thật

​Tạo nhóm tài nguyên

​Tải lên tài nguyên

​Sử dụng tài nguyên trong tạo video

​REST hoặc Action Volcengine

​Ví dụ về API

​Quy trình Action đầy đủ cho người thật

Chọn quy trình material

Khái niệm về tài nguyên (Material)

Material hình ảnh tự động

Xác minh tài nguyên người thật

Tạo nhóm tài nguyên

Tải lên tài nguyên

Sử dụng tài nguyên trong tạo video

REST hoặc Action Volcengine

Ví dụ về API

Quy trình Action đầy đủ cho người thật