视觉大模型

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