TokenLab

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ụngViệc cần làm
Một hình ảnh dùng một lầnGử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áchTạ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ậtHoà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ụcTrường RESTTrường ActionÝ nghĩa
Nhóm tài liệugroup_idGroupIdGiữ các tài liệu liên quan cùng nhau
Tài liệuidIdMộ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 ảolibrary_type: "aigc_avatar"GroupType: "AIGC"Không yêu cầu xác thực người thật
Nhóm người thậtlibrary_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ự ánproject_nameProjectNameGiữ 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:

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.

  1. Gọi Tạo phiên xác thực hình ảnh với CallbackURL; lưu Result.BytedToken và mở Result.H5Link cho người đang được xác thực.
  2. 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 BytedToken và ProjectName.
  3. Lưu trữ Result.GroupId được trả về. TokenLab tạo và liên kết nhóm LivenessFace trong bước này.
  4. 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 ảnhjpeg, 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]
Videomp4, mov; ≤ 200 MiB
Âm thanhaac, 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_id cho một tham chiếu tài liệu chung
  • material_asset_ids cho nhiều tham chiếu chung
  • asset://<asset-id> trong image_url, start_image, end_image hoặc reference_images khi 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).

Trên trang này