Skip to Content
API 參考影片生成真人參考圖

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

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

部分供應商要求含真人臉孔的參考圖先在其平台完成素材入庫與本人驗證，例如 Seedance，比較說明見 Seedance · 真人參考圖。使用 real_person 時不需預先完成這些步驟。

只能提交你依法有權且已獲授權使用的圖片。real_person 是處理指令，不是授權證明，也不會繞過 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 中至少要有一張圖片，而且這兩個參考欄位仍然互斥。具體結構與數量限制見建立影片任務。

提交後會發生什麼

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

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

圖片仍觸發真人審核時

讓人物更容易被穩定辨識，然後保持 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 錯誤碼。

相關文件

最後更新於
建立影片任務供應商路由