API接口文档 - 二维码识别系统

概览

Base URL: http://your-server:5000
所有接口支持 CORS跨域，可直接从浏览器调用。
鉴权方式：在请求头中携带 X-API-Key: your-key （未配置 API_KEY 时无需鉴权）。
统一响应格式：{ "success": bool, "data": {...}, "error": {...} }

GET /api/v1/health

健康检查接口，用于检测服务是否正常运行

响应示例

{
    "success": true,
    "data": {
        "status": "ok",
        "service": "QR Code Scanner API",
        "version": "1.0.0",
        "timestamp": 1234567890.12
    }
}

POST /api/v1/scan

上传图片文件，识别其中的二维码和条形码

请求参数 (multipart/form-data)

参数	类型	必填	说明
`image`	File	必填	图片文件 (png/jpg/bmp/webp)
`include_image`	String	选填	是否返回标注图片，默认 "true"

请求头

Header	必填	说明
`X-API-Key`	选填	API密钥（配置后必填）

cURL 示例

curl -X POST https://your-server:5000/api/v1/scan \
  -H "X-API-Key: your-api-key" \
  -F "image=@qrcode.png" \
  -F "include_image=false"

POST /api/v1/scan/url

通过图片URL地址识别二维码

请求体 (application/json)

字段	类型	必填	说明
`url`	String	必填	图片的URL地址
`include_image`	Boolean	选填	是否返回标注图片，默认 true

cURL 示例

curl -X POST https://your-server:5000/api/v1/scan/url \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"url": "https://example.com/qr.png", "include_image": false}'

POST /api/v1/scan/base64

通过Base64编码的图片数据识别二维码

请求体 (application/json)

字段	类型	必填	说明
`image`	String	必填	Base64编码的图片（支持带data:image前缀）
`include_image`	Boolean	选填	是否返回标注图片，默认 true

cURL 示例

curl -X POST https://your-server:5000/api/v1/scan/base64 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"image": "iVBORw0KGgo...", "include_image": false}'

统一响应格式

成功响应

{
    "success": true,
    "data": {
        "count": 1,
        "elapsed_ms": 45.2,
        "image_size": { "width": 400, "height": 400 },
        "results": [
            {
                "type": "QRCODE",
                "data": "https://example.com",
                "bounding_box": [[40,40], [40,360], [360,360], [360,40]],
                "center": [200, 200]
            }
        ],
        "annotated_image": "data:image/png;base64,..."
    }
}

错误响应

{
    "success": false,
    "error": {
        "code": "MISSING_IMAGE",
        "message": "未检测到上传的图片"
    }
}

错误码列表

code	HTTP状态码	说明
`UNAUTHORIZED`	401	API密钥无效或缺失
`MISSING_IMAGE`	400	未提供图片
`MISSING_URL`	400	未提供URL地址
`EMPTY_FILE`	400	文件为空
`DECODE_ERROR`	400	图片解码失败
`URL_ACCESS_ERROR`	400	无法访问URL
`DOWNLOAD_ERROR`	400	下载图片失败
`BASE64_ERROR`	400	Base64解码失败
`READ_ERROR`	400	读取图片失败

前端对接示例 (JavaScript)

// 方式1: 上传图片文件
const formData = new FormData();
formData.append('image', fileInput.files[0]);

fetch('https://your-server:5000/api/v1/scan', {
    method: 'POST',
    headers: { 'X-API-Key': 'your-api-key' },
    body: formData
})
.then(res => res.json())
.then(data => {
    if (data.success) {
        console.log('识别到', data.data.count, '个码');
        data.data.results.forEach(r => console.log(r.type, r.data));
    }
});

// 方式2: 通过URL识别
fetch('https://your-server:5000/api/v1/scan/url', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-API-Key': 'your-api-key'
    },
    body: JSON.stringify({ url: 'https://example.com/qr.png' })
})
.then(res => res.json())
.then(data => console.log(data));