智能扫描API接口文档 - 文档矫正/去阴影/增强锐化

可立图 ClipImg 智能扫描 API 服务

接口概述 #

本接口提供智能文档扫描、切边矫正、A4排版等功能。支持多种证件类型（身份证、户口本、护照等）及通用文档的扫描处理。

使用场景 #

文档电子化：将纸质文档（合同、发票、笔记）快速转换为清晰的电子扫描件。
证件扫描：自动识别并裁剪身份证、护照、驾驶证等证件，支持正反面A4排版。
试卷/作业扫描：去除背景杂乱，保留清晰的文字内容。

调用流程 #

智能扫描 (/pic/scan)：上传原始图片，获取初步的切边结果和 image_id。
(可选) 手动调整 (/pic/scan/auto_crop)：如果智能切边不准确，使用 image_id 和自定义坐标 points 进行修正。
(可选) A4排版 (/pic/scan/auto_crop_imgs)：将单张或多张处理好的图片（通过 image_id）自动排版到A4纸上，生成PDF或长图。

在线演示: 试一试
Postman: 文档

限制说明 #

QPS限制：1次/秒，20次/分钟。超过限制需另外收费或联系客服开通高额度。

1. 智能扫描接口 #

上传图片进行智能扫描，自动识别文档边缘并进行切边矫正。

接口地址: https://www.clipimg.com/api/pic/scan
请求方式: POST
Content-Type: application/json
需要API Key: 是

请求参数 #

参数	类型	必选	说明
file	string	是	Base64格式图片数据（不包含头部）
card_type	int	否	证件类型（见下表），默认为7（文档）
dpi	int	否	返回图片分辨率，默认300

card_type 取值说明

值	说明
1	身份证
2	户口本
3	护照
4	驾驶证
5	行驶证
6	银行卡
7	文档 (默认)

响应格式 #

{
  "code": 0,
  "msg": "Success",
  "data": {
    "points": [[114, 92], [543, 92], [543, 400], [114, 400]],
    "image_id": "unique_image_id_xxx",
    "filenames": {
      "preview_url": "https://www.clipimg.com/api/pic/scan/preview/xxx_scan_crop_preview",
      "download_url": "https://www.clipimg.com/api/pic/scan/download/xxx_scan_crop",
      "preview_img_name": "xxx_scan_crop_preview",
      "img_name": "xxx_scan_crop"
    }
  }
}

2. 扫描裁剪接口 (手动调整) #

如果智能扫描的边缘识别不准确，可使用此接口传入修正后的坐标进行裁剪。

接口地址: https://www.clipimg.com/api/pic/scan/auto_crop
请求方式: POST
Content-Type: application/json
需要API Key: 是

请求参数 #

参数	类型	必选	说明
image_id	string	是	图片标识，从 `/pic/scan` 接口返回中获取
points	list	是	修正后的四个点坐标，二维数组。例如 `[[x1,y1], [x2,y2], [x3,y3], [x4,y4]]`
card_type	int	否	证件类型

响应格式 #

{
  "code": 0,
  "msg": "",
  "data": {
    "preview_url": "...",
    "download_url": "...",
    "preview_img_name": "...",
    "img_name": "..."
  }
}

3. 扫描裁剪A4排版接口 #

支持多张图片裁剪后自动排版到A4纸上（如身份证正反面排版）。

接口地址: https://www.clipimg.com/api/pic/scan/auto_crop_imgs
请求方式: POST
Content-Type: application/json
需要API Key: 是

请求参数 #

参数	类型	必选	说明
card_type	int	是	证件类型
list	list	是	图片列表。`card_type`为1,2,4,6时长度为2；为3时长度为1；为7时长度大于1（最多9张）
size_width	float	否	自定义宽度（仅card_type=7时生效）
size_height	float	否	自定义高度（仅card_type=7时生效）
shadow_remove	int	否	是否去阴影，默认1（开启）

list 元素结构

参数	类型	必选	说明
image_id	string	是	图片标识
points	list	是	四个点坐标

响应格式 #

card_type 为 1-6 时 (返回单张拼图):

{
  "code": 0,
  "msg": "",
  "data": {
    "preview_url": "...",
    "download_url": "...",
    "preview_img_name": "...",
    "img_name": "..."
  }
}

card_type 为 7 时 (返回多张图及PDF):

{
  "code": 0,
  "msg": "",
  "data": {
    "imgs": [
      {
        "preview_url": "...",
        "download_url": "...",
        "preview_img_name": "...",
        "img_name": "..."
      }
    ],
    "pdf": {
      "preview_url": "...",
      "download_url": "...",
      "preview_img_name": "...",
      "img_name": "..."
    }
  }
}

图片/PDF 访问接口 #

预览 (GET) #

图片预览: https://www.clipimg.com/api/pic/scan/preview/{preview_img_name}
PDF预览: https://www.clipimg.com/api/pic/scan/preview/{preview_img_name}（preview_img_name应以_pdf结尾）
说明: 免费接口，返回二进制流。

下载 (POST) #

图片下载: https://www.clipimg.com/api/pic/scan/download/{img_name}
PDF下载: https://www.clipimg.com/api/pic/scan/download/{img_name}（img_name应以_pdf结尾）
说明: 扣费操作 (20点/次)。需带 X-API-Key Header。

状态码说明 #

状态码	说明
0	成功
400	参数错误 / 文件数据为空 / Base64解码错误 / 无法解析图片数据 / 尺寸错误
402	您的API点数已用完，请及时充值
404	文件不存在
509	处理超时，请稍后再试

扣点规则说明 #

API点数消耗规则 #

/pic/scan 接口：调用不消耗点数。
/pic/scan/auto_crop 接口：调用不消耗点数。
/pic/scan/auto_crop_imgs 接口：调用不消耗点数。
下载接口：下载“无水印原图”或“PDF”扣 20 点/次。

结果保留说明 #

制作结果保留1小时，1小时后自动删除制作结果图片，请及时保存。重复下载同一张照片不会重复扣费。

各语言调用示例 #

以下示例演示调用 /pic/scan、/pic/scan/auto_crop 和 /pic/scan/auto_crop_imgs 接口。

1. 智能扫描 (/pic/scan) #

curl

curl -X POST "https://www.clipimg.com/api/pic/scan" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file": "BASE64_STRING",
    "card_type": 7
  }'

Python (requests)

import base64
import requests
import json

api_url = "https://www.clipimg.com/api/pic/scan"
api_key = "YOUR_API_KEY"

with open("doc.jpg", "rb") as f:
    img_b64 = base64.b64encode(f.read()).decode("utf-8")

payload = {
    "file": img_b64,
    "card_type": 7
}

headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}

response = requests.post(api_url, headers=headers, data=json.dumps(payload))
print(response.json())

Node.js (axios)

const axios = require('axios');
const fs = require('fs');

const apiKey = 'YOUR_API_KEY';
const imgB64 = fs.readFileSync('doc.jpg', { encoding: 'base64' });

axios.post('https://www.clipimg.com/api/pic/scan', {
    file: imgB64,
    card_type: 7
}, {
    headers: {
        'X-API-Key': apiKey,
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});

PHP (cURL)

<?php
$apiKey = "YOUR_API_KEY";
$imgB64 = base64_encode(file_get_contents("doc.jpg"));

$data = array(
    "file" => $imgB64,
    "card_type" => 7
);

$ch = curl_init("https://www.clipimg.com/api/pic/scan");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "X-API-Key: $apiKey",
    "Content-Type: application/json"
));
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Java (OkHttp)

import okhttp3.*;
import java.io.File;
import java.nio.file.Files;
import java.util.Base64;

public class ScanDemo {
    public static void main(String[] args) throws Exception {
        String apiKey = "YOUR_API_KEY";
        File file = new File("doc.jpg");
        String imgB64 = Base64.getEncoder().encodeToString(Files.readAllBytes(file.toPath()));

        String json = "{\"file\":\"" + imgB64 + "\", \"card_type\": 7}";

        OkHttpClient client = new OkHttpClient();
        RequestBody body = RequestBody.create(MediaType.parse("application/json"), json);
        Request request = new Request.Builder()
                .url("https://www.clipimg.com/api/pic/scan")
                .addHeader("X-API-Key", apiKey)
                .post(body)
                .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println(response.body().string());
        }
    }
}

2. 扫描裁剪 (/pic/scan/auto_crop) #

curl

curl -X POST "https://www.clipimg.com/api/pic/scan/auto_crop" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_id": "IMAGE_ID_FROM_SCAN",
    "points": [[100,100], [500,100], [500,500], [100,500]],
    "card_type": 7
  }'

Python (requests)

import requests
import json

api_url = "https://www.clipimg.com/api/pic/scan/auto_crop"
api_key = "YOUR_API_KEY"

payload = {
    "image_id": "IMAGE_ID_FROM_SCAN",
    "points": [[100,100], [500,100], [500,500], [100,500]],
    "card_type": 7
}

headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}

response = requests.post(api_url, headers=headers, data=json.dumps(payload))
print(response.json())

Node.js (axios)

const axios = require('axios');

const apiKey = 'YOUR_API_KEY';

axios.post('https://www.clipimg.com/api/pic/scan/auto_crop', {
    image_id: "IMAGE_ID_FROM_SCAN",
    points: [[100,100], [500,100], [500,500], [100,500]],
    card_type: 7
}, {
    headers: {
        'X-API-Key': apiKey,
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});

PHP (cURL)

<?php
$apiKey = "YOUR_API_KEY";

$data = array(
    "image_id" => "IMAGE_ID_FROM_SCAN",
    "points" => [[100,100], [500,100], [500,500], [100,500]],
    "card_type" => 7
);

$ch = curl_init("https://www.clipimg.com/api/pic/scan/auto_crop");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "X-API-Key: $apiKey",
    "Content-Type: application/json"
));
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Java (OkHttp)

import okhttp3.*;

public class ScanCropDemo {
    public static void main(String[] args) throws Exception {
        String apiKey = "YOUR_API_KEY";
        String json = "{\"image_id\":\"IMAGE_ID_FROM_SCAN\", \"points\": [[100,100], [500,100], [500,500], [100,500]], \"card_type\": 7}";

        OkHttpClient client = new OkHttpClient();
        RequestBody body = RequestBody.create(MediaType.parse("application/json"), json);
        Request request = new Request.Builder()
                .url("https://www.clipimg.com/api/pic/scan/auto_crop")
                .addHeader("X-API-Key", apiKey)
                .post(body)
                .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println(response.body().string());
        }
    }
}

3. 扫描裁剪A4排版 (/pic/scan/auto_crop_imgs) #

curl

curl -X POST "https://www.clipimg.com/api/pic/scan/auto_crop_imgs" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "card_type": 7,
    "list": [
        {
            "image_id": "IMAGE_ID_1",
            "points": [[100,100], [500,100], [500,500], [100,500]]
        },
        {
            "image_id": "IMAGE_ID_2",
            "points": [[100,100], [500,100], [500,500], [100,500]]
        }
    ]
  }'

Python (requests)

import requests
import json

api_url = "https://www.clipimg.com/api/pic/scan/auto_crop_imgs"
api_key = "YOUR_API_KEY"

payload = {
    "card_type": 7,
    "list": [
        {
            "image_id": "IMAGE_ID_1",
            "points": [[100,100], [500,100], [500,500], [100,500]]
        },
        {
            "image_id": "IMAGE_ID_2",
            "points": [[100,100], [500,100], [500,500], [100,500]]
        }
    ]
}

headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}

response = requests.post(api_url, headers=headers, data=json.dumps(payload))
print(response.json())

Node.js (axios)

const axios = require('axios');

const apiKey = 'YOUR_API_KEY';

axios.post('https://www.clipimg.com/api/pic/scan/auto_crop_imgs', {
    card_type: 7,
    list: [
        {
            image_id: "IMAGE_ID_1",
            points: [[100,100], [500,100], [500,500], [100,500]]
        },
        {
            image_id: "IMAGE_ID_2",
            points: [[100,100], [500,100], [500,500], [100,500]]
        }
    ]
}, {
    headers: {
        'X-API-Key': apiKey,
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});

PHP (cURL)

<?php
$apiKey = "YOUR_API_KEY";

$data = array(
    "card_type" => 7,
    "list" => array(
        array(
            "image_id" => "IMAGE_ID_1",
            "points" => [[100,100], [500,100], [500,500], [100,500]]
        ),
        array(
            "image_id" => "IMAGE_ID_2",
            "points" => [[100,100], [500,100], [500,500], [100,500]]
        )
    )
);

$ch = curl_init("https://www.clipimg.com/api/pic/scan/auto_crop_imgs");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "X-API-Key: $apiKey",
    "Content-Type: application/json"
));
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Java (OkHttp)

import okhttp3.*;

public class ScanLayoutDemo {
    public static void main(String[] args) throws Exception {
        String apiKey = "YOUR_API_KEY";
        String json = "{\"card_type\": 7, \"list\": [{\"image_id\":\"IMAGE_ID_1\", \"points\": [[100,100], [500,100], [500,500], [100,500]]}, {\"image_id\":\"IMAGE_ID_2\", \"points\": [[100,100], [500,100], [500,500], [100,500]]}]}";

        OkHttpClient client = new OkHttpClient();
        RequestBody body = RequestBody.create(MediaType.parse("application/json"), json);
        Request request = new Request.Builder()
                .url("https://www.clipimg.com/api/pic/scan/auto_crop_imgs")
                .addHeader("X-API-Key", apiKey)
                .post(body)
                .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println(response.body().string());
        }
    }
}

4. 下载无水印图片/PDF (/pic/scan/download) #

curl

curl -X POST "https://www.clipimg.com/api/pic/scan/download/{img_name}" \
  -H "X-API-Key: YOUR_API_KEY" \
  --output result.jpg

Python (requests)

import requests

api_key = "YOUR_API_KEY"
img_name = "{img_name}" # 替换为实际的 img_name
url = f"https://www.clipimg.com/api/pic/scan/download/{img_name}"

headers = {"X-API-Key": api_key}

# 注意：下载接口需要使用 POST 方法
with requests.post(url, headers=headers, stream=True) as r:
    if r.status_code == 200:
        with open("result.jpg", "wb") as f:
            for chunk in r.iter_content(chunk_size=8192):
                f.write(chunk)
        print("下载成功")
    else:
        print(f"下载失败: {r.status_code} - {r.text}")

Node.js (axios)

const axios = require('axios');
const fs = require('fs');

const API_KEY = 'YOUR_API_KEY';
const IMG_NAME = '{img_name}'; // 替换为实际的 img_name
const URL = `https://www.clipimg.com/api/pic/scan/download/${IMG_NAME}`;

async function downloadImage() {
    try {
        const response = await axios.post(URL, {}, {
            headers: { 'X-API-Key': API_KEY },
            responseType: 'arraybuffer'
        });
        fs.writeFileSync('result.jpg', response.data);
        console.log('下载成功');
    } catch (error) {
        console.error('下载失败:', error.response ? error.response.status : error.message);
    }
}

downloadImage();

PHP (cURL)

<?php
$apiKey = 'YOUR_API_KEY';
$imgName = '{img_name}'; // 替换为实际的 img_name
$url = "https://www.clipimg.com/api/pic/scan/download/$imgName";

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: $apiKey"],
    CURLOPT_RETURNTRANSFER => true,
]);

$data = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode == 200) {
    file_put_contents('result.jpg', $data);
    echo "下载成功\n";
} else {
    echo "下载失败: $httpCode\n";
}
?>

Java (OkHttp)

import java.nio.file.*;
import okhttp3.*;

public class DownloadScanDemo {
  public static void main(String[] args) throws Exception {
    String imgName = "{img_name}"; // 替换为实际的 img_name
    String url = "https://www.clipimg.com/api/pic/scan/download/" + imgName;
    String apiKey = "YOUR_API_KEY";

    OkHttpClient client = new OkHttpClient();
    RequestBody body = RequestBody.create(new byte[0], null);
    Request req = new Request.Builder()
        .url(url)
        .addHeader("X-API-Key", apiKey)
        .post(body)
        .build();

    try (Response resp = client.newCall(req).execute()) {
      if (resp.isSuccessful()) {
        Files.write(Paths.get("result.jpg"), resp.body().bytes());
        System.out.println("下载成功");
      } else {
        System.out.println("下载失败: " + resp.code());
      }
    }
  }
}

开发建议 #

图片压缩
建议在上传前对图片进行适当压缩（如 JPEG 质量 80%），将文件大小控制在 4MB 以内。过大的图片会导致上传耗时增加，甚至触发超时错误。
超时设置
由于图像处理涉及复杂的计算机视觉算法，建议将 HTTP 请求的超时时间设置为 30秒或更长，以确保在网络波动或服务器负载较高时能正常获取结果。
坐标系说明
接口返回或传入的坐标点 (points) 均基于原图分辨率。如果在前端展示时对图片进行了缩放，请务必进行相应的坐标转换。
错误重试
遇到 509 (处理超时) 或网络错误时，建议实施指数退避策略进行重试。遇到 400 或 402 错误时，请检查参数或账户余额，不要立即重试。

接口概述 #

使用场景 #

调用流程 #

限制说明 #

1. 智能扫描接口 #

请求参数 #

card_type 取值说明

响应格式 #

2. 扫描裁剪接口 (手动调整) #

请求参数 #

响应格式 #

3. 扫描裁剪A4排版接口 #

请求参数 #

list 元素结构

响应格式 #

图片/PDF 访问接口 #

预览 (GET) #

下载 (POST) #

状态码说明 #

扣点规则说明 #

API点数消耗规则 #

结果保留说明 #

各语言调用示例 #

1. 智能扫描 (/pic/scan) #

curl

Python (requests)

Node.js (axios)

PHP (cURL)

Java (OkHttp)

2. 扫描裁剪 (/pic/scan/auto_crop) #

curl

Python (requests)

Node.js (axios)

PHP (cURL)

Java (OkHttp)

3. 扫描裁剪A4排版 (/pic/scan/auto_crop_imgs) #

curl

Python (requests)

Node.js (axios)

PHP (cURL)

Java (OkHttp)

4. 下载无水印图片/PDF (/pic/scan/download) #

curl

Python (requests)

Node.js (axios)

PHP (cURL)

Java (OkHttp)

开发建议 #

相关推荐 #