⚡

Gemini视觉API技能Skill gemini-vision

此技能基于Google的Gemini API，实现图像理解和分析功能，支持图像描述、分类、视觉问答、对象检测、分割和多图像比较，适用于AI应用和计算机视觉任务，关键词：图像理解、Gemini API、人工智能、计算机视觉、图像分析、AI模型。

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

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

  • Bash
  • Read
  • Write
  • Edit

Gemini 视觉 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 令牌

速率限制

限制因层级而异 (免费、Tier 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. 使用 3 步查找检查 API 密钥可用性
  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