GLM-V 图像描述技能

使用智谱 GLM-V 多模态模型为图像、视频和文档生成描述。

适用场景

• 描述、生成标题、总结或解释图像/视频/文档内容
• 用户提及“描述这张图片”、“生成标题”、“总结这段视频”、“图片描述”、“视频摘要”、“文档解读”、“看图说话”
• 从媒体文件中提取视觉或文本信息
• 比较多张图片
• 用户提供一张图片/视频/文件并询问其中内容

支持的输入类型

**⚠️ file_url 不能与 image_url 或 video_url 在同一请求中混用。**

⚠️ 视频和文档仅支持 URL —— 不支持本地路径或 Base64 编码（仅图像支持）。

资源链接

前置条件

API Key 配置（必需）

该脚本通过 ZHIPU_API_KEY 环境变量读取密钥，并与其他智谱技能共享同一个密钥。

获取密钥： 访问 [智谱开放平台 API Keys](https://bigmodel.cn/usercenter/proj-mgmt/apikeys) 创建或复制您的 API 密钥。

配置方式（任选其一）：

1. OpenClaw 配置（推荐）： 在 openclaw.json 中设置 skills.entries.glmv-caption.env：

"glmv-caption": { "enabled": true, "env": { "ZHIPU_API_KEY": "你的密钥" } }

1. Shell 环境变量： 添加至 ~/.zshrc：

export ZHIPU_API_KEY="你的密钥"

1. .env 文件： 在本技能目录下创建 .env 文件：

ZHIPU_API_KEY=你的密钥

⛔ 强制限制 - 严禁违反 ⛔

1. 仅使用 GLM-V API —— 执行脚本 python scripts/glmv_caption.py
2. 绝不自行描述媒体内容 —— 不得使用内置视觉能力或其他方法尝试描述
3. 绝不提供替代方案 —— 不得建议“我可以试试描述一下”等类似说法
4. 若 API 失败 —— 显示错误信息并立即停止
5. 无备用方法 —— 不得尝试其他任何方式生成描述

📋 输出显示规则（强制要求）

运行脚本后，必须将原始返回结果完整展示给用户，不得摘要、截断或仅提示“已生成”。用户需要原始模型输出以评估质量。

• 图像描述：显示完整的描述文本
• 多张图像：逐个展示每张图像的结果
• 视频/文档：显示完整的理解结果
• 若包含 token 使用量，可选择性显示

使用方法

描述单张图像

python scripts/glmv_caption.py --images "https://example.com/photo.jpg"
python scripts/glmv_caption.py --images /path/to/photo.png

描述多张图像

python scripts/glmv_caption.py --images img1.jpg img2.png "https://example.com/img3.jpg"

描述视频

python scripts/glmv_caption.py --videos "https://example.com/clip.mp4"

描述文档

python scripts/glmv_caption.py --files "https://example.com/report.pdf"
python scripts/glmv_caption.py --files "https://example.com/doc1.docx" "https://example.com/doc2.txt"

自定义提示词

python scripts/glmv_caption.py --images photo.jpg --prompt "详细描述建筑风格"

保存结果

python scripts/glmv_caption.py --images photo.jpg --output result.json

思考模式

python scripts/glmv_caption.py --images photo.jpg --thinking

CLI 参考

python {baseDir}/scripts/glmv_caption.py (--images IMG [IMG...] | --videos VID [VID...] | --files FILE [FILE...]) [OPTIONS]

注意： --images、--videos 和 --files 三者在单次请求中互斥，受 API 限制。

响应格式

{
  "success": true,
  "caption": "一张展示日落时分山脉景观的风景照片...",
  "usage": {
    "prompt_tokens": 128,
    "completion_tokens": 256,
    "total_tokens": 384
  }
}

关键字段说明：

• success — 请求是否成功
• caption — 生成的描述文本
• usage — token 使用统计信息
• warning — 当内容被安全审查拦截时出现
• error — 请求失败时的错误详情

错误处理

API 密钥未配置：

ZHIPU_API_KEY not configured. Get your API key at: https://bigmodel.cn/usercenter/proj-mgmt/apikeys

→ 向用户展示完整错误信息，并引导其完成配置

认证失败（401/403）： API 密钥无效或已过期 → 请重新配置

速率限制（429）： 配额已耗尽 → 告知用户等待后重试

文件未找到： 本地文件路径不存在 → 检查文件路径是否正确

内容被过滤： warning 字段存在 → 内容因安全审查被拦截