Skip to Content
API 參考影片生成建立影片任務

建立影片任務

提交一個影片生成任務。請求會立即返回 202 Accepted，攜帶任務 id 與輪詢地址——生成流程非同步執行。輪詢任務或接收 webhook，再用 查詢任務狀態 讀取結果。

POST https://api.ofox.ai/v1/videos

請求參數

參數類型必填說明
modelstring✅模型 slug，如 google/veo-3.1、bytedance/seedance-2.0
promptstring✅影片文字描述
durationinteger—影片秒數
resolutionstring—480p / 720p / 1080p / 1K / 2K / 4K
aspect_ratiostring—16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 3:2 / 2:3 / 21:9 / 9:21
sizestring—精確像素 WIDTHxHEIGHT（如 1280x720），取代 resolution + aspect_ratio
frame_imagesarray—幀控制（圖生影片 / 首尾幀）。傳入即視為 image-to-video，見下方
input_referencesarray—引導 subject / 風格（參考圖生影片），非精確幀錨點，見下方
generate_audioboolean—支援音訊輸出的模型預設 true
seedinteger—確定性生成種子（不保證所有 provider 支援）
callback_urlstring—終態 webhook 通知地址，必須 HTTPS（見 Webhook）
providerobject—provider 特有參數透傳，見 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。

模式判定（隱式）

無 gen_mode 欄位。模式由傳入的輸入欄位隱式判定：

模式判定條件
text2video不傳 frame_images 與 input_references
img2videoframe_images 含 1 個 first_frame
img2video_endframe_images 含 first_frame + last_frame
imgref2videoinput_references 僅圖片
mixref2videoinput_references 內含圖 / 音 / 視混合

回應

202 Accepted——任務受理，返回 status: "pending" 與 polling_url：

{
  "id": "9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718",
  "status": "pending",
  "polling_url": "https://api.ofox.ai/v1/videos/9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718"
}

輪詢 polling_url（或等待 webhook）直到任務進入終態——見 查詢任務狀態。

請求範例大全

一套 /v1/videos schema 涵蓋全部生成模式，模式由輸入欄位隱式判定。下方每個範例均可直接執行。

不傳 frame_images / input_references → 文生影片。

Terminal
curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/veo-3.1",
    "prompt": "A golden retriever running on the beach at sunset",
    "duration": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'

可疊加選項

以下欄位正交於生成模式——可疊加在上面任一種請求體上。

任務進入終態時在你的地址收到一次 POST 推送，取代輪詢。

{
  "model": "google/veo-3.1",
  "prompt": "...",
  "callback_url": "https://your-app.example/webhooks/ofox-video"
}

callback_url 必須 HTTPS。推送體與簽名見 Webhook。

Provider 透傳

provider 特有參數透過 provider.options.<slug> 傳遞——只有符合的 provider 會收到。像 watermark 這類參數並非所有模型都支援，因此放進 provider 透傳而非頂層欄位（對齊 OpenRouter 的 provider 透傳設計）。各模型支援哪些透傳參數以模型能力為準。

{
  "model": "alibaba/wan-2.7",
  "prompt": "...",
  "provider": {
    "options": {
      "dashscope": { "watermark": false, "audio_setting": "..." }
    }
  }
}
Last updated on
概覽查詢任務