使用 `real_person` 直接提交真人參考圖

OfoxAI 允許你在一般的 POST /v1/videos 請求中直接提交已獲授權的真人參考圖。只要在頂層加入 real_person: true，再透過 frame_images 或 input_references 傳圖；Ofox 會在任務交給影片供應商前自動完成隱私保護預處理。

這省去了供應商端的人像資產入庫步驟。首次請求前，你不需要先建立 Seedance 真人人像資產群組、請本人完成供應商的真人驗證與授權、等待素材變為可用狀態、取得 Asset ID，再把原圖換成 asset://... URI。

只能提交你依法有權且已獲授權使用的圖片。real_person 是處理指令，不是授權證明，也不會繞過 Ofox 或上游供應商的內容政策。

為什麼 Ofox 流程更簡單

BytePlus Seedance 2.0 官方影片 API 文件明確說明，含有真人臉孔的參考圖片或影片不能直接上傳，官方路徑是使用已授權的真人人像資產。官方私有真人人像資產庫指南要求完成人員驗證、素材一致性檢查、等待 Active 狀態，再以 Asset URI 產生影片。火山方舟指南也列出邀請、本人驗證授權、上傳素材、接收授權與取得 Asset ID 等步驟。

步驟	Seedance 2.0 官方直連 API	Ofox 影片 API
首次請求前	建立資產群組、完成真人驗證與授權、上傳並檢查素材、取得 Asset ID	無需在供應商平台預先入庫；直接使用你已獲授權處理的圖片
參考圖傳法	使用已生效的授權資產 `asset://<asset_id>`	在現有 `frame_images` 或 `input_references` 中傳圖片 URL 或 `data:` URI
請求開關	改用審核通過的資產 URI	在頂層加入 `"real_person": true`

Ofox 簡化的是技術串接，不會免除使用者對肖像權、授權與合法使用的責任。

快速開始


curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "prompt": "讓畫面中的人物走過充滿電影感的夜市",
    "real_person": true,
    "input_references": [
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/person.jpg" }
      }
    ]
  }'

real_person 必須放在請求頂層。frame_images 或 input_references 中至少要有一張圖片，而且這兩個參考欄位仍然互斥。完整結構與數量限制請參閱建立影片任務。

提交後會發生什麼

Ofox 驗證並預處理所選參考欄位中的每張圖片。
預處理後的請求會提交給所選影片供應商。
供應商仍會執行自己的身分、反深偽與內容安全檢查。

合適的輸入通常可進入正常的非同步任務流程，但預處理不保證上游一定接受。少量圖片仍可能觸發上游真人審核或遭拒；遭拒的任務不會計費。

圖片仍觸發真人審核時

讓人物更容易被穩定辨識，然後保持 real_person: true 重新提交：

保留一位清楚的主要人物，減少畫面中其他可見臉孔；
裁切或重新安排構圖，讓主要臉孔足夠大且不要貼近邊緣；
優先使用清楚、正面、無遮擋且光線均勻的臉孔；
盡量移除或裁掉背景人物、海報、螢幕、鏡面與反光中的臉孔；
避免極端角度、明顯動態模糊、重陰影、口罩與大面積遮擋；
改用更高品質的原圖，並簡化過度擁擠的版面。

這些調整可減少辨識歧義，但不會覆蓋供應商政策，也不保證一定通過。若仍遭拒，請改用另一張已獲授權的參考圖。

可直接修正的預處理錯誤

若 Ofox 無法預處理輸入圖片，請求會回傳 HTTP 400，且 error.code 為 "invalid_request"。error.message 結尾會帶有穩定原因代碼：

原因代碼	修正方式
`bad_data_uri`	修正格式錯誤的 `data:` URI 或 base64 內容
`download_failed`	確保 URL 可下載，且沒有連線、逾時或存取控制問題
`unreachable`	改用可回傳成功 HTTP 狀態的 URL
`not_image`	提供支援且可解碼的圖片
`too_large`	縮小檔案、像素尺寸或單次處理的圖片數量

完整錯誤物件與診斷方式請參閱影片 API 錯誤碼。

使用 real_person 直接提交真人參考圖