灵犀聚合API

API 能力视频理解 API 使用 Gemini 系列等先进 AI 模型进行智能视频分析和理解，支持视频内容识别、场景描述、动作分析等功能

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 速度快，性价比高快速视频分析

🚀 快速开始

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

Copy 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，以确保最佳的处理效果和响应速度。

完整示例 - 包含结果保存

Copy 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}")

使用 requests 库的示例

Copy 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)

🎯 常见应用场景

视频内容摘要

Copy prompt = """ 请分析这个视频并提供详细摘要，包括：

视频的主要内容和主题
关键场景和重要时刻
出现的人物或物体
视频的整体氛围和风格
适合的应用场景或目标受众 """
教学视频分析

Copy prompt = """ 这是一个教学视频，请分析：

教学的主题和知识点
讲解的步骤和流程
使用的教学方法和工具
重点和难点内容
建议的学习要点 """
监控视频分析

Copy prompt = """ 分析这段监控视频：

时间段和地点信息（如果可见）
出现的人员数量和活动
是否存在异常行为或事件
环境变化情况
需要关注的重点内容 """
营销视频评估

Copy prompt = """ 评估这个营销视频的效果：

视频的核心卖点和信息传达
视觉呈现和制作质量
目标受众定位
情感共鸣点
改进建议 """
体育动作分析

Copy prompt = """ 分析视频中的体育动作：

运动项目和动作类型
技术动作的规范性
关键动作要领
可能存在的问题
改进建议 """
💡 最佳实践
视频预处理建议格式支持：MP4、AVI、MOV 等主流视频格式文件大小：建议单个视频不超过 20MB 时长建议：较短的视频片段会获得更精准的分析分辨率：适中的分辨率即可，过高可能增加处理时间编码优化：使用 H.264 等高效编码格式
提示词优化技巧

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

{/_ ✅ 推荐：具体明确的提示 _/} prompt = """ 请从以下几个方面详细分析这个视频：

视频主题：整体内容和主要信息
场景描述：环境、地点、时间等背景信息
主体分析：出现的人物、物体及其行为
动作识别：关键动作和事件序列
情感基调：视频传达的情绪和氛围
应用建议：适合的使用场景和目标受众 """
参数调优建议

Copy {/_ 更准确的分析 _/} 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, )

🔧 高级功能

错误处理和重试机制

Copy 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

批量视频分析

Copy 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")

多轮对话深入分析

Copy 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）分段分析：对长视频可以考虑分段处理缓存结果：对于重复分析的视频，缓存之前的结果

🔗 相关资源完整代码示例 API 定价说明图像理解 API