> ## 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`, 平台會依正常規則選擇渠道. 支援私有素材庫的渠道會先準備並審核素材, 不支援的渠道略過此步驟, 沿用原有的媒體處理與影片生成流程. 不需要自行判斷渠道能力, 重複列出素材, 預先建立群組或另外查詢審核 API.

<Note>
  此方式適用於帶有媒體輸入的非同步影片生成請求, 不限於 Seedance. 平台必須啟用此功能; 純文字請求, 同步 API 以及影片 remix 和 extend 操作不適用. 模型的媒體要求與渠道可用性規則不變. 略過私有素材提審不代表略過供應商本身的內容審核. 中國大陸使用者可將範例中的 `https://toapis.com` 替換為 `https://toapis.cn`.
</Note>

## 請求方式

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

以下以 Seedance 2 為例. 使用其他模型時, 請依對應模型文件選擇媒體欄位與生成參數, 再加上 `private_asset_review: true`.

```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`                               |

原模型支援的 `video_list` 可繼續使用, 也可作為唯一媒體輸入, 例如 Kling Omni 和 Gemini Omni 1.1 的參考影片請求. 此欄位不納入上述私有素材提審範圍, 仍依各模型規則處理. 開關不會讓模型原本不支援的欄位或格式生效.

上述提審欄位中的 HTTP(S) URL 去除前後空白後用於比對, 最多 2048 個 UTF-8 位元組, 不得內嵌使用者名稱或密碼. 同一 URL 與型別會重用, 型別衝突則報錯. 圖片也支援純 Base64 或 `data:image/...;base64,...`; 需要提審時, 平台驗證解碼內容後轉存再審核. 略過提審的渠道依原模型規則處理 URL 或 Base64, 不會因此新增格式支援. 上述影片與音訊欄位只接受 HTTP(S). 不接受本機路徑; 也可先[上傳圖片](../uploads/images)取得 URL.

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

## 等待與查詢結果

1. 請求受理後返回影片任務, 不會保持 HTTP 連線等待完整審核. 返回任務不表示素材已通過或影片已開始生成.
2. 支援素材庫的渠道會檢查可重用記錄. 沒有可用記錄時, 平台轉存素材, 為每份渠道素材自動建立獨立群組並提審. 同一使用者, 素材來源與渠道的並行請求共用準備過程, 不會各自建立群組並重複提審.
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.
* 需要提審時, 平台為各渠道儲存獨立副本. 目前預設清理門檻為 60 天未使用, 實際保留期依平台設定. 自動建立的群組會隨素材副本一起清理, 不接管舊 API 的素材或共用群組. 影片提交被接受即算使用, 不必等影片完成. 清理後再次請求會重新準備, 來源 URL 應持續有效.
* 同一業務請求的網路重試使用相同 `client_business_id`, 已存在的任務會直接返回. 產生另一部影片或失敗後重新嘗試時, 使用新的業務 ID. 不要因等待審核而反覆建立任務.
* 若影片是否提交成功仍未確認, 請保留原任務並繼續查詢或聯絡支援, 不要立即用新業務 ID 重送.

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

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

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

參數錯誤請先檢查開關型別, asset:// 引用, URL 或 Base64 格式. 下載失敗請檢查存取權限與有效期. 功能未啟用, 沒有可用生成渠道或審核設定異常時, 請聯絡平台處理; 已設定審核的渠道不會因設定錯誤而自動略過審核.