> ## 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.

# 豆包真人素材使用指南

> 透過本人網頁確認建立真人素材，使用 asset:// 引用呼叫豆包 Seedance 影片生成，並查詢、重試和刪除素材。

真人素材用於在影片中引用已由本人確認的人物形象。流程為：建立素材組、本人完成網頁確認、新增素材、等待素材可用，再提交影片生成任務。

本頁以圖片素材為例，使用 AIHubMix API 完成素材管理，優先使用新版 `/ai/v1/videos` 生成影片。已有 `/v1/videos` 用戶端可參考[相容協定範例](#compatible-video)。

<h2 id="prerequisites">
  前置條件
</h2>

* 準備有效的 AIHubMix API Key，透過環境變數 `AIHUBMIX_API_KEY` 讀取。
* 使用新版影片介面前，在主控台開啟[非同步任務](/zh-Hant/api/async-tasks)，並確認帳戶有足夠額度及目標模型的使用權限。
* 素材中的本人同意相關用途，並親自完成網頁上的確認流程。同一素材組僅新增同一人的素材。
* 準備可供模型推理廠商讀取的圖片直連網址，確認連結在素材處理期間持續有效。
* 命令列範例需要 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；不要把網頁顯示的其他素材 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` | 本次未通過，檢查網頁提示後重新發起         |
| `expired`  | 本次已過期，重新發起確認              |
| `failed`   | 本次失敗，檢查錯誤提示，必要時聯絡支援       |

用戶端可每 10 至 15 秒查詢一次，並設定本機等待上限。該間隔為使用建議。網頁顯示完成或回傳空白頁面時，仍應透過 API 確認工作階段為 `verified`、素材組為 `active`，再新增素材。

若重新建立回傳 `409 verification_session_active`，先查詢已有工作階段和素材組。有效工作階段仍存在、素材組已完成確認，或前次結果仍待確認時，都不應反覆新增。持續未完成時聯絡[支援](/zh-Hant/FAQs/Feedback)。

<Warning>
  網頁出現 `internal error` 不代表確認工作階段已結束。先執行本節的兩個 GET 請求，查詢工作階段和素材組；工作階段仍為 `pending` 時，不要反覆建立同組工作階段。只有工作階段為 `verified` 且素材組為 `active`，才繼續新增素材。僅憑網頁錯誤無法判斷原因，持續未完成時保留 ID 聯絡支援。
</Warning>

<h2 id="create-asset">
  4. 透過圖片網址建立素材
</h2>

<h3 id="image-requirements">
  圖片準備
</h3>

提供回傳圖片檔案的絕對 HTTP(S) 網址，優先使用 HTTPS。連結應無需登入或附加請求標頭即可讀取；本機路徑、內部網路位址、Base64 和帶帳號密碼的 URL 不適用於素材建立介面。URL 不應包含 `#` 片段。

根據 [BytePlus 真人素材指南](https://docs.byteplus.com/en/docs/ModelArk/2315856)，圖片建議為清晰正面照，並符合以下素材入庫要求：

| 項目   | 要求                                   |
| ---- | ------------------------------------ |
| 格式   | JPEG、PNG、WebP、BMP、TIFF、GIF、HEIC、HEIF |
| 單張大小 | 小於 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`                 | 是  | 可存取的素材檔案網址                             |
| `asset_type`          | 是  | `image`、`video` 或 `audio`；本例使用 `image` |
| `client_reference_id` | 否  | 業務端素材識別值，最長 128 位元組                    |

請求主體只接受以上三個欄位。`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 秒，查詢不回傳原圖片網址，請自行保留業務記錄。

<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`，僅在模型支援相應能力時使用。完整參數參閱[影片生成](/zh-Hant/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`，依據現有相容介面約定和 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 .
```

兩種範例擇一執行，每次影片建立都是獨立請求。不要在相容請求中混入 `input_references`。同時提供兩處 `content` 時，`extra_body.content` 覆寫頂層 `content`，建議只提供一處。

相容版回傳的 `id` 應用於 `GET /v1/videos/{id}` 查詢，完成後透過 `GET /v1/videos/{id}/content` 下載。不要把相容版 ID 交給 `/ai/v1/videos` 查詢。詳細說明見[相容影片介面](/zh-Hant/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}`，統一任務介面 `/ai/v1/tasks/{id}` 提供唯讀快照。

影片查詢和下載使用建立任務時的同一 API Key。完成後及時下載並自行儲存；結果有保留期限，以 `expires_at` 為準，過期可能回傳 `410 artifact_expired`。

<h3 id="verified-flow">
  本次流程驗證
</h3>

2026-09-07 的線上驗證使用公開網路 HTTPS JPEG 直連網址、本人完成的網頁確認，以及上述 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 影片生成、相容介面建立、音訊與影片素材、首尾影格、刪除及其他異常組合。相關說明保留介面約定和官方資料依據，本次驗證不涵蓋整篇指南的全部情境。

<h2 id="idempotency">
  冪等重試
</h2>

* 素材建立逾時或回應遺失時，保留原 `Idempotency-Key`、`client_reference_id`、URL 和 `asset_type`，重新傳送同一請求。兩個識別值中任一個符合相同帳戶、相同素材組的已有素材時，會重用該素材。
* 相同識別值對應的 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>

刪除前先確認所有引用該素材的影片均已結束，包括透過相容介面提交的任務。刪除操作無法復原，已下載的影片檔案需自行管理。

刪除單個素材：

```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">
  已完成網頁操作，為什麼還不能新增素材？
</h3>

先查詢確認工作階段和素材組，以 `verified` 和 `active` 為準。網頁出現 `internal error` 時也執行相同檢查；`pending` 期間不反覆建立同組工作階段。結果尚未確認時稍後再查；持續未完成請提供 ID 聯絡支援，無需提交確認連結或本人照片。

<h3 id="video-failed">
  素材可用，為什麼生成影片仍然失敗？
</h3>

檢查引用是否使用 AIHubMix 回傳的素材 ID，所有素材是否屬於同一組，媒體類型是否相符，以及目前模型是否支援相應輸入。素材 `active` 表示素材可用，影片任務仍需單獨檢查完成狀態和錯誤資訊。

<h3 id="errors">
  如何處理常見介面錯誤？
</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`                                                        | 開啟非同步任務後使用新版影片介面           |
| 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`   | 稍後重試；持續不可用時聯絡支援            |

其他影片錯誤參閱[非同步任務錯誤碼](/zh-Hant/api/async-tasks#error-codes)。回報時提供發生時間、HTTP 狀態、`error.code`、回傳的 `error.tid`（如有）及相關資源 ID；不要提供 API Key、確認連結或帶簽章的圖片網址。

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

* [BytePlus：新增真人素材](https://docs.byteplus.com/en/docs/ModelArk/2315856)
* [BytePlus：使用 Seedance 生成肖像影片](https://docs.byteplus.com/en/docs/ModelArk/2608626)
* [AIHubMix 原生影片生成](/zh-Hant/api/aihubmix-video-generation)
* [OpenAI 相容影片介面](/zh-Hant/api/Video-Gen)
* [非同步任務](/zh-Hant/api/async-tasks)

更新時間：2026-09-07