> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Doubao 実在人物の素材利用ガイド

> 本人による Web ページでの確認を通じて実在人物の素材を作成し、asset:// 参照で Doubao Seedance の動画を生成するほか、素材の照会、再試行、削除を行います。

実在人物の素材は、本人が確認済みの人物の姿を動画内で参照するために使用します。素材グループの作成、本人による Web ページでの確認、素材の追加、素材が利用可能になるまでの待機、動画生成タスクの送信という順序で進めます。

本ページでは画像素材を例に、AIHubMix API で素材を管理し、新版の `/ai/v1/videos` を優先して動画を生成します。既存の `/v1/videos` クライアントについては、[互換プロトコルの例](#compatible-video)を参照してください。

<h2 id="prerequisites">
  前提条件
</h2>

* 有効な AIHubMix API Key を用意し、環境変数 `AIHUBMIX_API_KEY` から読み取ります。
* 新版の動画 API を使用する前に、コンソールで[非同期タスク](/jp/api/async-tasks)を有効にし、アカウントに十分な残高と対象モデルの利用権限があることを確認します。
* 素材に写る本人が用途に同意し、Web ページでの確認手続きを本人自身で完了する必要があります。同じ素材グループには、同一人物の素材のみを追加します。
* モデルプロバイダーが読み取れる画像の直接リンクを用意し、素材の処理中もリンクが有効であることを確認します。
* コマンドラインの例には Bash、curl、jq が必要です。同じターミナルで順番に実行し、返された素材グループ、確認セッション、素材、動画タスクの ID を保持してください。

<Note>
  BytePlus 公式の実在人物の素材ガイドは Seedance 2.0 と Seedance 2.5 を対象としています。本ページの新版動画の主な例では、本番環境での検証が完了した AIHubMix モデル ID `doubao-seedance-2-5-260628` を使用します。具体的なバージョン、参照メディアの種類、パラメータは、現在のモデル Schema とアカウントで利用可能な機能を基準にしてください。検証範囲は[今回のフロー検証](#verified-flow)を参照してください。この結果から、すべての Seedance バージョンで実在人物の素材を利用できると判断しないでください。
</Note>

ターミナル環境を準備します。API Key は実行環境からあらかじめ設定されている必要があります。

```bash theme={null}
set -euo pipefail
: "${AIHUBMIX_API_KEY:?请先配置 AIHUBMIX_API_KEY 环境变量}"
BASE_URL="https://aihubmix.com"
MODEL="doubao-seedance-2-5-260628"
```

<h2 id="create-group">
  1. 素材グループを作成する
</h2>

```bash theme={null}
GROUP_JSON=$(curl --fail-with-body -sS --max-time 60 \
  -X POST "$BASE_URL/ai/v1/asset-groups" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"我的真人素材"}')
printf '%s\n' "$GROUP_JSON" | jq .
GROUP_ID=$(printf '%s' "$GROUP_JSON" | jq -er '.id')
```

リクエストボディで受け付けるのは `name` のみです。名前は空にできず、最大 100 文字です。作成に成功すると HTTP `201` が返され、初期ステータスは `pending_auth` になります。

素材グループの公開フィールドは `id`、`object`、`name`、`status`、`created_at`、`updated_at` です。`object` は `asset_group` 固定で、時刻フィールドは Unix 秒です。その後、`status=active` で素材を追加できる状態になったことを判断します。

作成レスポンスを受け取れなかった場合は、重複して作成することを避けるため、まず一覧を照会してください。

```bash theme={null}
curl --fail-with-body -sS "$BASE_URL/ai/v1/asset-groups?limit=20" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq .
```

一覧は `data`、`has_more`、`next_after` を返します。次のページでは `after=前のページのnext_after` を渡します。`limit` のデフォルトは `20`、最大は `100` です。名前は冪等性の識別子として使用されないため、ID と作成時刻を併せて素材グループを識別してください。

<h2 id="create-verification">
  2. 本人確認リンクを取得する
</h2>

確認セッションを作成します。リクエストボディは不要です。

```bash theme={null}
SESSION_JSON=$(curl --fail-with-body -sS --max-time 60 \
  -X POST "$BASE_URL/ai/v1/asset-groups/$GROUP_ID/verification-sessions" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY")
SESSION_ID=$(printf '%s' "$SESSION_JSON" | jq -er '.id')
printf '%s' "$SESSION_JSON" | jq '{id, status, expires_at, verification_url}'
```

作成に成功すると HTTP `201` が返されます。公開フィールドは `id`、`object`、`group_id`、`status`、`created_at`、`expires_at`、`completed_at` です。`object` は `verification_session` 固定で、時刻フィールドは Unix 秒、未完了時の `completed_at` は `null` です。

<Warning>
  `verification_url` は作成成功時のレスポンスでのみ返され、その後の照会ではリンクは再び返されません。速やかに素材に写る本人へリンクを渡し、公開ログ、コードリポジトリ、問い合わせのスクリーンショットには含めないでください。有効期限は `expires_at` を基準とし、期限切れ後は元のリンクを使用できません。
</Warning>

本人が `verification_url` を開き、ページに表示される主体と用途を確認し、関連する規約を読んで同意したうえで、ページの案内に従って操作を完了します。BytePlus の公式ガイドでは、この手続きには個人の BytePlus アカウントへのログインが必要とされています。ページでカメラへのアクセス許可を求められた場合は、本人が端末を操作して許可してください。

公式ページには素材のアップロードなどの手順が含まれる場合があります。実際の案内に従って完了してください。その後、本ページの API による素材作成手順も実行し、AIHubMix が返す素材 ID を取得する必要があります。Web ページに表示された別の素材 ID を、そのまま API の例に代入しないでください。

<h2 id="check-verification">
  3. 確認結果を照会する
</h2>

```bash theme={null}
curl --fail-with-body -sS "$BASE_URL/ai/v1/verification-sessions/$SESSION_ID" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq .

curl --fail-with-body -sS "$BASE_URL/ai/v1/asset-groups/$GROUP_ID" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq .
```

| セッションのステータス | 次の手順                                               |
| ----------- | -------------------------------------------------- |
| `creating`  | セッションを作成中です。しばらくしてから照会し、完了しない状態が続く場合はサポートに連絡してください |
| `pending`   | 本人による操作の完了、または結果の確認を待っています。しばらくしてから再度照会してください      |
| `verified`  | 本人による確認が完了しています。続いて素材グループが `active` であることを確認してください |
| `rejected`  | 今回は承認されませんでした。Web ページの案内を確認してから再度開始してください          |
| `expired`   | 今回のセッションは期限切れです。確認手続きを再度開始してください                   |
| `failed`    | 今回のセッションは失敗しました。エラーの案内を確認し、必要に応じてサポートに連絡してください     |

クライアントは 10 から 15 秒ごとに照会し、ローカルでの待機時間に上限を設定できます。この間隔は利用上の推奨値です。Web ページに完了が表示された場合や空白のページが返された場合も、API でセッションが `verified`、素材グループが `active` であることを確認してから素材を追加してください。

再作成時に `409 verification_session_active` が返された場合は、まず既存のセッションと素材グループを照会してください。有効なセッションが存在する場合、素材グループの確認が完了している場合、または前回の結果が確認待ちの場合は、繰り返し新規作成しないでください。完了しない状態が続く場合は[サポート](/jp/FAQs/Feedback)に連絡してください。

<Warning>
  Web ページの `internal error` は、確認セッションの終了を意味しません。まず本節の 2 つの GET リクエストでセッションと素材グループを照会してください。セッションがまだ `pending` の場合は、同じグループのセッションを繰り返し作成しないでください。セッションが `verified` かつ素材グループが `active` の場合にのみ、素材の追加に進んでください。Web ページのエラーだけでは原因を判断できません。完了しない状態が続く場合は、ID を保持してサポートに連絡してください。
</Warning>

<h2 id="create-asset">
  4. 画像 URL から素材を作成する
</h2>

<h3 id="image-requirements">
  画像の準備
</h3>

画像ファイルを返す絶対 HTTP(S) URL を指定します。HTTPS を推奨します。リンクはログインや追加のリクエストヘッダーなしで読み取れる必要があります。ローカルパス、プライベートネットワークのアドレス、Base64、ユーザー名とパスワードを含む URL は、素材作成 API では使用できません。URL に `#` フラグメントを含めないでください。

[BytePlus の実在人物の素材ガイド](https://docs.byteplus.com/en/docs/ModelArk/2315856)では、鮮明な正面写真が推奨され、素材の登録には以下の要件を満たす必要があります。

| 項目         | 要件                                   |
| ---------- | ------------------------------------ |
| 形式         | JPEG、PNG、WebP、BMP、TIFF、GIF、HEIC、HEIF |
| 1 枚あたりのサイズ | 30 MB 未満                             |
| アスペクト比     | 0.4 より大きく、2.5 より小さい                  |
| 幅と高さ       | どちらも 300 ピクセルより大きく、6000 ピクセルより小さい    |
| 人物         | その素材グループで確認を完了した人物と一致すること            |

上記は公式の素材ライブラリの要件です。動画モデルには参照素材に対する独自の制限がある場合もあります。アップロード前に対象モデルの要件も確認してください。HTTP による作成が成功しても、素材の処理が完了したことを意味しません。

<h3 id="asset-request">
  作成リクエスト
</h3>

`IMAGE_URL` を、本人から利用への同意を得た画像の直接リンクに変更してください。例のドメインはプレースホルダーであり、実在人物の画像は提供していません。

```bash theme={null}
IMAGE_URL="https://cdn.example.com/portrait.jpg"
ASSET_KEY="portrait-image-001"
ASSET_BODY=$(jq -n --arg url "$IMAGE_URL" --arg ref "$ASSET_KEY" \
  '{url: $url, asset_type: "image", client_reference_id: $ref}')
ASSET_JSON=$(curl --fail-with-body -sS --max-time 60 \
  -X POST "$BASE_URL/ai/v1/asset-groups/$GROUP_ID/assets" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $ASSET_KEY" \
  -d "$ASSET_BODY")
printf '%s\n' "$ASSET_JSON" | jq .
ASSET_ID=$(printf '%s' "$ASSET_JSON" | jq -er '.id')
```

| リクエストフィールド            | 必須  | 説明                                             |
| --------------------- | --- | ---------------------------------------------- |
| `url`                 | はい  | アクセス可能な素材ファイルの URL                             |
| `asset_type`          | はい  | `image`、`video`、`audio` のいずれか。本例では `image` を使用 |
| `client_reference_id` | いいえ | アプリケーション側の素材識別子。最大 128 バイト                     |

リクエストボディで受け付けるのは上記の 3 フィールドのみです。`Idempotency-Key` は任意のリクエストヘッダーで、最大 128 バイトです。先頭と末尾の空白、および制御文字は使用できません。音声と動画のファイル制限は上記の公式ガイドを参照し、対象モデルが対応する種類と長さを確認してください。

初回作成では通常 HTTP `201`、既存素材を再利用する場合は `200`、結果が確認待ちでステータスが `reconciling` の場合は `202` が返されます。常にオブジェクトの `status` を読み取ってください。

素材の公開フィールドは `id`、`object`、`group_id`、`asset_type`、`status`、`client_reference_id`、`created_at`、`updated_at`、`deleted_at` です。`object` は `asset` 固定です。未指定または削除済みの `client_reference_id` は返されず、未削除時の `deleted_at` は `null` です。時刻フィールドは Unix 秒です。照会では元の画像 URL は返されないため、アプリケーション側で記録を保持してください。

<h2 id="wait-active">
  5. 素材が利用可能になるまで待つ
</h2>

```bash theme={null}
curl --fail-with-body -sS "$BASE_URL/ai/v1/assets/$ASSET_ID" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq .
```

| 素材のステータス      | 意味と対処                                    |
| ------------- | ---------------------------------------- |
| `creating`    | 作成がまだ完了していません。ID を保持し、しばらくしてから照会してください   |
| `processing`  | 処理中です。照会を続けてください                         |
| `active`      | 動画の参照素材として利用できます                         |
| `failed`      | 素材の処理に失敗しました。画像と人物の一致に関する要件を確認してください     |
| `reconciling` | 作成または削除の結果が確認待ちです。照会を続け、動画にはまだ使用しないでください |
| `deleting`    | 削除処理中です。動画には使用しないでください                   |
| `deleted`     | 削除が完了しています。動画には使用できません                   |

10 から 15 秒ごとに照会し、ローカルでの待機時間に上限を設定できます。ローカルのポーリングを停止しても、サーバー側の操作はキャンセルされません。

<Warning>
  作成結果が不明で、一致する結果が見つからない状態が続く場合、素材が `reconciling` のままになることがあり、素材や素材グループの削除にも影響する場合があります。ID と元のリクエスト識別子を保持してサポートに連絡してください。識別子を変更して繰り返し作成したり、一定時間待てば自動的に削除されると想定したりしないでください。
</Warning>

<h2 id="generate-video">
  6. 素材を使用して動画を生成する
</h2>

動画の参照には、AIHubMix の素材作成レスポンスに含まれる完全な `id` を使用します。形式は `asset://<asset_id>` です。同じリクエストで参照するすべての素材は、同一の素材グループに属し、現在のアカウントが所有し、いずれも `active` である必要があります。素材グループも利用可能な状態を維持している必要があります。

| 素材の種類   | 新版の `input_references[].type` | 互換版のネストされたフィールド |
| ------- | ----------------------------- | --------------- |
| `image` | `image_url`                   | `image_url.url` |
| `video` | `video_url`                   | `video_url.url` |
| `audio` | `audio_url`                   | `audio_url.url` |

参照の種類は、素材作成時の `asset_type` と一致する必要があります。`asset://` は動画の参照フィールドで使用します。ブラウザーでのダウンロード用アドレスとしては使用できません。

<h3 id="native-video">
  新版の動画プロトコル
</h3>

まずエンドポイントのパスで現在のモデル Schema を確認します。

```bash theme={null}
curl --fail-with-body -sS "$BASE_URL/call/schema/models/$MODEL/endpoints" \
  | jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema'
```

モデルが参照画像に対応していることを確認してから送信します。以下では、今回の本番環境での検証に成功した Seedance 2.5 のパラメータ `duration=4`、`resolution="480p"`、`aspect_ratio="3:4"`、`generate_audio=false` を使用します。新版では `input_references[].url` を直接使用します。`ASSET_ID` は、前の手順で AIHubMix が返した素材 ID です。

```bash theme={null}
VIDEO_BODY=$(jq -n --arg model "$MODEL" --arg asset "asset://$ASSET_ID" \
  '{model: $model,
    prompt: "The person in the reference image smiles and waves at the camera.",
    duration: 4,
    resolution: "480p",
    aspect_ratio: "3:4",
    generate_audio: false,
    input_references: [{type: "image_url", url: $asset}]}')
VIDEO_JSON=$(curl --fail-with-body -sS --max-time 120 \
  -X POST "$BASE_URL/ai/v1/videos" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$VIDEO_BODY")
printf '%s\n' "$VIDEO_JSON" | jq .
VIDEO_ID=$(printf '%s' "$VIDEO_JSON" | jq -er '.id')
export VIDEO_ID
```

新版では整数の `duration` でリクエストする長さを指定します。その他の許容値はモデル Schema を基準にしてください。`resolution="480p"` はリクエストする解像度の区分であり、出力の幅または高さが 480 ピクセルに固定されることを保証するものではありません。実際の寸法は生成ファイルを基準にしてください。最初と最後のフレームには `frame_images[].image_url.url` を使用し、併せて `frame_type` を設定できます。対応する機能をモデルがサポートしている場合にのみ使用してください。パラメータの詳細は[動画生成](/jp/api/aihubmix-video-generation)を参照してください。

<h3 id="compatible-video">
  互換動画プロトコル
</h3>

既存のクライアントで `/v1/videos` を使用する場合は、参照を `content` または `extra_body.content` に配置し、URL を対応するメディアオブジェクト内にネストします。本例では `extra_body.content` を使用します。

<Note>
  互換版の例は `doubao-seedance-2-0-260128` を維持し、既存の互換 API の仕様と BytePlus 公式の素材参照に関する説明に基づいて記載しています。今回、Seedance 2.0 の動画生成と `/v1/videos` による互換版の作成は実測していません。新版 Seedance 2.5 の検証結果を、この例にそのまま適用することはできません。
</Note>

```bash theme={null}
COMPAT_MODEL="doubao-seedance-2-0-260128"
COMPAT_BODY=$(jq -n --arg model "$COMPAT_MODEL" --arg asset "asset://$ASSET_ID" \
  '{model: $model,
    prompt: "The person in the reference image smiles and waves at the camera.",
    extra_body: {content: [{type: "image_url", image_url: {url: $asset}, role: "reference_image"}]}}')
curl --fail-with-body -sS --max-time 120 \
  -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$COMPAT_BODY" | jq .
```

2 種類の例からいずれか一方を選んで実行してください。動画の作成は毎回独立したリクエストです。互換リクエストに `input_references` を混在させないでください。両方の場所に `content` を指定すると、`extra_body.content` がトップレベルの `content` を上書きします。指定は一方のみにすることを推奨します。

互換版が返す `id` は `GET /v1/videos/{id}` での照会に使用し、完了後は `GET /v1/videos/{id}/content` でダウンロードしてください。互換版の ID を `/ai/v1/videos` の照会に使用しないでください。詳細は[互換動画 API](/jp/api/Video-Gen)を参照してください。

<h2 id="poll-download">
  7. 新版の動画をポーリングしてダウンロードする
</h2>

以下の Python の例は、前述の新版の作成手順にのみ続くものです。環境変数の `VIDEO_ID` を読み取り、タスクは再作成しません。`requests` のインストールが必要です。

```python theme={null}
import os
import time
from pathlib import Path

import requests

base_url = "https://aihubmix.com"
video_id = os.environ["VIDEO_ID"]
headers = {"Authorization": f"Bearer {os.environ['AIHUBMIX_API_KEY']}"}
deadline = time.monotonic() + 1800

while time.monotonic() < deadline:
    response = requests.get(
        f"{base_url}/ai/v1/videos/{video_id}", headers=headers, timeout=30
    )
    response.raise_for_status()
    task = response.json()
    status = task["status"]
    if status == "completed":
        break
    if status in {"failed", "cancelled"}:
        raise RuntimeError(f"视频任务未完成：{task.get('error') or status}")
    time.sleep(15)
else:
    raise TimeoutError(f"本地等待已结束，请稍后继续查询原任务：{video_id}")

temporary = Path("result.mp4.part")
with requests.get(
    f"{base_url}/ai/v1/videos/{video_id}/content",
    headers=headers,
    timeout=120,
    stream=True,
) as response:
    response.raise_for_status()
    with temporary.open("wb") as output:
        for chunk in response.iter_content(chunk_size=1024 * 1024):
            if chunk:
                output.write(chunk)
temporary.replace("result.mp4")
print("视频已保存为 result.mp4")
```

30 分はこの例のローカル待機時間の上限であり、サーバー側タスクのタイムアウトを示すものではありません。照会の HTTP `200` は生成成功を意味しないため、必ず `status` を確認してください。ポーリングには `/ai/v1/videos/{id}` を使用します。統一タスク API の `/ai/v1/tasks/{id}` は、読み取り専用のスナップショットを提供します。

動画の照会とダウンロードには、タスク作成時と同じ API Key を使用します。完了後は速やかにダウンロードし、自分で保存してください。結果には保持期限があり、`expires_at` を基準にします。期限切れの場合は `410 artifact_expired` が返されることがあります。

<h3 id="verified-flow">
  今回のフロー検証
</h3>

2026-09-07 の本番環境での検証では、インターネットからアクセス可能な HTTPS の JPEG 直接リンク、本人が完了した Web ページでの確認、および上記の Seedance 2.5 パラメータを使用し、以下の結果を確認しました。

| 手順            | 今回の結果                                                                                   |
| ------------- | --------------------------------------------------------------------------------------- |
| 素材グループの作成     | HTTP `201`、`status=pending_auth`                                                        |
| 確認セッションの作成    | HTTP `201`、`status=pending`                                                             |
| 本人による確認完了後の照会 | セッションは HTTP `200`、`status=verified`、素材グループは `active`                                    |
| 画像素材の作成と照会    | 作成時は HTTP `201`、`status=processing`、その後の照会は HTTP `200`、`status=active`                  |
| 新版動画の作成と照会    | 作成時は HTTP `200`、`status=in_progress`、その後の照会は HTTP `200`、`status=completed`、`error=null` |
| 動画のダウンロード     | HTTP `200`、`Content-Type: video/mp4`、ffmpeg によるファイル全体のデコードに成功                           |

今回のファイルは 1,558,358 バイトでした。ffprobe では H.264、24 fps、560 × 752 ピクセル、4.041667 秒、音声トラックなしと検出されました。これらは今回の生成結果の値であり、毎回のリクエストで同じ寸法、長さ、ファイルサイズが出力されることを示すものではありません。

確認ページを初めて開いた際に `internal error` が表示され、その後の API 照会でも `pending` のままでした。ページエラーの原因は未確認です。このテストでは、その後、独立したテストグループの新しいページを使用し、本人による操作の完了後にセッションが `verified`、素材グループが `active` であることを確認しました。新しいグループの使用は今回のテストでの対応方法に限られます。素材グループを繰り返し再作成することを一般的に推奨するものではなく、元のセッションが終了したことも意味しません。

今回、Seedance 2.0 の動画生成、互換 API による作成、音声と動画の素材、最初と最後のフレーム、削除、およびその他の異常条件の組み合わせは実測していません。関連する説明は API 仕様と公式資料に基づいて維持しています。今回の検証は、ガイド全体のすべてのシナリオを対象としていません。

<h2 id="idempotency">
  冪等な再試行
</h2>

* 素材作成がタイムアウトした場合やレスポンスを受け取れなかった場合は、元の `Idempotency-Key`、`client_reference_id`、URL、`asset_type` を保持し、同じリクエストを再送してください。2 つの識別子のいずれかが、同じアカウント、同じ素材グループの既存素材に一致すると、その素材が再利用されます。
* 同じ識別子に対応する URL または `asset_type` が変わると、`409 asset_idempotency_conflict` が返されます。署名付き画像 URL の更新も URL の変更に該当します。
* どちらの識別子も指定しない場合、リクエスト間の重複排除は保証されません。別の素材を作成することが確定した場合にのみ、新しい識別子を使用してください。
* 素材 ID を取得済みの場合は、まず `GET /ai/v1/assets/{id}` で照会してください。`reconciling` は失敗を意味しません。新しい識別子に変更して再作成しないでください。
* 素材の削除が完了すると、元の冪等性識別子は保持されなくなります。その識別子を使って削除済み素材を復元しようとしたり、古い作成リクエストを再送したりしないでください。
* 本節の冪等性の仕様は素材作成にのみ適用されます。素材グループ、確認セッション、動画の作成には適用できません。新版の動画作成レスポンスを受け取れなかった場合は、重複生成を避けるため、まず `GET /ai/v1/videos?limit=20&order=desc` で元のタスクを探してください。

<h2 id="delete-assets">
  素材と素材グループを削除する
</h2>

削除する前に、互換 API から送信したタスクも含め、その素材を参照するすべての動画が終了していることを確認してください。削除操作は取り消せません。ダウンロード済みの動画ファイルは、自分で管理する必要があります。

単一の素材を削除します。

```bash theme={null}
curl --fail-with-body -sS -X DELETE "$BASE_URL/ai/v1/assets/$ASSET_ID" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq .
```

`202` が返された場合は削除処理が継続中です。`GET /ai/v1/assets/{id}` で `status=deleted` になるまで照会を続けてください。削除を再度リクエストすると現在のステータスが返されます。`reconciling` の場合は結果の確認を続け、完了しない状態が続く場合はサポートに連絡してください。

素材グループ全体を削除すると、グループ内の素材も同時に削除されます。`cascade=true` を明示的に渡す必要があります。

```bash theme={null}
curl --fail-with-body -sS -X DELETE \
  "$BASE_URL/ai/v1/asset-groups/$GROUP_ID?cascade=true" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq .
```

受け付けられると `202` が返されます。`GET /ai/v1/asset-groups/{id}` で照会してください。`deleting` は処理中、`partially_deleted` は一部が未削除の状態を示し、`deleted` で初めて完了となります。デフォルトでは、一覧に削除済みの素材グループは表示されません。

`409 asset_group_in_use` は、まだ終了していない操作または動画タスクがあることを示します。待機し、関連するステータスを照会してから再試行してください。互換版の動画タスクについては、自分で終了を確認する必要があります。削除リクエストが、すべての互換タスクによる使用状況を自動的に判断すると想定しないでください。

<h2 id="faq">
  よくある質問
</h2>

<h3 id="verification-pending">
  Web ページでの操作を完了しても素材を追加できないのはなぜですか？
</h3>

まず確認セッションと素材グループを照会し、`verified` と `active` を基準にしてください。Web ページに `internal error` が表示された場合も、同じ確認を行います。`pending` の間は同じグループのセッションを繰り返し作成しないでください。結果が未確認の場合は、しばらくしてから再度照会してください。完了しない状態が続く場合は、ID を添えてサポートに連絡してください。確認リンクや本人の写真を提出する必要はありません。

<h3 id="video-failed">
  素材が利用可能でも動画生成に失敗するのはなぜですか？
</h3>

参照に AIHubMix が返した素材 ID を使用しているか、すべての素材が同じグループに属しているか、メディアの種類が一致しているか、現在のモデルが該当する入力に対応しているかを確認してください。素材の `active` は素材が利用可能であることを示します。動画タスクの完了ステータスとエラー情報は、別途確認する必要があります。

<h3 id="errors">
  よくある API エラーにはどう対処しますか？
</h3>

| HTTP | `error.code`                                                               | 対処方法                                     |
| ---- | -------------------------------------------------------------------------- | ---------------------------------------- |
| 400  | `invalid_request`                                                          | リクエストのフィールド、構造、使用する動画プロトコルを確認            |
| 400  | `asset_group_invalid`                                                      | 素材グループの名前を確認                             |
| 400  | `asset_invalid`                                                            | URL、素材の種類、リクエスト識別子を確認                    |
| 400  | `asset_binding_mismatch`                                                   | 同じ動画リクエストでは、同一の素材グループの素材のみを参照            |
| 400  | `cascade_confirmation_required`                                            | グループ全体を削除する意図を確認したうえで `cascade=true` を指定 |
| 401  | `authentication_failed`                                                    | API Key の環境変数と認証リクエストヘッダーを確認             |
| 403  | `async_not_enabled`                                                        | 非同期タスクを有効にしてから新版の動画 API を使用              |
| 404  | `asset_group_not_found`、`asset_not_found`、`verification_session_not_found` | リソース ID と所属アカウントを確認                      |
| 409  | `asset_group_not_verified`                                                 | 本人による確認の結果を照会し、素材グループが利用可能になるまで待機        |
| 409  | `verification_session_active`                                              | 既存のセッションまたは素材グループを照会し、重複した開始を回避          |
| 409  | `asset_not_ready`                                                          | 素材のステータスを照会し、動画生成前に `active` になるまで待機     |
| 409  | `asset_idempotency_conflict`                                               | 識別子に対応する元の URL と種類を確認                    |
| 409  | `asset_group_in_use`                                                       | 関連する操作と動画タスクが終了してから削除                    |
| 503  | `asset_group_unavailable`、`verification_unavailable`、`asset_unavailable`   | しばらくしてから再試行し、利用できない状態が続く場合はサポートに連絡       |

その他の動画エラーは[非同期タスクのエラーコード](/jp/api/async-tasks#error-codes)を参照してください。問い合わせ時には、発生時刻、HTTP ステータス、`error.code`、返された `error.tid`（存在する場合）、関連リソースの ID を提供してください。API Key、確認リンク、署名付き画像 URL は提供しないでください。

<h2 id="references">
  参考資料
</h2>

* [BytePlus：実在人物の素材を追加する](https://docs.byteplus.com/en/docs/ModelArk/2315856)
* [BytePlus：Seedance でポートレート動画を生成する](https://docs.byteplus.com/en/docs/ModelArk/2608626)
* [AIHubMix ネイティブ動画生成](/jp/api/aihubmix-video-generation)
* [OpenAI 互換動画 API](/jp/api/Video-Gen)
* [非同期タスク](/jp/api/async-tasks)

更新日：2026-09-07