📚 API文档

Qt图片比对API服务器接口说明

🏠 首页 📊 状态 🔍 图片比对 💡 改进建议 💚 健康检查 ⚠️ 错误码 📝 示例代码

🔍 图片比对接口

POST/api/v1/image/compare

上传两张图片，计算相似度并返回比对结果

请求参数

参数名 类型 必需 描述
image1 File 否* 主图片文件，最大16MB
image1_url String 否* 主图片URL地址
image2 File 否* 对比图片文件，最大16MB
image2_url String 否* 对比图片URL地址
threshold Float 否 相似度阈值(0-100)，默认80.0

*注意：每张图片必须提供文件或URL其中一种方式

请求示例

文件上传方式：

curl -X POST "http://221.130.52.210:10000/api/v1/image/compare" \ -F "image1=@/path/to/image1.jpg" \ -F "image2=@/path/to/image2.jpg" \ -F "threshold=85.0"

URL方式：

curl -X POST "http://221.130.52.210:10000/api/v1/image/compare" \ -F "image1_url=https://example.com/image1.jpg" \ -F "image2_url=https://example.com/image2.jpg"

混合方式：

curl -X POST "http://221.130.52.210:10000/api/v1/image/compare" \ -F "image1=@/path/to/local.jpg" \ -F "image2_url=https://example.com/remote.jpg"

成功响应

{ "code": 0, "message": "Success", "data": { "similarity": { "overall_score": 85.5, "color_similarity": 88.2, "structure_similarity": 82.8, "detail_similarity": 85.5 }, "analysis": { "main_image_analysis": "主图片的详细分析描述", "comparison_analysis": "两张图片的对比分析" }, "processing_time": 2.34, "taskId": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8" } }

响应字段说明

字段名 类型 描述
code Number 业务状态码，0表示成功
message String 提示信息
data.similarity Number 相似度分数 (0-100)
data.taskId String 任务唯一标识符

💡 图像改进建议接口

POST/api/v1/image/suggest

基于两张图片的比对，生成提高相似度的改进建议

请求参数

参数名 类型 必需 描述
image1 File 否* 主图片文件，最大16MB
image1_url String 否* 主图片URL地址
image2 File 否* 目标图片文件，最大16MB
image2_url String 否* 目标图片URL地址

*注意：每张图片必须提供文件或URL其中一种方式

请求示例

curl -X POST "http://221.130.52.210:10000/api/v1/image/suggest" \ -F "image1=@/path/to/main.jpg" \ -F "image2=@/path/to/target.jpg"

成功响应

{ "code": 0, "message": "Success", "data": { "suggestions": [ { "category": "颜色调整", "priority": "高", "description": "建议调整主图片的色调以更接近目标图片", "specific_advice": "将色温调整为更暖的色调" }, { "category": "构图优化", "priority": "中", "description": "建议调整构图比例", "specific_advice": "将主体物品向右移动约10%" } ], "summary": "整体改进建议总结", "processing_time": 3.21, "taskId": "uuid-string" } }

💚 健康检查接口

GET/api/health

检查API服务器状态

请求示例

curl -X GET "http://221.130.52.210:10000/api/health"

响应示例

{ "status": "ok", "service": "Qt Image Comparison API", "version": "1.0", "timestamp": "2025-01-13T10:00:00Z" }

⚠️ 错误码说明

错误码 HTTP状态 描述
0 200 成功
4001 400 图片格式无效
4002 400 缺少图片文件
4003 413 图片文件过大
4004 404 接口不存在
5001 500 服务器内部错误

错误响应示例

{ "code": 4001, "message": "Invalid image format. Only JPEG and PNG are supported.", "data": null }

📝 使用说明

支持的图片格式

  • JPEG (.jpg, .jpeg)
  • PNG (.png)
  • GIF (.gif)
  • WebP (.webp)
  • HEIC (.heic) - 苹果设备格式，自动转换为JPEG
  • HEIF (.heif) - 高效图像格式，自动转换为JPEG

文件大小限制

  • 最大文件大小: 16MB
  • 建议图片尺寸: 1920x1080以下

相似度说明

  • 相似度范围: 0-100
  • 90-100: 极高相似度 - 图片内容高度一致
  • 80-89: 高相似度 - 图片内容很相似
  • 60-79: 中等相似度 - 图片有一定相似性
  • 40-59: 低相似度 - 图片略有相似
  • 0-39: 极低相似度 - 图片差异很大

最新更新说明

  • ✅ 支持URL和文件上传两种方式
  • ✅ 新增图像改进建议接口
  • ✅ 详细的相似度分析（颜色、结构、细节）
  • ✅ 增加文件大小限制到16MB
  • ✅ 支持更多图片格式（JPG, PNG, GIF, WEBP, HEIC, HEIF）

📝 示例代码

Python示例

import requests # 文件上传方式 def compare_images(image1_path, image2_path): url = "http://221.130.52.210:10000/api/v1/image/compare" with open(image1_path, 'rb') as f1, open(image2_path, 'rb') as f2: files = {'image1': f1, 'image2': f2} data = {'threshold': 80.0} response = requests.post(url, files=files, data=data) return response.json() # URL方式 def compare_images_url(url1, url2): url = "http://221.130.52.210:10000/api/v1/image/compare" data = { 'image1_url': url1, 'image2_url': url2, 'threshold': 85.0 } response = requests.post(url, data=data) return response.json() # 使用示例 result = compare_images('image1.jpg', 'image2.jpg') if result['code'] == 0: similarity = result['data']['similarity']['overall_score'] print(f"相似度: {similarity}%")

JavaScript示例

// 文件上传方式 async function compareImages(file1, file2) { const formData = new FormData(); formData.append('image1', file1); formData.append('image2', file2); formData.append('threshold', '80.0'); const response = await fetch('http://221.130.52.210:10000/api/v1/image/compare', { method: 'POST', body: formData }); return await response.json(); } // URL方式 async function compareImagesUrl(url1, url2) { const formData = new FormData(); formData.append('image1_url', url1); formData.append('image2_url', url2); const response = await fetch('http://221.130.52.210:10000/api/v1/image/compare', { method: 'POST', body: formData }); return await response.json(); }

更多示例

查看完整的多语言示例代码，请访问：

📁 API_USAGE_EXAMPLES.md 📁 Qt_Image_API_Postman_Collection.json

包含以下语言的完整示例：

  • Python (requests库)
  • JavaScript (Node.js + 浏览器)
  • Java (OkHttp)
  • C# (HttpClient)
  • PHP (cURL)
  • cURL命令行