跳轉到主要內容
API易 上有多家模型能「看懂」影片:用一段提示詞,讓模型識別影片裡的場景、動作、字幕,並按時間戳定位關鍵畫面。除了 Gemini 系列,Seed(豆包)全系、Qwen 視覺 / 全模態系列、Kimi K3 也都實測可用。本頁給出支援清單、通用寫法,以及最容易踩坑的限制。
先看這三條:
  1. 通用寫法是 video_url:{"type": "video_url", "video_url": {"url": "data:video/mp4;base64,..."}},Seed / Qwen / Kimi / MiniMax / Gemini 都認。本頁舊版的 image_url + data:video/mp4 寫法只有 Gemini 認,換成別的模型會直接 400。
  2. GPT、Grok、Claude、GLM、DeepSeek 不支援影片輸入。其中 GPT 和 GLM 會靜默丟掉影片、照樣返回 200,GPT 還可能編出一段看似合理的答案——詳見「不支援影片的模型」。
  3. Gemini 不接收公開影片直鏈:可能報 Request contains an invalid argument,也可能返回 200 但影片被靜默丟棄(prompt_tokens 只有幾十),模型回答「看不到」甚至說畫面是「黑屏」;Seed / Qwen / Kimi 可以直接傳公網 https 地址。

視覺化介面測試

在 iCover 視覺化測試工具裡直接上傳影片、除錯理解介面。

讓 AI Agent 幫你接入

複製這段提示詞,貼上給 Codex / Claude Code / Cursor

它會先抓本頁的純文本版(任意文件頁地址後加 .md),再按你專案的技術棧寫程式碼——通用 video_url 寫法、Gemini 不收公網直鏈與 20MB 上限、用 prompt_tokens 確認影片真的進了模型這幾個高頻問題已經寫死在要求裡。

幫我在當前專案裡接入 / 排查影片理解:把一段影片交給多模態模型,做內容摘要、場景描述、動作分析或按時間戳定位。

先讀文件再動手:抓 https://docs.apiyi.com/api-capabilities/video-understanding.md 拿到本頁純文本版;需要 YouTu …

  1. 端點與寫法:走 OpenAI 相容的 POST https://api.apiyi.com/v1/chat/completions …

共 9 條接入要求,點下方按鈕複製完整版

支援的模型

以下結論來自 2026-10-11 (UTC+8) 的實測:同一段 10 秒測試影片(每 2.5 秒換一個數字與形狀),要求模型按順序說出數字和出現時間,並用一張空白圖做對照,排除「沒看也能答」的情況。 上一代 gemini-3.7-flash、gemini-3.5-flash 與經典穩定版 gemini-2.5-pro(2M 上下文)、gemini-2.5-flash 仍可用;3.8 Flash 與 3.5 Flash 實測影片 tokens 相同(10 秒約 713),但輸入單價只有一半。耗時與 tokens 只針對上述 10 秒、540p 的測試影片,影片越長、解析度越高越多,可據此按比例估算;實際耗時還受端點和上游排隊影響,同一段影片可能相差 2–3 倍。
模型價格與官網對齊,且可能隨官網調整;上表僅供參考,具體以頂部導航「模型價格」欄目為準:模型價格。

不支援影片的模型

GPT 在影片被丟棄後可能編造答案:實測 gpt-6-sol 3 次中 3 次編出了影片里根本不存在的數字序列,還把一段倫敦街景描述成「泳池和充氣浮具」。如果一定要用這些模型,請改用下方「抽幀當多圖」的寫法。

影片輸入方式

Gemini 的 20MB 限制:Base64 方式下,整個請求體(含編碼後的影片)必須在 20MB 以內。超過 20MB 的影片只能:① 用 YouTube 連結;② 先本地壓縮 / 擷取片段到 20MB 內再 base64;③ 換用 Seed / Qwen,把影片放到公網地址後直接傳連結。
公網直鏈要上游拉得到:影片由模型服務方去下載,地址必須對它可達。實測火山引擎物件儲存上的地址 Seed / Qwen / Kimi / MiniMax 都能拉取,而谷歌雲端儲存上的地址 Seed 報 403。拿不準時先用 Base64 跑通,再換直鏈。

快速開始:通用寫法(video_url)

適用於 Seed、Qwen、Kimi、MiniMax,以及 Gemini。
curl 等價寫法(把 <BASE64_VIDEO> 替換為影片的 base64 字串,或把整個 url 換成公網地址):
Seed 可以調取樣幀率:在 video_url 里加 "fps": 2,動作快的影片能看得更細(實測 10 秒影片輸入從約 4900 增加到約 6200 tokens)。Qwen、Kimi 會忽略這個欄位。

Gemini 專用寫法

Base64 內聯(image_url 舊寫法)

Gemini 同時相容上面的 video_url 寫法和下面這種 image_url 寫法,存量程式碼不用改;新程式碼建議統一用 video_url,方便切換模型。

Base64 內聯(Gemini 原生格式)

已經在用谷歌官方 google-genai SDK 的專案,不必改成 OpenAI 相容寫法:把 base_url 換成 https://api.apiyi.com,影片用 Part.from_bytes 內聯即可。與上面一樣,整個請求體須在 20MB 以內。
REST 等價寫法:Base64 字串很長,不要直接拼進命令列引數,先寫進 JSON 檔案再用 -d @req.json 傳送。
原生格式更容易確認影片有沒有進模型:響應的 usageMetadata.promptTokensDetails 會把輸入按模態拆開,實測 10 秒測試影片是 VIDEO 660 + TEXT 若干,與 OpenAI 相容寫法的總量一致。沒有 VIDEO 這一項,就說明影片沒被收到。

YouTube 連結(Gemini 原生格式)

YouTube 連結無需下載、不受 20MB 限制,但只能通過 Gemini 原生格式傳入(google-genai SDK,端點 https://api.apiyi.com)。
原生格式的更多用法(流式、推理預算、Function Calling 等)見 Gemini 原生格式呼叫。

不支援影片的模型:抽幀當多圖

GPT、Grok 這類只收圖片的模型,可以先在本地按固定間隔抽幀,再把幀當多張圖片傳入。實測 gpt-6-sol、gpt-6-luna、gpt-5.6-terra、grok-4.7、grok-4.5 用 4 幀都能正確說出內容和順序。代價是丟失音訊和幀之間的動作,時間點要靠你在提示詞裡說明。

進階技巧

時間戳定位

在提示詞裡用 MM:SS 直接定位片段——這是純提示詞技巧,任意支援影片的模型都可用:
需要精確時間點時優先選 Seed 或 Qwen;MiniMax-M3 實測時間點不可靠。

兩種「答案不可信」的情況

① 影片根本沒進模型:看響應裡的 usage.prompt_tokens。10 秒影片在 Seed / Qwen 上約 5000、Gemini 約 700;如果只有幾十個 token,說明影片被丟掉了(GPT、GLM,以及 Gemini 收到公網直鏈時都是這種情況),此時的答案不可信。注意模型不一定會說「看不到」:Gemini 收到直鏈時會把丟失的影片描述成「完全純黑的黑屏」,GPT 則會編出一段不存在的內容。 ② 素材不對,而提示詞又預設了內容:比如傳錯了檔案、影片解碼成黑屏 / 灰屏,或者聯調時隨手用了佔位圖。這種情況下 prompt_tokens 完全正常,靠 token 數查不出來。
Gemini 系列在情況 ② 下容易順著問題編答案。實測把影片換成一張空白圖:
  • 用中性問法「描述一下你收到的畫面」,Gemini 3.8 Flash / 3.5 Flash / 3.1 Pro / 3.1 Flash Lite 12 次全部如實說是空白圖——看圖能力本身沒問題;
  • 但問題一旦預設了內容(「影片裡依次出現了哪些數字」,甚至「有沒有出現數字?沒有就說沒有」),3.5 Flash / 3.1 Pro / 3.1 Flash Lite 合計 18 次中有 12 次編出了並不存在的數字;
  • 新一代 gemini-3.8-flash 明顯改善但沒有根治:同樣的預設問題 7 次中仍有 2 次編造;
  • 同樣的問題,Seed、Qwen、Kimi 都如實回答「看不到 / 沒有」。
正常影片的識別不受影響。素材來源不可控的批次場景,建議先用中性問題讓模型描述畫面,確認素材無誤後再問具體問題,或選用 Seed / Qwen。

常見任務的提問思路

同一段影片,換提示詞就能完成不同分析,無需改程式碼:
  • 內容摘要:用 3-5 句話概括影片主題、關鍵畫面與結論
  • 教學分析:提取知識點、章節劃分與重點時間戳
  • 監控分析:識別異常行為、出現的人/物及發生時間
  • 營銷評估:分析產品賣點呈現、節奏與目標受眾契合度
  • 動作分析:拆解動作步驟、姿態要點與可改進之處

技術說明

  • Gemini:預設按 1 幀/秒 取樣並理解音訊軌;Gemini 3.x 預設按低解析度計幀,實測約 70 tokens/秒。
  • Seed / Qwen:實測約 500 tokens/秒(540p 影片);Seed 可用 fps 調整取樣。
  • Kimi K3:實測約 1400 tokens/秒,長影片成本明顯更高。
  • 支援格式:mp4、mov、webm 等常見格式;建議統一轉成 H.264 編碼的 mp4,相容性最好。

常見問題

不能。Claude 和 Grok 會直接報錯;GPT 的 chat 端點會靜默丟掉影片、照樣返回 200,模型可能編出答案。需要用這些模型時,請先抽幀再當多張圖片傳入,見「不支援影片的模型:抽幀當多圖」。
實測可用:Seed 全系(seed-2-0-pro-260328、dola-seed-2-1-turbo-260628、seed-2-0-lite-260428、seed-2-0-mini-260428、seed-1-8-251228)、Qwen 的 qwen3.8-max、qwen3.8-flash、qwen3-vl-plus、qwen3.5-omni-plus,以及 kimi-k3。MiniMax-M3 能認出內容但時間點不準。glm-5.3 與 deepseek-v4-flash-vision-exp 不支援影片。
多半是用了 image_url + data:video/mp4 的舊寫法——它只有 Gemini 認。改成 {"type": "video_url", "video_url": {"url": ...}} 即可在各家通用。
先確認素材本身沒問題(不是黑屏、空白或傳錯檔案)。實測 Gemini 在素材有問題、而提問又預設了內容時,容易順著問題編出答案。排查時先換成中性問法「描述一下你收到的畫面」,看它描述的是不是你的影片;詳見「兩種「答案不可信」的情況」。
Gemini 不接收任意公開直鏈(如 https://example.com/video.mp4),這不是 API易 攔截。Gemini 請改用 Base64 內聯(20MB 以內)或 YouTube 連結;也可以換用 Seed / Qwen,它們可以直接拉取公網地址。走 /v1/chat/completions 時不一定報錯:可能返回 200、模型自稱看到「黑屏」,此時 prompt_tokens 只有幾十,結果不可用。
Base64 內聯方式下,Gemini 的整個請求體一直限制在 20MB 以內(與谷歌官方一致)。如果你「之前能用」的是公開直鏈,那其實從來不是受支援的方式,只是恰好某些情況下沒報錯;現在按規範會明確拒絕。
不能。Gemini 官方的 Files API(client.files.upload())第三方不支援,僅谷歌官方端點可用。大影片請走 YouTube 連結、壓縮到 20MB 內用 Base64,或換用 Seed / Qwen 傳公網地址。
三條路:① 上傳到 YouTube 後用連結傳入(Gemini 原生格式);② 用 ffmpeg 等工具本地壓縮或擷取關鍵片段到 20MB 內再 base64;③ 把影片放到公網可訪問的物件儲存,用 Seed / Qwen 直接傳連結。

相關資源

模型價格

檢視全部模型與最新定價

Gemini 原生格式

YouTube 連結、流式、推理預算等原生用法

影像理解 API

圖片內容識別與多模態分析

Qwen3.8-Max

通義千問旗艦,原生圖片與影片輸入