建立影片任務
提交一個影片生成任務。請求會立即返回 202 Accepted，攜帶任務 id 與輪詢地址——生成流程非同步執行。輪詢任務或接收 webhook，再用 查詢任務狀態 讀取結果。
POST https://api.ofox.io/v1/videos請求參數
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
model | string | ✅ | 模型 slug，如 bytedance/seedance-2.5、bytedance/seedance-2.0 |
prompt | string | ✅ | 影片文字描述 |
duration | integer | — | 影片秒數 |
resolution | string | — | 480p / 720p / 1080p / 1K / 2K / 4K |
aspect_ratio | string | — | 16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 3:2 / 2:3 / 21:9 / 9:21 |
size | string | — | 精確像素 WIDTHxHEIGHT（如 1280x720），取代 resolution + aspect_ratio |
frame_images | array | — | 幀控制（圖生影片 / 首尾幀）。傳入即視為 image-to-video，見下方 |
input_references | array | — | 引導 subject / 風格（參考圖生影片），非精確幀錨點，見下方 |
real_person | boolean | — | 預設 false。真人參考圖設為 true，服務端會在生成前自動預處理；至少需要一張圖片引用 |
generate_audio | boolean | — | 支援音訊輸出的模型預設 true |
seed | integer | — | 確定性生成種子（不保證所有 provider 支援） |
callback_url | string | — | 終態 webhook 通知地址，必須 HTTPS（見 Webhook） |
provider | object | — | type 指定承載供應商，options 透傳 provider 特有參數。見 供應商路由 |
frame_images[] 元素
每個元素錨定輸出的一幀，frame_type 取 first_frame 或 last_frame。
{
"type": "image_url",
"image_url": { "url": "https://example.com/first.jpg" },
"frame_type": "first_frame"
}input_references[] 元素
依 type 傳圖片 / 音訊 / 影片參考（引導 subject / 風格 / 一致性，非精確幀錨點）：
{ "type": "image_url", "image_url": { "url": "https://example.com/subject.jpg" } }
{ "type": "audio_url", "audio_url": { "url": "https://example.com/voice.mp3" } }
{ "type": "video_url", "video_url": { "url": "https://example.com/ref.mp4" } }| 媒體 | type | 數量上限 | 其他限制 |
|---|---|---|---|
| 圖片 | image_url | ≤ 9 | — |
| 音訊 | audio_url | ≤ 3 | 單段 ≤ 15 秒 |
| 影片 | video_url | ≤ 1 | — |
超出任一上限返回 400 too_many_references（見 錯誤碼）。
frame_images 與 input_references 互斥——一個請求只能用其中一種，不能同時傳。同時傳返回 400 references_conflict。
real_person：真人參考圖
Ofox 一步式直傳流程、與 Seedance 人像資產入庫的比較，以及圖片遭拒後的實用調整建議，請參閱真人參考圖。
當參考圖包含可識別的真人形象時，將頂層 real_person 設為 true。Ofox 會在提交生成任務前，對所選參考欄位中的每張圖片自動進行隱私保護預處理。預設值為 false，現有請求行為不變。
{
"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 中的圖片配合使用，但這兩個欄位仍然互斥。請求中至少需要一張圖片，否則返回 400 invalid_request。
預處理可以減少上游反深偽審核的誤拒，但不會繞過內容政策，也不保證一定通過。上游仍可能拒絕任務；拒絕後不計費，可修正輸入或重試。圖片輸入問題見real_person 圖片預處理錯誤。
模式判定（隱式）
無 gen_mode 欄位。模式由傳入的輸入欄位隱式判定：
| 模式 | 判定條件 |
|---|---|
text2video | 不傳 frame_images 與 input_references |
img2video | frame_images 含 1 個 first_frame |
img2video_end | frame_images 含 first_frame + last_frame |
imgref2video | input_references 僅圖片 |
mixref2video | input_references 內含圖 / 音 / 視混合 |
回應
202 Accepted——任務受理，返回 status: "pending" 與 polling_url：
{
"id": "9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718",
"status": "pending",
"polling_url": "https://api.ofox.io/v1/videos/9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718"
}輪詢 polling_url（或等待 webhook）直到任務進入終態——見 查詢任務狀態。
請求範例大全
一套 /v1/videos schema 涵蓋全部生成模式，模式由輸入欄位隱式判定。下方每個範例均可直接執行。
文生影片
不傳 frame_images / input_references → 文生影片。
# 選填：指定供應商；不傳則由平台自動分流
# "provider": { "type": "byteplus" }
curl -X POST https://api.ofox.io/v1/videos \
-H "Authorization: Bearer $OFOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "bytedance/seedance-2.5",
"prompt": "A golden retriever running on the beach at sunset",
"duration": 5,
"resolution": "1080p",
"aspect_ratio": "16:9",
"generate_audio": true
}'可疊加選項
以下欄位正交於生成模式——可疊加在上面任一種請求體上。
Webhook（callback_url）
任務進入終態時在你的地址收到一次 POST 推送，取代輪詢。
{
"model": "bytedance/seedance-2.5",
"prompt": "...",
"callback_url": "https://your-app.example/webhooks/ofox-video"
}callback_url 必須 HTTPS。推送體與簽名見 Webhook。