视频理解 API

使用 Gemini 3.5 Flash、Gemini 3.1 Pro Preview 等先进模型进行智能视频分析，支持内容识别、场景描述、动作分析与时间戳定位

API易 通过 Gemini 系列多模态模型提供视频理解能力：用一段提示词，让模型”看懂”视频里的场景、动作、字幕与音频，并按时间戳定位关键画面。本页说明支持的模型、可用的视频输入方式，以及最容易踩坑的限制。

先看这一条：视频只能通过 Base64 内联（整个请求 ≤ 20MB） 或 YouTube 链接（Gemini 原生格式）传入。直接传公开视频直链（如 https://example.com/demo.mp4）会报 Request contains an invalid argument —— 这是谷歌不接收直链，并非 API易 拦截。详见下方「视频输入方式」。

可视化接口测试

在 iCover 可视化测试工具里直接上传视频、调试理解接口。

​

支持的模型

模型	模型 ID	特点	推荐场景
Gemini 3.5 Flash 🔥	gemini-3.5-flash	速度快、性价比之王，多模态能力强	日常视频分析首选
Gemini 3.1 Pro Preview	gemini-3.1-pro-preview	谷歌最强推理 + 多模态理解	复杂、长视频深度分析
Gemini 3.1 Flash Lite	gemini-3.1-flash-lite	超低价、超低延迟	大批量、高并发场景

经典稳定版 gemini-2.5-pro（2M 上下文）与 gemini-2.5-flash 仍可用。完整价格见 模型列表与价格。

​

视频输入方式

这是最容易踩坑的地方，请先对照下表确认你的输入方式是否被支持：

输入方式	是否支持	说明
Base64 内联	✅	本地视频读取后 base64 编码传入，整个请求体需 ≤ 20MB。OpenAI 兼容格式与原生格式都支持
YouTube 链接	✅	仅 Gemini 原生格式，通过 file_uri 传入 YouTube URL
公开视频直链（如 .mp4 网址）	❌	谷歌不接收，会返回 Request contains an invalid argument，并非 API易 拦截
Files API（files.upload）	❌	第三方不支持，仅谷歌官方支持

20MB 限制：Base64 方式下，整个请求体（含编码后的视频）必须在 20MB 以内。超过 20MB 的视频目前只能：① 用 YouTube 链接；② 先本地压缩 / 截取片段到 20MB 内再 base64。

​

快速开始：Base64 内联（OpenAI 兼容格式）

最常用的方式：读取本地视频 → base64 编码 → 用 image_url 字段传入。

from openai import OpenAI
import base64

client = OpenAI(
    api_key="YOUR_API_KEY",            # 替换为您的 API易 密钥
    base_url="https://api.apiyi.com/v1"
)

{/* 读取本地视频并转 base64（整个请求 ≤ 20MB）*/}
with open("demo.mp4", "rb") as f:
    video_b64 = base64.b64encode(f.read()).decode()

response = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "请详细描述这个视频的内容"},
            {
                "type": "image_url",
                "image_url": {"url": f"data:video/mp4;base64,{video_b64}"},
                "mime_type": "video/mp4",
            },
        ],
    }],
)

print(response.choices[0].message.content)

curl 等价写法（把 <BASE64_VIDEO> 替换为视频的 base64 字符串；体积较大时建议直接用 SDK 自动编码）：

curl https://api.apiyi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-flash",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "请总结这个视频"},
        {"type": "image_url",
         "image_url": {"url": "data:video/mp4;base64,<BASE64_VIDEO>"},
         "mime_type": "video/mp4"}
      ]
    }]
  }'

​

YouTube 链接（Gemini 原生格式）

YouTube 链接无需下载、不受 20MB 限制，但只能通过 Gemini 原生格式传入（google-genai SDK，端点 https://api.apiyi.com）。

from google import genai
from google.genai import types

client = genai.Client(
    api_key="YOUR_API_KEY",
    http_options={"base_url": "https://api.apiyi.com"}
)

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=types.Content(parts=[
        types.Part(file_data=types.FileData(
            file_uri="https://www.youtube.com/watch?v=VIDEO_ID"
        )),
        types.Part(text="请总结这个视频的主要内容和关键信息"),
    ]),
)

print(response.text)

原生格式的更多用法（流式、推理预算、Function Calling 等）见 Gemini 原生格式调用。

​

进阶技巧

​

时间戳定位

模型默认按 1 帧/秒采样并理解音频，你可以在提示词里用 MM:SS 直接定位片段——这是纯提示词技巧，任意输入方式都可用：

请描述 00:30 到 01:15 之间发生了什么，并指出 02:40 出现的文字内容。

​

常见任务的提问思路

同一段视频，换提示词就能完成不同分析，无需改代码：

• 内容摘要：用 3-5 句话概括视频主题、关键画面与结论
• 教学分析：提取知识点、章节划分与重点时间戳
• 监控分析：识别异常行为、出现的人/物及发生时间
• 营销评估：分析产品卖点呈现、节奏与目标受众契合度
• 动作分析：拆解动作步骤、姿态要点与可改进之处

​

技术说明

• 采样帧率：默认按 1 帧/秒（FPS） 采样，同时理解音频轨。
• Token 消耗：默认分辨率约 300 tokens/秒，低分辨率约 100 tokens/秒——视频越长，token 越多，请据此估算成本。
• 支持格式：mp4、mpeg、mov（quicktime）、avi、webm、wmv、3gpp 等常见格式。

​

常见问题

传公开视频链接报错 Request contains an invalid argument / 拉取失败

谷歌的视频理解不接收任意公开直链（如 https://example.com/video.mp4），会返回 Request contains an invalid argument。这不是 API易 或 Nginx 拦截。请改用：① Base64 内联（≤20MB）；② YouTube 链接（原生格式）。

为什么限制 20MB？之前明明能用

Base64 内联方式下，整个请求体一直限制在 20MB 以内（与谷歌官方一致）。如果你”之前能用”的是公开直链，那其实从来不是受支持的方式，只是恰好某些情况下没报错；现在按规范会明确拒绝。

能用 files.upload 上传大视频吗？

不能。Gemini 官方的 Files API（client.files.upload()）第三方不支持，仅谷歌官方端点可用。大视频请走 YouTube 链接，或压缩到 20MB 内用 Base64。

超过 20MB 的视频怎么办？

两条路：① 上传到 YouTube 后用链接传入（原生格式，不受 20MB 限制）；② 用 ffmpeg 等工具本地压缩或截取关键片段到 20MB 内再 base64。

​

相关资源

模型列表与价格

查看全部 Gemini 模型与最新定价

Gemini 原生格式

YouTube 链接、流式、推理预算等原生用法

图像理解 API

图片内容识别与多模态分析

API 文档

完整 API 规范与端点说明