视觉大模型

Vision VLM 服务器 API 文档

VLM-skill视觉大模型工具，基于阿里云千问视觉理解大模型（默认 qwen3.6-plus）的多模态识别服务，提供文件上传、视觉语言理解（VLM）等接口。主要支持图片识别和处理：原生支持文字识别、物体识别、内建多模态大语言模型能力。

  • 基础地址：http://<host>:<port> （默认 http://vlm.html.dtns.top）
  • 认证方式：通过请求头 X-API-Key 或 JSON/Form 字段 apiKey 传递 DashScope API Key。
  • 内容类型：
    • application/json 用于 JSON 请求体
    • multipart/form-data 用于文件上传

目录

  1. 健康检查
  2. 服务器信息
  3. 通用文件上传
  4. VLM 图片识别（文件上传）
  5. VLM 图片识别（Base64）
  6. VLM 图片识别（图片URL）
  7. 错误响应格式

1. 健康检查

检查服务器运行状态、模型及配置信息。

请求示例（curl）

curl http://vlm.html.dtns.top/health

响应示例

{
  "status": "ok",
  "service": "Vision LLM VLM Server",
  "model": "qwen3.6-plus",
  "apiUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions",
  "defaultPrompt": "提取文字，如果有表格，则需包含表格输出",
  "uptime": 123.456
}

2. 服务器信息

返回服务器详细配置及支持的接口列表。

请求示例（curl）

curl http://vlm.html.dtns.top/info

响应示例

{
  "name": "Vision LLM VLM Server",
  "version": "3.0.0",
  "model": "qwen3.6-plus",
  "maxFileSize": 10485760,
  "supportedFormats": ["jpeg", "jpg", "png", "gif", "bmp", "tiff", "webp"],
  "defaultPrompt": "提取文字，如果有表格，则需包含表格输出",
  "endpoints": {
    "upload": "/api/upload",
    "vlm": "/api/vlm",
    "vlmBase64": "/api/vlm/base64",
    "vlmURL": "/api/vlm/url",
    "health": "/health",
    "info": "/info"
  }
}

3. 通用文件上传

上传任意类型文件到服务器，返回可下载的文件链接。

请求参数

参数 类型 必需 说明
file File 是 上传的文件（表单字段名必须为 file）

请求示例（curl）

curl -X POST \
  -F "file=@/path/to/document.pdf" \
  http://vlm.html.dtns.top/api/upload

响应示例（成功）

{
  "success": true,
  "message": "文件上传成功",
  "file": {
    "originalName": "document.pdf",
    "filename": "1712345678901-123456789.pdf",
    "size": 204800,
    "mimetype": "application/pdf",
    "url": "http://vlm.html.dtns.top/uploads/1712345678901-123456789.pdf"
  }
}

返回的 url 可直接用于下载或作为 VLM URL 识别的输入。

4. VLM 图片识别（文件上传）

上传图片文件，调用千问视觉大模型进行多模态识别，支持自定义提示词。

请求参数

参数 类型 必需 说明
image File 是 图片文件（支持 jpeg, jpg, png, gif, bmp, tiff, webp）
prompt String 否 自定义提示词，默认使用服务器的 defaultPrompt
apiKey String 否 DashScope API Key。优先级：请求头 X-API-Key > 此字段 > 服务器默认 key

注意：若使用 API Key，建议通过 X-API-Key 请求头传递。

请求示例（curl）

基础请求（使用默认提示词，需提前设置服务器 API Key）：

curl -X POST \
  -F "image=@test.png" \
  http://vlm.html.dtns.top/api/vlm

携带 API Key 和自定义提示词：

curl -X POST \
  -H "X-API-Key: sk-your-dashscope-key" \
  -F "image=@photo.jpg" \
  -F "prompt=描述图片中的主要内容，并用JSON输出" \
  http://vlm.html.dtns.top/api/vlm

通过表单字段传递 API Key：

curl -X POST \
  -F "image=@photo.jpg" \
  -F "apiKey=sk-your-key" \
  -F "prompt=提取文字，保留表格格式" \
  http://vlm.html.dtns.top/api/vlm

响应示例（成功）

{
  "success": true,
  "text": "图片中包含以下文字：\n标题：会议纪要\n...",
  "processingTime": "1234ms",
  "model": "qwen3.6-plus",
  "prompt": "提取文字，保留表格格式",
  "usage": {
    "prompt_tokens": 256,
    "completion_tokens": 120,
    "total_tokens": 376
  }
}

响应示例（失败）

{
  "success": false,
  "error": "请提供有效的 DashScope API Key",
  "processingTime": "0ms"
}

5. VLM 图片识别（Base64）

通过 Base64 编码的图片数据进行识别，适用于非文件上传的场景。

请求体（JSON）

字段 类型 必需 说明
image String 是 图片的 Base64 数据，支持完整 Data URL（data:image/...;base64,...）或纯 Base64 字符串
prompt String 否 自定义提示词
apiKey String 否 API Key（也可通过 X-API-Key 请求头提供）

请求示例（curl）

使用完整 Data URL：

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-your-key" \
  -d '{
    "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "prompt": "请提取图片中的文字"
  }' \
  http://vlm.html.dtns.top/api/vlm/base64

使用纯 Base64 字符串：

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{ 
    "image": "iVBORw0KGgoAAAANSUhEUgAA...",
    "apiKey": "sk-your-key",
    "prompt": "用中文描述图片内容"
  }' \
  http://vlm.html.dtns.top/api/vlm/base64

从本地文件生成 Base64 后调用（Linux/macOS）：

# 生成 base64 字符串
IMAGE_BASE64=$(base64 -w 0 photo.jpg)
# 调用接口
curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-your-key" \
  -d "{\"image\":\"$IMAGE_BASE64\", \"prompt\":\"描述图片\"}" \
  http://vlm.html.dtns.top/api/vlm/base64

响应格式

同 VLM 图片识别（文件上传） 的响应。

6. VLM 图片识别（图片 URL）

通过可直接访问的图片链接进行识别。

请求体（JSON）

字段 类型 必需 说明
url String 是 可公开访问的图片链接（HTTP/HTTPS）
prompt String 否 自定义提示词
apiKey String 否 API Key（也可通过请求头提供）

请求示例（curl）

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-your-key" \
  -d '{
    "url": "https://example.com/chart.png",
    "prompt": "提取图表中的数据，用CSV格式输出"
  }' \
  http://vlm.html.dtns.top/api/vlm/url

结合文件上传功能（先上传，再识别）：

# 1. 上传图片，获取 URL
UPLOAD_RESPONSE=$(curl -s -X POST -F "file=@photo.jpg" http://vlm.html.dtns.top/api/upload)
IMAGE_URL=$(echo $UPLOAD_RESPONSE | grep -o '"url":"[^"]*"' | cut -d'"' -f4)

# 2. 使用该 URL 进行 VLM 识别
curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-your-key" \
  -d "{\"url\":\"$IMAGE_URL\", \"prompt\":\"总结图片内容\"}" \
  http://vlm.html.dtns.top/api/vlm/url

响应格式

同 VLM 图片识别（文件上传） 的响应。

7. 错误响应格式

所有接口在失败时均返回统一的 JSON 结构：

{
  "success": false,
  "error": "具体错误信息",
  "timestamp": "2026-04-29T08:30:00.000Z"  // 仅服务器内部错误时包含
}

常见 HTTP 状态码：

  • 400：请求参数错误（如缺少文件、无效格式）
  • 500：服务器内部错误

全局配置说明

  • 默认提示词：提取文字，如果有表格，则需包含表格输出（可通过命令行 --default-prompt 修改）
  • 文件大小限制：默认 10MB（可通过命令行 --max-file-size 修改）
  • 支持图片格式：JPEG、PNG、GIF、BMP、TIFF、WebP
  • CORS：默认允许所有来源（*）

完整测试流程示例（curl）

# 1. 检查服务是否运行
curl http://vlm.html.dtns.top/health

# 2. 上传一个图片文件
curl -X POST -F "file=@screenshot.png" http://vlm.html.dtns.top/api/upload
# 返回: {"success":true, "file":{"url":"http://vlm.html.dtns.top/uploads/xxx.png",...}}

# 3. 使用文件上传方式直接识别
curl -X POST \
  -H "X-API-Key: sk-your-key" \
  -F "image=@screenshot.png" \
  -F "prompt=提取所有文字，保留段落结构" \
  http://vlm.html.dtns.top/api/vlm

# 4. 使用 Base64 方式识别（从图片文件生成）
IMAGE_64=$(base64 -w 0 screenshot.png)
curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-your-key" \
  -d "{\"image\":\"$IMAGE_64\", \"prompt\":\"有什么物体？\"}" \
  http://vlm.html.dtns.top/api/vlm/base64

# 5. 使用 URL 方式识别（先上传得到链接）
URL="http://vlm.html.dtns.top/uploads/xxx.png"
curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-your-key" \
  -d "{\"url\":\"$URL\", \"prompt\":\"用英文描述图片\"}" \
  http://vlm.html.dtns.top/api/vlm/url