Seedance API で Seedance Private Assets を使う方法

PiAPI は、再利用可能な参照素材をアップロードし、あとから asset://<asset_id> で呼び出せる Seedance API ワークフロー、Seedance Private Asset Library に対応しました。

Seedance Private Asset Library では、顔、キャラクター、商品、シーン、動画、音声などの参照をアップロードし、Seedance API タスクで再利用できます。これは参照の再利用やキャラクター一貫性のための機能であり、従来型の face swap、inpainting、ピクセル単位の画像編集ではありません。

重要ポイント

• 顔、キャラクター、商品などの被写体を複数の動画生成で使い回す場合は private asset を使います。
• 一度だけ使う背景、シーン、小物、参照画像には通常の URL を使います。
• ユーザー提供の一時参照を単発タスクで取り込む場合は auto_upload_assets: true を使います。
• private asset は Seedance タスクで参照する前に Active になる必要があります。
• asset:// 参照は seedance-2-less-restriction と seedance-2-fast-less-restriction で使えます。strict 系 task type では使えません。

クイック回答

Seedance private assets は、Seedance API で再利用する参照素材に最適です。参照を一度アップロードし、Active になるまで待ち、その後の動画タスクで asset://<asset_id> として呼び出します。

Seedance Private Assets とは

Seedance private assets は、動画生成の前にアプリケーションから PiAPI にアップロードする再利用可能なファイルです。アップロード後、PiAPI は asset_id を返します。asset が Active になると、Seedance API リクエストで次の形式で参照できます。endpoint、quota、ライフサイクルの詳細は Private Asset Library docs を確認してください。

asset://<asset_id>

同じ顔写真、キャラクター画像、商品写真、動画クリップ、音声参照を毎回送る代わりに、一度だけアップロードし、複数タスクで asset ID を再利用します。

private asset は、Seedance 動画生成のための再利用可能な参照です。

何を解決するのか

AI 動画生成では、同じ被写体を複数の prompt、シーン、クリエイティブバリエーションで一貫させたい場合に難しさが出ます。通常の画像 URL は単発タスクでは便利ですが、何度も使う参照には向いていません。

よくある用途は、同じ人物やキャラクターの一貫性維持、avatar や creator 向け動画プロダクト、広告バリエーションでの商品参照の再利用、短編ストーリーでの安定したキャスト、固定の人物や商品と変わる背景の組み合わせ、backend での重複 upload 削減などです。

モデル全体を先に理解したい場合は、Seedance 2.0 API guide から読むとスムーズです。

Private Assets ではないもの

Seedance Private Asset Library は、face swap、inpainting、正確な写真合成として説明すべきものではありません。人物写真と風景画像を渡した場合、Seedance はそれらを生成の参照として使います。結果は参照に導かれた生成動画であり、既存写真へのピクセル単位の挿入ではありません。

Private Assets vs Raw URL vs Auto-Upload

シンプルな判断基準は、後で再利用するなら private asset、一度だけなら raw URL または auto-upload です。

ワークフロー

1. 再利用する参照をアップロードします。
2. asset status が Active になるまで待ちます。
3. image_urls、video_urls、audio_urls に asset://<asset_id> を入れて Seedance タスクを送信します。
4. prompt 内では Image 1、Image 2、Video 1、Audio 1 のように入力順を明示します。
5. 出力動画が完成するまで Seedance タスクを poll します。

順序は重要です。image_urls の最初が private asset、二番目が風景 URL なら、Image 1 は private asset、Image 2 は背景です。

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

prompt では次のように書けます。

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

例: 人物 asset と風景画像を組み合わせる

人物写真を private asset としてアップロードし、風景写真を raw URL として渡し、Seedance に両方の参照を使った動画生成を依頼できます。これは生成動画であり、正確な写真合成ではありません。

{
  "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."
}

API 例

Step 1: private asset をアップロード

ソース URL は、PiAPI が fetch と ingest を行う間、公開状態で到達可能である必要があります。最低 24 時間は有効にしておくのが安全です。

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"}'

Step 2: asset status を確認

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

Processing の場合は待って再確認します。Failed の場合はエラーを確認し、修正したファイルをアップロードしてください。

Step 3: `asset://` で Seedance タスクを送信

seedance-2-less-restriction または seedance-2-fast-less-restriction を使います。seedance-2 や seedance-2-fast などの strict 版は asset:// 参照をサポートしません。

一度きりの参照には Auto-Upload

参照が一回だけ必要な場合は auto_upload_assets: true を使います。PiAPI は asset:// ではない URL を一時的に取り込み、タスクで使い、retention window 後にクリーンアップできます。

Best Practices

• 複数回使う顔、主要キャラクター、商品、ブランド被写体に private assets を使う。
• 一度だけ使う背景は raw URL のままにする。
• prompt では Image 1、Image 2、Video 1、Audio 1 を明確に使う。
• 生成前に Active を待つ。
• quota、TTL、ユーザー参照の権利と同意を設計する。

よくあるミス

strict task type を使う

seedance-2 は asset:// と一緒に使えません。less-restriction 版を使ってください。

asset を早すぎるタイミングで参照する

正しい流れは upload asset -> status poll -> Active を待つ -> Seedance task 送信です。

すべての背景を asset にする

private asset slot は、複数タスクで一貫性が必要な参照に使いましょう。

FAQ

Seedance private asset とは？

Seedance 動画生成のために PiAPI にアップロードする再利用可能な参照です。Active になると asset://<asset_id> で使えます。

顔写真を再利用できますか？

はい。ただし参照ガイド付き生成であり、正確な face swap を保証するものではありません。

face swap と同じですか？

いいえ。目的は生成動画内の人物や被写体の一貫性です。

まとめ

Seedance Private Asset Library は、Seedance API で再利用可能な参照ワークフローを構築するための整理された方法です。参照をアップロードし、Active を確認してから、asset、prompt、必要な raw URL を含む seedance-2-less-restriction タスクを送信します。API key を接続する準備ができたら、Seedance workspace で試せます。

Sources:

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