跳到正文
HopBase 文檔
登入控制台

Gemini Omni：影片生成 API

用 Gemini Omni 一次同步請求產生短影片：型號、請求參數、回傳結果、報錯與計費。

Gemini Omni 用一次同步請求產生短影片：回應本文中直接回傳 base64 MP4 成片，沒有任務 ID，也不需要輪詢。

項目取值
Base URLhttps://api.hop-base.com/v1beta
產生影片POST /v1beta/interactions
等價別名POST /v1/interactions、POST /interactions
任務與輪詢無，同步回傳
金鑰分組「Gemini 官方直連」

可用型號

模型 ID解析度時長官方價
gemini-omni-flash-preview720p3-10 秒$1.50 / $9/ 百萬 tokens

gemini-omni-flash-preview 是唯一能產生影片的 Gemini 模型，也是 HopBase 上唯一同步回傳的影片模型。成片為 3-10 秒 720p MP4，按 Token 計費而非按秒計費。完整規格見模型卡。

Omni 影片由Gemini 官方直連分組提供，與 Gemini 對話、Gemini 生圖是同一個分組、同一把金鑰，不需要另外購買影片套餐。可用性以 GET /v1/models 為準，實際單價請見登入後的模型廣場。

請求參數

參數必填類型與限制預設值說明
model必填僅 gemini-omni-flash-preview—其他模型返回 400
input必填字串，或原生步驟陣列；素材用 data（base64）加 mime_type，或遠端 uri；輸入影片 ≤ 10 秒—支援文字、圖片、影片輸入。10 秒上限由模型校驗，閘道不查
stream選填布林值false傳 true 也不會逐段串流，結果一次性返回
其他原生欄位選填如 system_instruction、generation_config—原樣透傳

沒有 duration、resolution、fps 這類參數，想要多長就直接在提示詞裡說明。

回傳結果

請求會一直等到成片生成完畢，沒有「排隊中」「處理中」這類中間狀態。成功時 HTTP 200，成片位於 type 為 model_output 那一步的 steps[].content[] 裡。

欄位說明
status完成時為 completed
steps[].type成片所在步驟為 model_output
steps[].content[].type影片區塊為 video
steps[].content[].mime_typevideo/mp4
steps[].content[].database64 編碼的 MP4
usage.total_input_tokens / usage.total_output_tokens輸入與輸出 Token
usage.output_tokens_by_modality輸出 Token 依模態拆開，僅供參考

成功

{
  "status": "completed",
  "model": "gemini-omni-flash-preview",
  "steps": [{
    "type": "model_output",
    "content": [{ "type": "video", "mime_type": "video/mp4", "data": "<base64-mp4>" }]
  }],
  "usage": {
    "total_input_tokens": 20,
    "total_output_tokens": 17819,
    "output_tokens_by_modality": [{ "modality": "video", "tokens": 17376 }]
  }
}

usage.output_tokens_by_modality 中的數字已經計入 total_output_tokens，請勿重複相加。

項目數值
時長3-10 秒
解析度720p
影格率24 FPS
封裝MP4，以 base64 回傳
上下文視窗1,048,576 Token

成片直接放在 JSON 回應本文裡，沒有下載連結，也就不存在連結過期。回應因此會很大，客戶端緩衝區要留夠空間。

失敗

失敗有三種形態：

  • 閘道校驗失敗返回 400，格式是 {"error": {"message": …}}，原文見下方「常見報錯」。
  • 模型自身的報錯以其原生錯誤體返回。
  • 返回 200 但沒有 type: "video" 區塊（模型只回了文字或拒答）。這種情況仍按 Token 計費，判定成功前請先檢查這個區塊。

最小範例

curl https://api.hop-base.com/v1beta/interactions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  --max-time 600 \
  -d '{
    "model": "gemini-omni-flash-preview",
    "input": "生成一段 3 秒影片:白色背景上一顆紅球緩慢滾動"
  }'

注意事項

Chat Completions 取不到影片：

把 gemini-omni-flash-preview 送到 /v1/chat/completions 是能呼叫成功的，但只會回傳回答裡的文字部分，影片區塊會被捨棄。要拿到成片就用 Interactions 端點。

影片生成較慢，而這個端點沒有非同步模式——Prefer: respond-async 對 Gemini 生圖有效，對這裡無效。

  • 原生 Interactions 端點沒有閘道端的逾時監控，客戶端逾時請設得足夠長，建議至少 5 分鐘。
  • 若改經 /v1/chat/completions 呼叫 gemini-omni-flash-preview，單次請求會受約 100 秒的限制，與客戶端逾時設定無關；可能跑得更久的請求請直接走 Interactions 端點。
  • HopBase 在這條路徑上刻意不重試 504：結果未知就重送，有可能把片子生成兩次、也扣兩次費用。
  • 模型 ID 帶 preview，能力與可用性可能隨時異動。

目前網關沒有為 Omni 圖片/影片輸入設定統一的素材數量、單檔位元組數校驗；未驗證的上限不等於無限制。不要套用 GPT Image 的 16 張或 Seedance 的素材規則。

uri 是遠端素材位址，data 是 base64 內容；不要傳 asset://、Seedance 素材 ID 或本機檔案路徑。即使結構被接受，媒體規格和內容審核仍以服務端結果為準。

常見報錯 → 改法

閘道對以下情況返回 400：

Interactions API only supports model gemini-omni-flash-preview
request body is missing input
missing model
request body must be JSON
報錯或現象改法
Interactions API only supports model gemini-omni-flash-previewmodel 改為 gemini-omni-flash-preview
request body is missing input補上 input
missing model補上 model
request body must be JSON請求本文改為 JSON
402餘額不大於 0，儲值後再呼叫
200 但沒有影片區塊模型只回了文字或拒答，仍計費；檢查 steps[].content[] 後再判定成功
經 /v1/chat/completions 只拿到文字改用 POST /v1beta/interactions
504HopBase 不自動重試；重送可能生成兩次、扣兩次費用

計費

按 Token 計費，不按秒。返回 200 但沒有影片區塊時仍按 Token 計費；發生錯誤或逾時的請求都不計費。

送出前不做餘額預留，只有餘額不大於 0 時才會回傳 402。官方牌價請見價格頁，你的實際單價以登入後的模型廣場為準，每次請求的實際扣款請見主控台「用量紀錄」。

下一步

本頁目錄

可用型號請求參數回傳結果成功失敗最小範例注意事項常見報錯 → 改法計費下一步