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

可立图 ClipImg 智能扫描 API 服务

接口概述 #

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

使用场景 #

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

调用流程 #

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

在线演示: 试一试
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 取值说明

值	说明	适用场景
0	自定义尺寸	已知目标输出尺寸，但不属于预置证件类型时使用，例如自定义卡片、小票、小尺寸单页材料
1	身份证	中国居民身份证正反面扫描、A4排版
2	户口本	户口本首页、常住人口登记卡等双页材料扫描与排版
3	护照	护照资料页等单页证件扫描与排版
4	驾驶证	驾驶证正副页扫描、A4排版
5	行驶证	行驶证主页/副页扫描、A4排版
6	银行卡	银行卡、储蓄卡、信用卡等标准卡面扫描
7	文档 (默认)	合同、发票、试卷、表格、纸质材料、多页文档扫描
8	标准横版卡证扩展类型	社保卡、工作证、会员卡、出入证等尺寸和排版方式接近银行卡/身份证卡面的单页横版卡证

说明：

card_type=8 在当前实现里会复用“标准横版卡证”的裁剪与排版逻辑，输出尺寸与银行卡/身份证卡面类一致，适合未单独建模但版式接近标准卡面的扩展卡证场景。
如果输入内容本质上是普通纸质材料，而不是卡面类证件，建议优先使用 card_type=7。

默认 render_options 模板

当调用方未传 render_options 时，服务端会按 card_type 自动应用默认模板；若只传了部分字段，则仅覆盖传入字段，其余字段仍沿用该默认模板。

card_type	说明	默认 mode	默认 rotate_angle	默认 shadow_remove
0	自定义尺寸	`enhance_sharpen`	`0`	`0`
1	身份证	`enhance_sharpen`	`0`	`0`
2	户口本	`enhance_sharpen`	`0`	`0`
3	护照	`enhance_sharpen`	`0`	`0`
4	驾驶证	`enhance_sharpen`	`0`	`0`
5	行驶证	`enhance_sharpen`	`0`	`0`
6	银行卡	`enhance_sharpen`	`0`	`0`
7	文档	`origin`	`0`	`1`
8	标准横版卡证扩展类型	`enhance_sharpen`	`0`	`0`

响应格式 #

{
  "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",
            "render_options": {
                "mode": "origin",
                "rotate_angle": 0,
                "shadow_remove": 1
            }
        },
        "capabilities": {
            "render_modes": [
                "origin",
                "enhance_sharpen",
                "black_white",
                "brighten",
                "grayscale",
                "save_ink"
            ],
            "rotate_angles": [0, 90, 180, 270]
    }
  }
}

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	否	证件类型
render_options	object	否	裁剪后渲染参数，控制旋转、去阴影和效果模式

render_options 结构

参数	类型	必选	说明
mode	string	否	效果模式，支持 `origin`(原图)、`enhance_sharpen`(增强并锐化，推荐用于屏幕存档)、`black_white`(增强黑白，背景极净)、`brighten`(智能增亮，保护色相)、`grayscale`(灰度去色)、`save_ink`(极简省墨，黑斑线框化防洇墨适合打印)
rotate_angle	int	否	旋转角度，仅支持 `0/90/180/270`，默认 `0`
shadow_remove	int	否	是否去除环境阴影，`0/1`，默认 `0`。（注：黑白与省墨模式本身已自带强力去阴影效果，会忽略此参数）

说明：

render_options 未传时，服务端会自动套用当前 card_type 对应的默认模板。
仅传部分字段时，未传字段继续沿用该 card_type 默认模板。
同一 image_id 在不同 render_options 下会生成不同结果文件名，请始终使用接口返回的 preview_img_name / img_name。

响应格式 #

{
  "code": 0,
  "msg": "",
  "data": {
    "preview_url": "...",
    "download_url": "...",
    "preview_img_name": "...",
        "img_name": "...",
        "render_options": {
            "mode": "enhance_sharpen",
            "rotate_angle": 90,
            "shadow_remove": 1
        },
        "capabilities": {
            "render_modes": [
                "origin",
                "enhance_sharpen",
                "black_white",
                "brighten",
                "grayscale",
                "save_ink"
            ],
            "rotate_angles": [0, 90, 180, 270]
        }
  }
}

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（开启），建议迁移到 `render_options.shadow_remove`
render_options	object	否	顶层默认渲染参数，作用于所有页面，支持被 `list[i].render_options` 覆盖

list 元素结构

参数	类型	必选	说明
image_id	string	是	图片标识
points	list	是	四个点坐标
render_options	object	否	单页渲染参数，优先级高于顶层 `render_options`

render_options 继承规则

list[i].render_options 优先。
未传单页参数时，继承顶层 render_options。
新旧参数都未传时，保持旧逻辑。

兼容规则

若仍传旧字段 shadow_remove，服务端会内部归一到 render_options.shadow_remove。
顶层和单页同时传值时，以单页 render_options 为准。
顶层和单页都未传 render_options 时，服务端会按当前 card_type 套用默认模板。

响应格式 #

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	文件不存在 (Image ID 失效或已过期)
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,
        "render_options": {
            "mode": "enhance_sharpen",
            "rotate_angle": 90,
            "shadow_remove": 1
        }
  }'

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,
    "render_options": {
        "mode": "enhance_sharpen",
        "rotate_angle": 90,
        "shadow_remove": 1
    }
}

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,
    render_options: {
        mode: 'enhance_sharpen',
        rotate_angle: 90,
        shadow_remove: 1
    }
}, {
    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,
    "render_options" => array(
        "mode" => "enhance_sharpen",
        "rotate_angle" => 90,
        "shadow_remove" => 1
    )
);

$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, \"render_options\": {\"mode\": \"enhance_sharpen\", \"rotate_angle\": 90, \"shadow_remove\": 1}}";

        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,
        "render_options": {
            "mode": "grayscale",
            "rotate_angle": 0,
            "shadow_remove": 1
        },
    "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]],
                        "render_options": {
                            "rotate_angle": 180,
                            "mode": "black_white"
                        }
        }
    ]
  }'

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,
    "render_options": {
        "mode": "grayscale",
        "rotate_angle": 0,
        "shadow_remove": 1
    },
    "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]],
            "render_options": {
                "rotate_angle": 180,
                "mode": "black_white"
            }
        }
    ]
}

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,
    render_options: {
        mode: 'grayscale',
        rotate_angle: 0,
        shadow_remove: 1
    },
    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]],
            render_options: {
                rotate_angle: 180,
                mode: 'black_white'
            }
        }
    ]
}, {
    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,
    "render_options" => array(
        "mode" => "grayscale",
        "rotate_angle" => 0,
        "shadow_remove" => 1
    ),
    "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]],
            "render_options" => array(
                "rotate_angle" => 180,
                "mode" => "black_white"
            )
        )
    )
);

$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, \"render_options\": {\"mode\": \"grayscale\", \"rotate_angle\": 0, \"shadow_remove\": 1}, \"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]], \"render_options\": {\"rotate_angle\": 180, \"mode\": \"black_white\"}}]}";

        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());
      }
    }
  }
}

开发建议 & 最佳实践 #

1. 效果模式 `mode` 的选取指南 #

业务资料建档 (首选)：建议传 mode: "enhance_sharpen"。该模式会结合亮度补偿与细节锐化策略，在尽量保持原始版式和内容信息的前提下提升文字边缘清晰度，适合建档留存与后续OCR识别。
纯屏幕查阅 (最干净)：传 mode: "black_white"，能彻底杀掉发灰底纹、麻点和水印。
需要用物理打印机复印输出：极其推荐传 mode: "save_ink"。此模式会对印章和人像等“大块黑色”执行极限剥离、强制线框化。能防止墨水堆积导致打印纸打皱或污墨。
想要自己做滤镜叠加：传 mode: "origin", shadow_remove: 1，我们将只帮您去除四角环境阴影斑块，不破坏任何图片质感特征。

2. 图片压缩 #

建议在上传前对图片进行适当压缩（如 JPEG 质量 80%），分辨率较小边控制在1500像素即可，过大的图片会导致上传及识别耗时剧增。

3. 超时设置 #

由于图像处理涉及复杂的计算机视觉算法，建议将 HTTP 请求的超时时间设置为 30秒或更长，以确保在网络波动或服务器负载较高时能正常获取结果。

4. 坐标系说明 #

接口返回或传入的坐标点 (points) 均基于原图分辨率。如果在前端展示时对图片进行了缩放，请务必进行相应的坐标转换。

5. 错误重试 #

遇到 509 (处理超时) 或网络错误时，建议实施指数退避策略进行重试。遇到 400 或 402 错误时，请检查参数或账户余额，不要立即重试。

接口概述 #

使用场景 #

调用流程 #

限制说明 #

1. 智能扫描接口 #

请求参数 #

card_type 取值说明

默认 render_options 模板

响应格式 #

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

请求参数 #

render_options 结构

响应格式 #

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

请求参数 #

list 元素结构

render_options 继承规则

兼容规则

响应格式 #

图片/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)

开发建议 & 最佳实践 #

1. 效果模式 mode 的选取指南 #

2. 图片压缩 #

3. 超时设置 #

4. 坐标系说明 #

5. 错误重试 #

相关推荐 #

1. 效果模式 `mode` 的选取指南 #