Hướng dẫn media
Tài liệu Seedance và Xác thực người thật
Tái sử dụng hình ảnh, video, âm thanh hoặc người đã xác thực trong Seedance
Các tài liệu Seedance cho phép bạn tái sử dụng tệp hình ảnh, video hoặc âm thanh mà không cần nhập lại cho mỗi lần tạo. Các tham chiếu đến người thật yêu cầu sự đồng ý và xác thực hình ảnh; đối với người ảo, sản phẩm và phong cách thì không cần.
Chọn loại tài liệu
| Nội dung bạn muốn tái sử dụng | Việc cần làm |
|---|---|
| Một hình ảnh dùng một lần | Gửi URL của nó trong trường hình ảnh được hỗ trợ; việc này không tạo ID tài liệu có thể tái sử dụng |
| Tái sử dụng người ảo, sản phẩm hoặc phong cách | Tạo nhóm aigc_avatar, tạo tài sản, đợi trạng thái ACTIVE, sau đó sử dụng ID tài sản |
| Tái sử dụng người thật | Hoàn tất xác thực hình ảnh, nhận GroupId, tạo tài sản trong nhóm đó, đợi trạng thái ACTIVE, sau đó sử dụng ID tài sản |
| Di chuyển khách hàng tài liệu Volcengine hiện có | Giữ nguyên cấu trúc yêu cầu Action và sử dụng tham chiếu tài liệu tương thích Volc |
Nhóm và tài liệu
| Mục | Trường REST | Trường Action | Ý nghĩa |
|---|---|---|---|
| Nhóm tài liệu | group_id | GroupId | Giữ các tài liệu liên quan cùng nhau |
| Tài liệu | id | Id | Một tệp hình ảnh, video hoặc âm thanh đã nhập; sử dụng ID này sau khi nó trở nên active |
| Nhóm avatar ảo | library_type: "aigc_avatar" | GroupType: "AIGC" | Không yêu cầu xác thực người thật |
| Nhóm người thật | library_type: "liveness_face" | GroupType: "LivenessFace" | Chỉ được tạo thông qua quy trình xác thực hình ảnh thành công |
| Tên dự án | project_name | ProjectName | Giữ các tài liệu từ các dự án khác nhau tách biệt; mặc định là default |
Hãy giữ ID nhóm và ID tài sản riêng biệt. Một nhóm dùng để tổ chức các tệp tải lên; ID tài sản là tham chiếu được sử dụng bởi quá trình tạo video. Các ID công khai có dạng group-20260720123456-vrt01 và asset-20260720123457-def45.
Lưu trữ tài liệu
TokenLab lưu giữ mọi tài sản tài liệu cho đến khi bạn xóa tài sản hoặc nhóm của nó. Tài liệu không bị xóa do không hoạt động.
- Nếu một tài sản cần được chuẩn bị lại khi bạn sử dụng, lần tạo đầu tiên có thể mất nhiều thời gian hơn một chút. Nếu nó chưa sẵn sàng, yêu cầu sẽ trả về
409 seedance_material_preparing; hãy thử lại sau ít phút. - Việc xóa một tài sản hoặc nhóm là vĩnh viễn và không thể hoàn tác.
URL hình ảnh và tài liệu có thể tái sử dụng
Gửi các URL HTTP(S) công khai hoặc các URL dữ liệu được hỗ trợ trong các trường hình ảnh mà mô hình bạn chọn chấp nhận. Các đầu vào này tuân theo đường dẫn phương tiện thông thường và không tự động tạo ID tài liệu có thể tái sử dụng.
Đối với các tài liệu có thể tái sử dụng, hãy tạo tài sản thông qua API tài liệu, đợi trạng thái ACTIVE, sau đó sử dụng material_asset_id, material_asset_ids hoặc asset://<id> trong trường phương tiện được hỗ trợ. Hãy giữ vai trò khung hình đầu tiên, khung hình cuối cùng hoặc hình ảnh tham chiếu dự kiến.
Khi một tài liệu cụ thể vẫn đang trong quá trình chuẩn bị, POST /v1/videos/generations sẽ trả về 409 seedance_material_preparing cùng với inactive_asset_ids. Hãy thăm dò các tài sản đó cho đến khi trạng thái là ACTIVE, sau đó thử lại với cùng các ID tài liệu đó. Nếu một tài sản ở trạng thái FAILED, hãy kiểm tra error_message và sửa hoặc nhập lại trước khi thử lại. Một yêu cầu tạo sử dụng tài sản bị lỗi sẽ trả về 422 seedance_material_failed cùng với failed_asset_ids.
Tài liệu Avatar ảo
Sử dụng Tạo nhóm tài sản tài liệu để tạo nhóm aigc_avatar. Đối với việc tạo tài sản REST, group_id là tùy chọn chỉ khi project_name là default; khi đó TokenLab sẽ sử dụng hoặc tạo nhóm avatar ảo mặc định của tổ chức. Một project_name không phải mặc định và mọi tài sản người thật đều yêu cầu group_id.
Sau khi một nhóm tồn tại, hãy quản lý nó bằng:
- Liệt kê các nhóm tài sản tài liệu
- Lấy nhóm tài sản tài liệu
- Cập nhật nhóm tài sản tài liệu
- Xóa nhóm tài sản tài liệu
Việc xóa một nhóm cũng sẽ xóa các tài liệu TokenLab chứa trong đó và không thể hoàn tác.
Xác thực người thật
Sử dụng quy trình này khi sản phẩm của bạn cần thu thập sự đồng ý và xác thực khuôn mặt trước khi tái sử dụng người thật làm tham chiếu Seedance.
- Gọi Tạo phiên xác thực hình ảnh với
CallbackURL; lưuResult.BytedTokenvà mởResult.H5Linkcho người đang được xác thực. - Sau khi quy trình H5 chuyển hướng đến callback, hãy thăm dò Lấy kết quả xác thực hình ảnh với cùng
BytedTokenvàProjectName. - Lưu trữ
Result.GroupIdđược trả về. TokenLab tạo và liên kết nhómLivenessFacetrong bước này. - Tạo tài sản với ID nhóm đó, sau đó thăm dò tài sản cho đến khi nó trở thành
ACTIVE.
BytedToken có hiệu lực trong 30 phút. Khách hàng không thể tạo nhóm LivenessFace bằng CreateAssetGroup; điều này ngăn chặn việc một nhóm chưa được xác thực bị trình bày như đã xác thực.
Mở H5Link được trả về ngay sau khi tạo. Hiệu lực của token không có nghĩa là trang xác thực có thể được mở lần đầu tiên vào bất kỳ thời điểm nào trong khoảng thời gian đó.
Đối với nhóm người thật, các tệp tải lên được kiểm tra đối chiếu với khuôn mặt đã xác thực. Một tài sản có thể thất bại nếu nó chứa nhiều khuôn mặt hoặc khuôn mặt không khớp. Để có kết quả tốt nhất, hãy tải lên một tham chiếu toàn thân từ phía trước và một ảnh cận cảnh rõ nét nhìn thẳng.
Tạo và chuẩn bị tài sản
Sử dụng Tạo tài sản tài liệu để nhập từng URL có thể truy cập công khai một lần.
| Loại | Đầu vào được hỗ trợ |
|---|---|
| Hình ảnh | jpeg, png, webp, bmp, tiff, gif, heic, heif; ≤ 30 MiB; chiều rộng và chiều cao [300, 6000] px; tỷ lệ khung hình [0.4, 2.5] |
| Video | mp4, mov; ≤ 200 MiB |
| Âm thanh | aac, wav, mp3; ≤ 15 MiB |
Đây là các giới hạn nhập tệp. Một yêu cầu nhập thành công không đảm bảo rằng phương tiện hoặc xác thực người thật sẽ vượt qua. Hãy đợi trạng thái ACTIVE; nếu tài sản trở thành FAILED, hãy sử dụng error_message để sửa nguồn trước khi nhập lại.
Việc tiếp nhận tài liệu là không đồng bộ. Hãy thăm dò Lấy tài sản tài liệu cho đến khi status trở thành ACTIVE. Thành công HTTP có nghĩa là việc nhập đã được chấp nhận, không có nghĩa là tài sản đã sẵn sàng. Nếu tài sản trở thành FAILED, hãy kiểm tra error_message, sửa nguồn và tạo tài sản mới.
URL nguồn chỉ được sử dụng để nhập. TokenLab trả về ID tài sản của riêng nó và giữ tài sản trong thư viện tài liệu của tổ chức bạn cho đến khi bạn xóa tài sản hoặc nhóm của nó.
Sử dụng tài sản trong tạo video
Sau khi tài sản ở trạng thái ACTIVE, hãy chọn một trong các hình thức sau khi gọi Tạo video:
material_asset_idcho một tham chiếu tài liệu chungmaterial_asset_idscho nhiều tham chiếu chungasset://<asset-id>trongimage_url,start_image,end_imagehoặcreference_imageskhi vai trò phương tiện phải rõ ràng
Các tham chiếu tài liệu được tính vào giới hạn tham chiếu Seedance của mô hình đã chọn. Nếu API trả về Seedance material asset not found or not accessible, hãy xác nhận rằng giá trị đó là ID tài sản thay vì ID nhóm, thuộc cùng tổ chức và dự án, không bị xóa và đang ở trạng thái ACTIVE.
REST hoặc Volcengine Action
Các tích hợp gốc của TokenLab có thể tiếp tục sử dụng các endpoint REST snake_case /v1/videos/assets*. Các khách hàng Volcengine hiện tại có thể giữ nguyên các phần thân PascalCase với Action tài liệu (Tương thích Volc). Cả hai giao diện đều hoạt động trên cùng dữ liệu tài liệu theo phạm vi tổ chức và dự án.
Ví dụ REST: Tài sản Avatar ảo
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","project_name":"default"}'
curl https://api.tokenlab.sh/v1/videos/assets \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"group_id":"group-20260720123456-abc12","asset_url":"https://example.com/reference.png","asset_name":"Front view","asset_type":"Image","project_name":"default"}'
curl https://api.tokenlab.sh/v1/videos/assets/asset-20260720123457-def45?project_name=default \
-H "Authorization: Bearer $TOKENLAB_API_KEY"Ví dụ Action: Tài sản người thật đã xác thực
Trước tiên, hãy tạo và hoàn tất xác thực hình ảnh:
curl 'https://api.tokenlab.sh/?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/?Action=GetVisualValidateResult&Version=2024-01-01' \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"BytedToken":"<BYTED_TOKEN>","ProjectName":"default"}'Sau đó chuyển GroupId được trả về cho 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"
}'Thăm dò bằng GetAsset cho đến khi trạng thái là Active, sau đó chuyển ID tài sản được trả về cho quá trình tạo video. Đối với tất cả 10 thao tác Action, bộ lọc, phân trang, cấu trúc phản hồi và lỗi, hãy xem Action tài liệu (Tương thích Volc).