Cách dùng Seedance Private Assets với Seedance API

PiAPI hiện hỗ trợ Seedance Private Asset Library, một quy trình mới trong Seedance API để tải lên các tham chiếu có thể tái sử dụng và gọi lại bằng asset://<asset_id>.

Seedance Private Asset Library cho phép bạn tải lên các tham chiếu như khuôn mặt, nhân vật, sản phẩm, cảnh, video hoặc âm thanh, rồi dùng lại trong các tác vụ Seedance API. Tính năng này phù hợp nhất cho workflow cần tham chiếu lặp lại và giữ nhất quán nhân vật, không phải face swap truyền thống, inpainting hay chỉnh sửa ảnh chính xác từng pixel.

Ý chính

• Dùng private asset khi một khuôn mặt, nhân vật, sản phẩm hoặc chủ thể cần xuất hiện trong nhiều video trong tương lai.
• Dùng URL thô cho cảnh nền, đạo cụ hoặc ảnh tham chiếu chỉ dùng một lần.
• Dùng auto_upload_assets: true khi tham chiếu do người dùng cung cấp chỉ cần nhập tạm cho một tác vụ.
• Private asset phải có trạng thái Active trước khi được tham chiếu trong tác vụ Seedance.
• Tham chiếu asset:// hoạt động với seedance-2-less-restriction và seedance-2-fast-less-restriction, không dùng với các task type Seedance strict.

Câu trả lời nhanh

Seedance private assets phù hợp nhất cho các tham chiếu có thể tái sử dụng trong Seedance API. Tải tham chiếu lên một lần, chờ trạng thái Active, rồi gọi trong các tác vụ video sau bằng asset://<asset_id>. Hãy dùng cho khuôn mặt, nhân vật, sản phẩm, cảnh, video clip hoặc âm thanh xuất hiện nhiều lần.

Seedance Private Assets là gì?

Seedance private assets là các tệp có thể tái sử dụng mà ứng dụng của bạn tải lên PiAPI trước khi tạo video. Sau khi tải lên, PiAPI trả về asset_id. Khi asset chuyển sang Active, request Seedance API có thể tham chiếu nó bằng định dạng dưới đây. Chi tiết endpoint, quota và vòng đời nằm trong Private Asset Library docs.

asset://<asset_id>

Thay vì gửi lại cùng một ảnh khuôn mặt, ảnh nhân vật, ảnh sản phẩm, video clip hoặc âm thanh nhiều lần, bạn tải lên một lần rồi dùng lại private asset ID qua nhiều tác vụ.

Mô hình tư duy quan trọng rất đơn giản:

Private asset là tham chiếu có thể tái sử dụng cho tạo video bằng Seedance.

Private assets giải quyết vấn đề gì?

AI video generation thường gặp khó khi người dùng muốn cùng một chủ thể xuất hiện qua nhiều prompt, cảnh hoặc biến thể sáng tạo. URL ảnh thô có thể giúp cho một tác vụ, nhưng không lý tưởng khi cần dùng lại nhiều lần.

Các trường hợp phổ biến gồm giữ cùng một người hoặc nhân vật nhất quán qua nhiều video, xây dựng sản phẩm avatar hoặc influencer, tái sử dụng ảnh sản phẩm cho nhiều biến thể quảng cáo, giữ dàn nhân vật ổn định cho phim ngắn, kết hợp người hoặc sản phẩm cố định với nền thay đổi, và giảm việc upload lặp lại ở backend.

Trước khi đi sâu hơn, bạn có thể xem tổng quan mô hình tại Seedance 2.0 API guide.

Private Assets không phải là gì

Seedance Private Asset Library không nên được mô tả như face swap cổ điển, inpainting hoặc ghép ảnh chính xác. Nếu bạn tải ảnh một người và ảnh phong cảnh, tác vụ Seedance dùng chúng làm tham chiếu tạo sinh. Nó không đảm bảo người đó sẽ được chèn vào nền với kiểm soát từng pixel.

Seedance private assets hỗ trợ tạo video theo tham chiếu với các chủ thể có thể tái sử dụng.

Nếu sản phẩm của bạn cần thay thế ảnh chính xác, masking hoặc face swap, API chỉnh sửa ảnh hoặc face swap chuyên dụng có thể phù hợp hơn. Nếu cần người, nhân vật, sản phẩm hoặc cảnh lặp lại trong video tạo sinh, private assets là workflow Seedance nên đánh giá.

Private Assets vs URL thô vs Auto-Upload

Quy tắc đơn giản: nếu tham chiếu sẽ được dùng lại về sau, hãy biến nó thành private asset. Nếu chỉ cần một lần, giữ dạng URL thô hoặc dùng auto-upload mode.

Workflow Seedance Private Asset hoạt động thế nào

1. Tải lên tham chiếu có thể tái sử dụng.
2. Chờ trạng thái asset chuyển thành Active.
3. Gửi tác vụ Seedance với asset://<asset_id> trong image_urls, video_urls hoặc audio_urls.
4. Gọi input trong prompt theo thứ tự như Image 1, Image 2, Video 1 hoặc Audio 1.
5. Poll tác vụ Seedance cho đến khi video hoàn tất.

Thứ tự tham chiếu trong prompt rất quan trọng. Nếu image_urls có private asset ở vị trí đầu và ảnh nền ở vị trí thứ hai, Image 1 là private asset và Image 2 là URL ảnh nền.

{
  "image_urls": [
    "asset://asset-20260607154123-aaaa1",
    "https://your-cdn.com/scenic-background.jpg"
  ]
}

Trong prompt, bạn có thể viết:

Image 1 is the person reference. Image 2 is the scenic background.

Ví dụ: dùng person asset với ảnh phong cảnh

Có, bạn có thể tải ảnh một người thành Seedance private asset, truyền ảnh phong cảnh dưới dạng URL thô, và yêu cầu Seedance tạo video dựa trên cả hai tham chiếu. Kết quả là video tạo sinh có hướng dẫn bằng tham chiếu, không phải ghép ảnh chính xác.

{
  "image_urls": [
    "asset://asset-person-reference",
    "https://your-cdn.com/scenic-background.jpg"
  ],
  "prompt": "Image 1 is the person reference. Image 2 is the scenic background. Generate a cinematic 5-second video of the person from Image 1 standing naturally in the location from Image 2."
}

Ví dụ API: tải lên và sử dụng Seedance Private Asset

Bước 1: tải lên private asset

URL nguồn phải truy cập công khai trong lúc PiAPI fetch và ingest file. Giữ URL hoạt động ít nhất 24 giờ là lựa chọn an toàn.

curl --request POST "https://api.piapi.ai/api/v1/asset/upload" \
  --header "X-API-Key: $PIAPI_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://your-cdn.com/person-reference.jpg",
    "asset_type": "Image",
    "name": "main-character"
  }'

Bước 2: kiểm tra trạng thái asset

curl --request GET "https://api.piapi.ai/api/v1/asset/list?status=active,processing,failed" \
  --header "X-API-Key: $PIAPI_API_KEY"

Nếu asset vẫn Processing, hãy chờ rồi kiểm tra lại. Nếu Failed, xem lỗi và tải lên file đã sửa.

Bước 3: gửi Seedance task với `asset://`

curl --request POST "https://api.piapi.ai/api/v1/task" \
  --header "X-API-Key: $PIAPI_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedance",
    "task_type": "seedance-2-less-restriction",
    "input": {
      "prompt": "Image 1 is the person reference. Image 2 is the scenic background. Generate a cinematic 5-second video of the person from Image 1 standing naturally in the location from Image 2.",
      "image_urls": ["asset://asset-20260607154123-aaaa1", "https://your-cdn.com/scenic-background.jpg"],
      "aspect_ratio": "16:9",
      "duration": 5,
      "resolution": "720p"
    }
  }'

Ví dụ này dùng seedance-2-less-restriction, task type hỗ trợ asset://. Bạn cũng có thể dùng seedance-2-fast-less-restriction. Các task type strict như seedance-2 và seedance-2-fast không hỗ trợ private asset references.

Auto-Upload Mode cho tham chiếu dùng một lần

Private assets phù hợp cho tham chiếu dùng lại. Nếu tham chiếu chỉ cần cho một tác vụ, hãy dùng auto-upload mode. Với auto_upload_assets: true, PiAPI có thể nhập tạm URL không phải asset://, dùng cho tác vụ, rồi dọn sau retention window.

Best Practices

• Dùng private assets cho khuôn mặt, nhân vật chính, sản phẩm hoặc chủ thể thương hiệu cần nhất quán.
• Giữ nền chỉ dùng một lần ở dạng URL thô.
• Viết prompt bằng nhãn rõ ràng như Image 1, Image 2, Video 1 hoặc Audio 1.
• Chờ Active trước khi tạo video.
• Dùng seedance-2-less-restriction hoặc seedance-2-fast-less-restriction.
• Quản lý quota, TTL và quyền sử dụng dữ liệu người dùng một cách có chủ đích.

Lỗi thường gặp

Lỗi 1: dùng strict task type

seedance-2 và seedance-2-fast không hoạt động với asset://. Hãy dùng các biến thể less-restriction.

Lỗi 2: tham chiếu asset quá sớm

Hãy dùng flow: upload asset -> poll trạng thái -> chờ Active -> gửi Seedance task.

Lỗi 3: biến mọi background thành managed asset

Không phải ảnh nào cũng nên thành private asset. Hãy dành slot private asset cho tham chiếu cần nhất quán qua nhiều tác vụ.

Lỗi 4: xem private assets như chỉnh sửa ảnh chính xác

Private assets hướng dẫn quá trình tạo video. Chúng không đảm bảo chèn người vào ảnh với độ chính xác từng pixel.

FAQ

Seedance private asset là gì?

Đó là tham chiếu có thể tái sử dụng được tải lên PiAPI cho tạo video bằng Seedance. Khi asset Active, bạn có thể gọi lại bằng asset://<asset_id>.

Tôi có thể tải ảnh khuôn mặt và dùng lại trong Seedance không?

Có. Hãy coi đây là tạo video theo tham chiếu, không phải face swap hoặc chỉnh sửa ảnh chính xác.

Private Asset Library có giống face swap không?

Không. Mục tiêu là giữ nhất quán nhân vật hoặc chủ thể trong video tạo sinh.

Kết luận

Seedance Private Asset Library giúp developer xây dựng workflow tham chiếu tái sử dụng gọn hơn với Seedance API. Hãy tải lên một tham chiếu, xác nhận nó Active, rồi gửi tác vụ seedance-2-less-restriction dùng asset cùng prompt và các URL thô dùng một lần. Khi sẵn sàng kết nối API key, bạn có thể thử Seedance trong Seedance workspace.

Nguồn:

• PiAPI Private Asset Library docs: https://piapi.ai/docs/seedance-api/private-asset
• Seedance 2.0 arXiv page: https://arxiv.org/abs/2604.14148