Seedance 2.0 - 素材ライブラリ（デジタルヒューマン素材管理API）

本ドキュメントは、デジタルヒューマン向けの素材（真人形象 / 虚拟形象）の作成、アップロード、一覧取得、ステータス同期（ポーリング）、更新、削除のAPIをまとめたものです。

---

0. 認証と共通ルール

• 認証：Authorization: Bearer {new-api-token}
• 形式：特記なければ application/json
• 共通レスポンス：
• success: boolean
• message: string（空のことがあります）
• data: object | null

---

1. 概念

1.1 素材コンテナ（Group）

素材コンテナは、素材ファイル（画像/動画/音声など）をまとめて保持する入れ物です。

• group_type
• 1：真人形象（LivenessFace）— 顔認証フローで作成
• 2：虚拟形象（AIGC）— コンテナを直接作成して素材をアップロード

1.2 素材ファイル（Asset）

素材ファイルはコンテナ配下のリーフノードです。アップロード後は通常 Processing(0) となるため、Active(1) または Failed(2) になるまでポーリングしてください。

---

2. データ構造

2.1 UserAssetResponse

素材/素材コンテナの統一レスポンス（主要フィールド）：

• id：resource_id
• asset_type：
• 0：不明
• 1：素材コンテナ
• 2：動画
• 3：画像
• 4：音声
• group_type：コンテナ種別（0/1/2）
• name / description
• status：
• 0：処理中
• 1：利用可能
• 2：失敗（fail_reason を参照）
• is_leaf：
• 0：素材コンテナ
• 1：素材ファイル
• created_at / updated_at：Unix 時間（秒）

---

3. 真人形象（GroupType=1 / LivenessFace）

3.1 真人形象の検証セッション作成

• POST /v1/asset/human/session
• 用途：検証セッションを作成し、検証ページのURLを返します。完了後、ユーザーは redirect_url にリダイレクトされ、結果パラメータが付与されます：
• 成功：status=success&group_id={groupId}
• 失敗：status=failed&reason={reason}

リクエストボディ

必須：redirect_url

{
  "name": "張三の真人形象",
  "description": "デジタルヒューマン動画生成用",
  "redirect_url": "https://your-app.com/asset/callback-result"
}

レスポンス例

{
  "success": true,
  "data": {
    "Url": "https://xxx.volccdn.com/verify?token=xxx",
    "H5Link": "https://xxx.volccdn.com/verify?token=xxx",
    "BytedToken": "byted_token_abc123"
  }
}

---

4. 虚拟形象（GroupType=2 / AIGC）

4.1 虚拟形象コンテナ作成

• POST /v1/asset/human/aigc
• 用途：コンテナを作成し GroupId を返します。作成後、/v1/asset/human/upload で素材をアップロードします。

リクエストボディ

必須：name

{
  "name": "バーチャル配信者A",
  "description": "ライブコマース向け AIGC 素材"
}

レスポンス例

{
  "success": true,
  "data": {
    "GroupId": "group_abc123"
  }
}

---

5. 共通API（一覧 / ステータス同期 / 更新 / 削除）

5.1 素材ファイルのアップロード

• POST /v1/asset/human/upload
• 用途：指定コンテナに素材（画像/動画/音声）をアップロードします。
• 注意：
• アップロード後は Processing(0) になるため、Active(1) / Failed(2) までポーリングしてください
• group_id は当該トークンのユーザーに所属している必要があります

リクエストボディ

必須：group_id、url、asset_type

asset_type enum： - Image - Video - TrainingVideo - Script - Audio

{
  "group_id": "group_abc123",
  "url": "https://cdn.example.com/video/demo.mp4",
  "asset_type": "Video",
  "name": "デモ動画",
  "description": "デジタルヒューマン動画生成用"
}

レスポンス例

data は UserAssetResponse（初期状態は Processing が一般的です）。

{
  "success": true,
  "message": "",
  "data": {
    "id": "asset_xyz789",
    "asset_type": 2,
    "group_type": 1,
    "name": "デモ動画",
    "description": "デジタルヒューマン動画生成用",
    "status": 0,
    "fail_reason": "",
    "is_leaf": 1,
    "created_at": 1714000000,
    "updated_at": 1714000000
  }
}

5.2 素材一覧の取得

• GET /v1/asset/human/list
• 用途：ユーザーの素材一覧を取得します。group_id で絞り込み可能です。
• クエリ：
• group_id（任意）
• is_leaf（任意）：1 素材ファイル（デフォルト）、0 コンテナ
• p（任意）：ページ（デフォルト 1）
• page_size（任意）：件数（デフォルト 20）

リクエスト例

curl "https://api.agtcloud.ai/v1/asset/human/list?group_id=group_abc123&is_leaf=1&p=1&page_size=20" \
  -H "Authorization: Bearer $API_KEY"

5.3 素材ステータスの同期（ポーリング）

• GET /v1/asset/human/get/{id}
• 用途：単一素材の最新ステータスを同期して返します（アップロード後のポーリング向け）。
• パス：
• id：素材の resource_id（レスポンスの id）

リクエスト例

curl "https://api.agtcloud.ai/v1/asset/human/get/asset_xyz789" \
  -H "Authorization: Bearer $API_KEY"

5.4 素材情報の更新

• PUT /v1/asset/human/update/{id}
• 用途：name と description を更新します。

{
  "name": "更新後のデモ動画",
  "description": "新しい説明"
}

5.5 素材/コンテナの削除

• DELETE /v1/asset/human/delete/{id}
• 用途：素材ファイルまたはコンテナを削除します。
• 挙動（対象リソースの is_leaf による）：
• is_leaf=0（コンテナ）：配下素材も含めて削除
• is_leaf=1（素材ファイル）：単体削除

curl -X DELETE "https://api.agtcloud.ai/v1/asset/human/delete/group_abc123" \
  -H "Authorization: Bearer $API_KEY"