⚡

Gemini视觉API技能Skill gemini-vision

这个技能使用Google Gemini API实现高级图像理解功能，包括图像描述、分类、视觉问答、对象检测、分割和多图像分析。适用于图像分析、视觉问题回答、对象检测或处理带有视觉的文档，关键词：Gemini API, 图像理解, 计算机视觉, AI视觉分析。

计算机视觉 0 次安装 0 次浏览 更新于 3/20/2026

名称: gemini-vision 描述: 实施Google Gemini API图像理解的指南 - 使用标题生成、分类、视觉问答、对象检测、分割和多图像比较分析图像。在分析图像、回答视觉问题、检测对象或处理带有视觉的文档时使用。 许可证: MIT 允许的工具:

  • Bash
  • Read
  • Write
  • Edit

Gemini Vision API 技能

这个技能使Claude能够使用Google的Gemini API进行高级图像理解任务，包括标题生成、分类、视觉问答、对象检测、分割和多图像分析。

快速开始

前提条件

  1. 获取API密钥: 从 Google AI Studio 获取
  2. 安装SDK: pip install google-genai (Python 3.9+)

API密钥配置

该技能按以下顺序检查 GEMINI_API_KEY：

  1. 进程环境变量 (推荐)

    export GEMINI_API_KEY="your-api-key"

  2. 技能目录: .claude/skills/gemini-vision/.env

    GEMINI_API_KEY=your-api-key

  3. 项目目录: 项目根目录中的 .env 或 .gemini_api_key

安全: 切勿将API密钥提交到版本控制。将 .env 添加到 .gitignore。

核心能力

图像分析

  • 标题生成: 为图像生成描述性文本
  • 分类: 对图像内容进行分类和识别
  • 视觉问答: 回答关于图像内容的问题
  • 多图像: 比较和分析多达3,600张图像

高级功能 (模型特定)

  • 对象检测: 使用边界框识别和定位对象 (Gemini 2.0+)
  • 分割: 为对象创建像素级掩码 (Gemini 2.5+)
  • 文档理解: 处理带有视觉的PDF文档 (最多1,000页)

支持的格式

  • 图像: PNG, JPEG, WEBP, HEIC, HEIF
  • 文档: PDF (最多1,000页)
  • 大小限制:
    • 内联: 最大总请求大小20MB
    • 文件API: 用于较大文件
    • 最大图像数: 每个请求3,600张

可用模型

  • gemini-2.5-pro: 功能最强大，分割 + 检测
  • gemini-2.5-flash: 快速高效，分割 + 检测
  • gemini-2.5-flash-lite: 轻量级，分割 + 检测
  • gemini-2.0-flash: 支持对象检测
  • gemini-1.5-pro/flash: 上一代

使用示例

基本图像分析

# 分析本地图像
python scripts/analyze-image.py path/to/image.jpg "What's in this image?"

# 从URL分析
python scripts/analyze-image.py https://example.com/image.jpg "Describe this"

# 指定模型
python scripts/analyze-image.py image.jpg "Caption this" --model gemini-2.5-pro

对象检测 (2.0+)

python scripts/analyze-image.py image.jpg "Detect all objects" --model gemini-2.0-flash

多图像比较

python scripts/analyze-image.py img1.jpg img2.jpg "What's different between these?"

文件上传 (用于大文件或重复使用)

# 上传文件
python scripts/upload-file.py path/to/large-image.jpg

# 使用上传的文件
python scripts/analyze-image.py file://file-id "Caption this"

文件管理

# 列出上传的文件
python scripts/manage-files.py list

# 获取文件信息
python scripts/manage-files.py get file-id

# 删除文件
python scripts/manage-files.py delete file-id

令牌成本

图像根据大小消耗令牌：

  • 小 (两个维度都≤384px): 258个令牌
  • 大: 分割成768×768块，每块258个令牌

令牌公式:

crop_unit = floor(min(width, height) / 1.5)
tiles = (width / crop_unit) × (height / crop_unit)
total_tokens = tiles × 258

示例: 960×540图像 = 6块 = 1,548个令牌

速率限制

限制因层级而异 (免费, 第1层, 第2层, 第3层):

  • 以RPM (请求/分钟), TPM (令牌/分钟), RPD (请求/天) 衡量
  • 按项目应用，不是按API密钥
  • RPD在太平洋时间午夜重置

最佳实践

图像质量

  • 使用清晰、不模糊的图像
  • 验证正确的图像旋转
  • 调整大小时考虑令牌成本

提示

  • 在指令中具体明确
  • 对于单图像提示，将文本放在图像后
  • 使用少量示例以获得更好的准确性
  • 指定输出格式 (JSON, markdown等)

文件管理

  • 对于大于20MB的文件使用文件API
  • 对于重复使用使用文件API (节省令牌)
  • 文件在48小时后自动删除
  • 完成后手动清理

安全

  • 切勿在代码中暴露API密钥
  • 使用环境变量
  • 在Google Cloud Console中添加API密钥限制
  • 定期监控使用情况
  • 定期轮换密钥

错误处理

常见错误：

  • 401: 无效的API密钥
  • 429: 超过速率限制
  • 400: 无效请求 (检查文件大小、格式)
  • 403: 权限被拒绝 (检查API密钥限制)

额外资源

查看 references/ 目录获取：

实施指南

当实施Gemini视觉功能时：

  1. 检查API密钥可用性 使用3步查找
  2. 选择适当的模型 基于需求：
    • 需要分割？使用2.5+模型
    • 需要检测？使用2.0+模型
    • 需要速度？使用Flash变体
    • 需要质量？使用Pro变体
  3. 验证输入：
    • 检查文件格式 (PNG, JPEG, WEBP, HEIC, HEIF, PDF)
    • 验证文件大小 (<20MB用于内联, >20MB使用文件API)
    • 计数图像 (最大3,600)
  4. 适当处理响应：
    • 如果请求，解析结构化输出
    • 提取对象检测的边界框
    • 处理分割掩码 (如果适用)
  5. 高效管理文件：
    • 通过文件API上传大文件
    • 尽可能重复使用上传的文件
    • 使用后清理

脚本概述

所有脚本都支持3步API密钥查找：

运行任何脚本时使用 --help 获取详细的使用说明。

官方文档: https://ai.google.dev/gemini-api/docs/image-understanding