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

# 產生影片時按需審核素材

> 透過 private_asset_review 在同一個影片任務中完成素材審核與影片生成

在影片生成請求中設定 `private_asset_review: true`, 平台會自動準備實際使用的素材, 全部審核通過後才提交影片生成. 不需要重複列出素材, 也不必先建立素材群組或另外查詢審核接口.

<Note>
  此方式僅適用於已啟用按需素材審核的 Seedance 非同步影片渠道, 不適用於所有影片模型或同步接口. 功能未啟用或沒有相容渠道時, 請求會失敗. 中國大陸使用者可將範例中的 `https://toapis.com` 替換為 `https://toapis.cn`.
</Note>

## 請求方式

繼續呼叫 `POST /v1/videos/generations`. 圖片, 影片與音訊仍放在原有輸入欄位, 只需加上布林開關.

```bash theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance-2",
    "client_business_id": "avatar-demo-001",
    "prompt": "Animate the character in image 1 using the movement in video 1.",
    "duration": 5,
    "aspect_ratio": "16:9",
    "image_with_roles": [
      {"url": "https://files.example.com/avatar.jpg", "role": "reference_image"}
    ],
    "video_with_roles": [
      {"url": "https://files.example.com/motion.mp4", "role": "reference_video"}
    ],
    "private_asset_review": true
  }'
```

請將範例網址換成自己的公開 URL. 開關適用於實際使用的全部素材, 不能只選部分素材審核. 原有模型數量限制與角色驗證不變.

| 欄位                     | 型別      | 說明                                                     |
| ---------------------- | ------- | ------------------------------------------------------ |
| `private_asset_review` | boolean | 選填, 預設 `false`. 設為 `true` 啟用按需審核; 省略或設為 `false` 維持原有行為 |

建議使用下列輸入欄位. 各模型的數量限制與角色組合規則維持不變:

圖片依 `image_with_roles[].url` > `reference_images` > `image_urls` > `images` > `image` 選取第一個非空欄位, 不合併這些欄位. 原本禁止欄位混用的模型仍會報錯. 不掃描提示詞或 metadata, 也不讓原本忽略的欄位生效.

| 素材型別    | 影片輸入欄位                   | 角色                                              |
| ------- | ------------------------ | ----------------------------------------------- |
| `image` | `image_with_roles[].url` | `first_frame`, `last_frame` 或 `reference_image` |
| `video` | `video_with_roles[].url` | `reference_video`                               |
| `audio` | `audio_with_roles[].url` | `reference_audio`                               |

HTTP(S) URL 去除前後空白後用於比對, 最多 2048 個 UTF-8 位元組, 不得內嵌使用者名稱或密碼. 同一 URL 與型別會重用, 型別衝突則報錯. 圖片也支援純 Base64 或 `data:image/...;base64,...`, 平台驗證解碼內容後轉存再審核. 影片與音訊只接受 HTTP(S). 不接受本機路徑; 也可先[上傳圖片](../../uploads/images)取得 URL.

按需轉存要求檔案不能為空, 圖片不超過 20 MiB, 影片與音訊不超過 100 MiB. 模型或審核服務可能另有更嚴格的格式, 時長與大小限制. 上方的上傳入口適用於圖片; 本機影片與音訊請分別使用[上傳影片](../../uploads/videos)和[上傳音訊](../../uploads/audios).

## 等待與查詢結果

1. 請求受理後返回影片任務, 不會保持 HTTP 連線等待完整審核. 返回任務不表示素材已通過或影片已開始生成.
2. 平台儲存副本, 並檢查目前渠道是否已有可用審核記錄. 必要時發起審核; 同一使用者, URL 與渠道的並行請求共用準備過程.
3. 實際使用的素材必須全部通過, 才會提交影片生成. 首次準備可能需要數分鐘; 有可用記錄時會略過重複審核, 影片仍以非同步方式生成.

使用返回的任務 ID 或請求中的 `client_business_id` 查詢同一個影片任務:

```bash theme={null}
curl --request GET \
  --url https://toapis.com/v1/videos/generations/avatar-demo-001 \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

沿用[影片任務狀態](../../tasks/video-status)與[任務 Webhook](../../webhooks/task-webhooks). 審核期間可能維持 `queued`, 不需要呼叫舊素材狀態接口. `completed` 表示影片完成, `failed` 時請查看 `error.message`.

目前每輪素材準備期限預設為 20 分鐘, 從該輪開始準備時計算. 多份素材共用期限, 並非每份各有 20 分鐘, 也不包含後續影片生成時間. 平台設定可能調整此期限; 切換渠道時會開始新一輪準備. 素材被拒絕或準備逾時會結束該影片任務, 不會繼續提交影片.

首次審核未通過不會收取影片生成費用. 通過後依正常影片流程預扣與結算, 重用審核記錄不改變影片計價方式.

## 重用, 重試與保留時間

* 後續請求仍傳入素材並設定 `private_asset_review: true`, 不必儲存素材 ID. 同一使用者與渠道下, URL 依完整網址比對, Base64 圖片依解碼內容摘要比對, 純編碼與 data URI 可重用同一記錄. 不跨使用者或渠道共用.
* 不同 URL 視為新來源. 同一 URL 的內容變更不會透過檔案內容重新辨識, 素材更新時請使用新的版本 URL.
* 平台儲存獨立副本. 預設超過 30 天未使用的副本可能被清理, 實際保留期依平台設定. 影片提交被接受即算使用, 不必等影片完成. 清理後再次請求會重新準備, 來源 URL 應持續有效.
* 同一業務請求的網路重試使用相同 `client_business_id`, 已存在的任務會直接返回. 產生另一部影片或失敗後重新嘗試時, 使用新的業務 ID. 不要因等待審核而反覆建立任務.
* 若影片是否提交成功仍未確認, 請保留原任務並繼續查詢或聯絡支援, 不要立即用新業務 ID 重送.

## 與舊素材接口並行使用

省略開關或設為 `false` 時, 舊的[虛擬人像素材接口](./private-avatar)與既有 `asset://` 引用維持原有行為. 設為 `true` 時, 媒體欄位出現任何 `asset://` 都會返回 HTTP 400, 不查詢舊記錄, 不複製或遷移歷史素材.

此開關不改變模型能力或素材要求, 也不取代獨立的[真人人像認證](./real-avatar). 先前方案的 `private_assets` 欄位已不再接受, 請改用布林欄位 `private_asset_review`.

參數錯誤請先檢查開關型別, asset:// 引用, URL 或 Base64 格式. 下載失敗請檢查存取權限與有效期. 功能未啟用或渠道不相容時, 請聯絡平台確認適用範圍.