视频理解 API

API易提供强大的视频理解能力，支持使用 Gemini 2.5 Pro 等先进的 AI 模型对视频进行深度分析和理解。通过统一的 OpenAI API 格式，您可以轻松实现视频内容识别、场景描述、动作分析等功能。

🎬 智能视频分析 支持视频场景理解、动作识别、内容摘要等多种视频分析任务，让 AI 真正”看懂”视频内容。

🌟 核心特性

🎯 顶级模型支持：Gemini 2.5 Pro 等领先的多模态视频理解模型
📹 灵活输入：支持 Base64 编码视频文件
🌏 中文优化：完美支持中文场景理解和内容描述
⚡ 专业分析：深度理解视频内容、动作、场景和上下文
💰 高性价比：强大能力，合理定价

📋 支持的视频理解模型

模型名称	模型 ID	特点	推荐场景
Gemini 2.5 Pro ⭐	`gemini-2.5-pro`	超长上下文，视频理解能力强	复杂视频内容分析
Gemini 2.5 Flash	`gemini-2.5-flash`	速度快，性价比高	快速视频分析

🚀 快速开始

1. 基础示例 - 本地视频 Base64 编码

from openai import OpenAI
import base64

def gemini_video_test(video_path, question, model="gemini-2.5-pro"):
    """视频理解函数"""
    client = OpenAI(
        api_key="YOUR_API_KEY",  # 替换为您的 API Key
        base_url="https://api.apiyi.com/v1"
    )

    {/* 读取本地视频文件并转换为 Base64 */}
    with open(video_path, "rb") as f:
        video_b64 = base64.b64encode(f.read()).decode()
        video_url = f"data:video/mp4;base64,{video_b64}"

    response = client.chat.completions.create(
        model=model,
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": question},
                    {
                        "type": "image_url",
                        "image_url": {
                            "url": video_url
                        },
                        "mime_type": "video/mp4",
                    }
                ]
            }
        ],
        temperature=0.2,
        max_tokens=4096
    )

    return response.choices[0].message.content

{/* 使用示例 */}
if __name__ == "__main__":
    video_path = "./demo.mp4"  # 本地视频文件路径
    question = "请详细描述这个视频的内容"

    result = gemini_video_test(video_path, question)
    print(result)

文件大小限制：建议单个视频文件不超过 20MB，以确保最佳的处理效果和响应速度。

2. 完整示例 - 包含结果保存

from openai import OpenAI
import base64
import json
from datetime import datetime
import os

def gemini_test(question, model="gemini-2.5-pro"):
    client = OpenAI(
        api_key="YOUR_API_KEY",
        base_url="https://api.apiyi.com/v1"
    )

    model = model
    user_msg = question

    VIDEO_PATH = "./demo.mp4"   # 本地文件，≤20 MB 为佳
    with open(VIDEO_PATH, "rb") as f:
        video_b64 = base64.b64encode(f.read()).decode()
        video_url = f"data:video/mp4;base64,{video_b64}"

    response = client.chat.completions.create(
        model=model,
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": question},
                    {
                        "type": "image_url",
                        "image_url": {
                            "url": video_url
                        },
                        "mime_type": "video/mp4",
                    }
                ]
            }
        ],
        temperature=0.2,
        max_tokens=4096
    )

    return response.choices[0].message.content

if __name__ == "__main__":
    print("开始视频理解测试...")

    {/* 运行视频理解 */}
    question = "请描述这个视频的内容"
    result = gemini_test(question)

    {/* 生成时间戳 */}
    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")

    {/* 获取当前脚本所在目录 */}
    current_dir = os.path.dirname(os.path.abspath(__file__))

    {/* 保存为txt文件 */}
    txt_filename = os.path.join(current_dir, f"video_analysis_{timestamp}.txt")
    with open(txt_filename, "w", encoding="utf-8") as f:
        f.write("=" * 60 + "\n")
        f.write("视频理解分析结果\n")
        f.write("=" * 60 + "\n")
        f.write(f"分析时间: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n")
        f.write(f"提问内容: {question}\n")
        f.write("=" * 60 + "\n\n")
        f.write(result)
        f.write("\n\n" + "=" * 60 + "\n")

    {/* 保存为json文件 */}
    json_filename = os.path.join(current_dir, f"video_analysis_{timestamp}.json")
    data = {
        "timestamp": datetime.now().strftime('%Y-%m-%d %H:%M:%S'),
        "question": question,
        "model": "gemini-2.5-pro",
        "video_file": "demo.mp4",
        "result": result
    }
    with open(json_filename, "w", encoding="utf-8") as f:
        json.dump(data, f, ensure_ascii=False, indent=2)

    {/* 控制台输出 */}
    print("\n视频理解结果：")
    print(result)
    print(f"\n结果已保存到:")
    print(f"  - TXT文件: {txt_filename}")
    print(f"  - JSON文件: {json_filename}")

3. 使用 requests 库的示例

import requests
import base64

def analyze_video_with_requests(video_path, question):
    """使用 requests 库进行视频分析"""

    {/* 读取并编码视频 */}
    with open(video_path, "rb") as f:
        video_b64 = base64.b64encode(f.read()).decode()
        video_url = f"data:video/mp4;base64,{video_b64}"

    url = "https://api.apiyi.com/v1/chat/completions"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    }

    payload = {
        "model": "gemini-2.5-pro",
        "messages": [
            {"role": "system", "content": "You are a helpful assistant."},
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": question},
                    {
                        "type": "image_url",
                        "image_url": {"url": video_url},
                        "mime_type": "video/mp4"
                    }
                ]
            }
        ],
        "temperature": 0.2,
        "max_tokens": 4096
    }

    response = requests.post(url, headers=headers, json=payload)

    if response.status_code == 200:
        return response.json()['choices'][0]['message']['content']
    else:
        print(f"错误: {response.status_code} - {response.text}")
        return None

{/* 使用示例 */}
result = analyze_video_with_requests("./demo.mp4", "请描述这个视频的内容")
print(result)

🎯 常见应用场景

1. 视频内容摘要

prompt = """
请分析这个视频并提供详细摘要，包括：
1. 视频的主要内容和主题
2. 关键场景和重要时刻
3. 出现的人物或物体
4. 视频的整体氛围和风格
5. 适合的应用场景或目标受众
"""

2. 教学视频分析

prompt = """
这是一个教学视频，请分析：
1. 教学的主题和知识点
2. 讲解的步骤和流程
3. 使用的教学方法和工具
4. 重点和难点内容
5. 建议的学习要点
"""

3. 监控视频分析

prompt = """
分析这段监控视频：
1. 时间段和地点信息（如果可见）
2. 出现的人员数量和活动
3. 是否存在异常行为或事件
4. 环境变化情况
5. 需要关注的重点内容
"""

4. 营销视频评估

prompt = """
评估这个营销视频的效果：
1. 视频的核心卖点和信息传达
2. 视觉呈现和制作质量
3. 目标受众定位
4. 情感共鸣点
5. 改进建议
"""

5. 体育动作分析

prompt = """
分析视频中的体育动作：
1. 运动项目和动作类型
2. 技术动作的规范性
3. 关键动作要领
4. 可能存在的问题
5. 改进建议
"""

💡 最佳实践

视频预处理建议

格式支持：MP4、AVI、MOV 等主流视频格式
文件大小：建议单个视频不超过 20MB
时长建议：较短的视频片段会获得更精准的分析
分辨率：适中的分辨率即可，过高可能增加处理时间
编码优化：使用 H.264 等高效编码格式

提示词优化技巧

{/* ❌ 不推荐：模糊的提示 */}
prompt = "看看这个视频"

{/* ✅ 推荐：具体明确的提示 */}
prompt = """
请从以下几个方面详细分析这个视频：
1. 视频主题：整体内容和主要信息
2. 场景描述：环境、地点、时间等背景信息
3. 主体分析：出现的人物、物体及其行为
4. 动作识别：关键动作和事件序列
5. 情感基调：视频传达的情绪和氛围
6. 应用建议：适合的使用场景和目标受众
"""

参数调优建议

{/* 更准确的分析 */}
response = client.chat.completions.create(
    model="gemini-2.5-pro",
    messages=messages,
    temperature=0.2,      # 降低随机性，提高准确性
    max_tokens=4096,      # 足够的输出长度
)

{/* 更有创意的描述 */}
response = client.chat.completions.create(
    model="gemini-2.5-pro",
    messages=messages,
    temperature=0.7,      # 提高创意性
    max_tokens=2048,
)

🔧 高级功能

1. 错误处理和重试机制

import time
from openai import OpenAI

def analyze_video_with_retry(video_path, question, max_retries=3):
    """带重试机制的视频分析"""
    client = OpenAI(
        api_key="YOUR_API_KEY",
        base_url="https://api.apiyi.com/v1"
    )

    with open(video_path, "rb") as f:
        video_b64 = base64.b64encode(f.read()).decode()
        video_url = f"data:video/mp4;base64,{video_b64}"

    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="gemini-2.5-pro",
                messages=[
                    {
                        "role": "user",
                        "content": [
                            {"type": "text", "text": question},
                            {
                                "type": "image_url",
                                "image_url": {"url": video_url},
                                "mime_type": "video/mp4"
                            }
                        ]
                    }
                ],
                temperature=0.2,
                max_tokens=4096
            )
            return response.choices[0].message.content

        except Exception as e:
            print(f"尝试 {attempt + 1}/{max_retries} 失败: {e}")
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)  # 指数退避
            else:
                raise

    return None

2. 批量视频分析

import os
import glob

def batch_analyze_videos(video_dir, question):
    """批量分析文件夹中的所有视频"""
    video_files = glob.glob(os.path.join(video_dir, "*.mp4"))
    results = {}

    for video_file in video_files:
        print(f"分析视频: {os.path.basename(video_file)}")
        try:
            result = gemini_video_test(video_file, question)
            results[video_file] = result
        except Exception as e:
            print(f"分析失败: {e}")
            results[video_file] = f"错误: {str(e)}"

    return results

{/* 使用示例 */}
results = batch_analyze_videos("./videos", "请描述这个视频的主要内容")
for video, analysis in results.items():
    print(f"\n{video}:\n{analysis}\n")

3. 多轮对话深入分析

def interactive_video_analysis(video_path):
    """交互式视频分析"""
    client = OpenAI(
        api_key="YOUR_API_KEY",
        base_url="https://api.apiyi.com/v1"
    )

    {/* 读取视频 */}
    with open(video_path, "rb") as f:
        video_b64 = base64.b64encode(f.read()).decode()
        video_url = f"data:video/mp4;base64,{video_b64}"

    messages = []

    {/* 初始分析 */}
    messages.append({
        "role": "user",
        "content": [
            {"type": "text", "text": "请分析这个视频的内容"},
            {
                "type": "image_url",
                "image_url": {"url": video_url},
                "mime_type": "video/mp4"
            }
        ]
    })

    response = client.chat.completions.create(
        model="gemini-2.5-pro",
        messages=messages,
        temperature=0.2,
        max_tokens=4096
    )

    assistant_message = response.choices[0].message.content
    print(f"AI: {assistant_message}\n")
    messages.append({"role": "assistant", "content": assistant_message})

    {/* 继续提问 */}
    while True:
        user_question = input("您的问题 (输入 'quit' 退出): ")
        if user_question.lower() == 'quit':
            break

        messages.append({
            "role": "user",
            "content": [{"type": "text", "text": user_question}]
        })

        response = client.chat.completions.create(
            model="gemini-2.5-pro",
            messages=messages,
            temperature=0.2,
            max_tokens=4096
        )

        assistant_message = response.choices[0].message.content
        print(f"AI: {assistant_message}\n")
        messages.append({"role": "assistant", "content": assistant_message})

📊 模型对比

模型	视频理解能力	响应速度	上下文长度	价格
Gemini 2.5 Pro	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	超长	$$
Gemini 2.5 Flash	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	长	$

🚨 注意事项

文件大小：建议单个视频文件不超过 20MB，以确保最佳性能
隐私保护：不要上传包含敏感信息或隐私内容的视频
合规使用：遵守相关法律法规，不用于非法用途
结果验证：AI 分析结果仅供参考，重要决策需人工复核
成本控制：视频分析消耗的 token 较多，请合理使用
视频格式：确保视频格式被支持（MP4 格式兼容性最好）

💰 成本优化建议

视频预处理：上传前适当压缩视频，减小文件大小
精准提问：使用明确的问题，避免重复分析
模型选择：根据需求选择合适的模型（Flash vs Pro）
分段分析：对长视频可以考虑分段处理
缓存结果：对于重复分析的视频，缓存之前的结果

🔗 相关资源

💡 小贴士：视频理解功能特别适合自动化内容审核、视频摘要生成、教学视频分析等场景。建议先使用 Gemini 2.5 Flash 进行测试，确认效果后根据需求选择合适的模型。

产品基础

API 能力

🌟 核心特性

📋 支持的视频理解模型

🚀 快速开始

1. 基础示例 - 本地视频 Base64 编码

2. 完整示例 - 包含结果保存

3. 使用 requests 库的示例

🎯 常见应用场景

1. 视频内容摘要

2. 教学视频分析

3. 监控视频分析

4. 营销视频评估

5. 体育动作分析

💡 最佳实践

视频预处理建议

提示词优化技巧

参数调优建议

🔧 高级功能

1. 错误处理和重试机制

2. 批量视频分析

3. 多轮对话深入分析

📊 模型对比

🚨 注意事项

💰 成本优化建议

🔗 相关资源

产品基础

API 能力

​🌟 核心特性

​📋 支持的视频理解模型

​🚀 快速开始

​1. 基础示例 - 本地视频 Base64 编码

​2. 完整示例 - 包含结果保存

​3. 使用 requests 库的示例

​🎯 常见应用场景

​1. 视频内容摘要

​2. 教学视频分析

​3. 监控视频分析

​4. 营销视频评估

​5. 体育动作分析

​💡 最佳实践

​视频预处理建议

​提示词优化技巧

​参数调优建议

​🔧 高级功能

​1. 错误处理和重试机制

​2. 批量视频分析

​3. 多轮对话深入分析

​📊 模型对比

​🚨 注意事项

​💰 成本优化建议

​🔗 相关资源

🌟 核心特性

📋 支持的视频理解模型

🚀 快速开始

1. 基础示例 - 本地视频 Base64 编码

2. 完整示例 - 包含结果保存

3. 使用 requests 库的示例

🎯 常见应用场景

1. 视频内容摘要

2. 教学视频分析

3. 监控视频分析

4. 营销视频评估

5. 体育动作分析

💡 最佳实践

视频预处理建议

提示词优化技巧

参数调优建议

🔧 高级功能

1. 错误处理和重试机制

2. 批量视频分析

3. 多轮对话深入分析

📊 模型对比

🚨 注意事项

💰 成本优化建议

🔗 相关资源