文字识别API文档

最近更新时间:2020-07-17 17:04:17

人脸识别API文档

目录

调用方式

请求结构

服务地址 AI开放服务API的服务接入地址为:http://kcr.api.ksyun.com

通信协议

支持通过HTTP或HTTPS协议进行请求通信。为保证您的服务安全性,请使用HTTPS协议进行通信。

请求方式

支持GET方法发送请求,注意参数需要进行urlencode。

公共参数

公共请求header

参数名 必选 类型 说明
Authorization string 必要的请求验证信息
X-Amz-Date string 当前请求的时间戳,例如:20171129T114852Z
Host string kcr.api.ksyun.com

签名参数

Region:金山云机房信息,目前仅支持cn-beijing-6

Service:固定为kcr

返回结果

接口统一返回json格式数据,满足以下格式:

{
    "header":{
      "err_no":200,
      "err_msg":"success"
    },
    "cost":0.11,
    "request_id": "d679e27b-9f1b-44bf-b134-49a6d9f0adff",
    "request_time": 1234567890123,
    "body":{}
}

调用成功,err_no返回200,msg为success,否则返回对应错误码及错误信息。

cost为服务端耗时,单位秒。

每此请求会返回唯一的请求表示request_id,调用失败时提供request_id给金山云客服,方便定位问题。

request_time为每次请求时的服务器时间。

签名机制

详见金山云签名机制文档

通用文字识别接口

输入:

GET参数部分

参数名 必选 类型 说明
Action=RecognizeText string 固定此值
Version=2020-01-19 string API版本号,固定此值

POST请求示例

{
    "image_url":"xxxxx"
}

POST参数说明

参数 必选 类型 说明
image_url string 图片url (image_url和image_data二选一)
image_data string 图片内容的BASE64编码,不能超过1MB (image_url和image_data二选一)

接口返回:

{
    "header": {
        "err_no": 200,
        "err_msg": "success"
    },
    "request_id": "090e40f5-f90c-4921-b058-30f1a7e83c3d",
    "cost": 0.627,
    "words_result_num": 2,
    "words_result": [
        {
            "words": "XXXXXXXXXXXX",
            "location": {
               "top_left_x": 0.16029005560994847,
               "top_left_y": 0.2177239403843063,
               "top_right_y": 0.3159262808263047,
               "top_right_x": 0.20467229934001807,
               "bottom_right_y": 0.3159262808263047,
               "bottom_right_x": 0.20467229934001807,
               "bottom_left_x": 0.16029005560994847,
               "bottom_left_y": 0.2177239403843063
            }
        },
        {
            "words": "XXXXXXXXXXXX",
            "location": {
               "top_left_x": 0.16029005560994847,
               "top_left_y": 0.2177239403843063,
               "top_right_y": 0.3159262808263047,
               "top_right_x": 0.20467229934001807,
               "bottom_right_y": 0.3159262808263047,
               "bottom_right_x": 0.20467229934001807,
               "bottom_left_x": 0.16029005560994847,
               "bottom_left_y": 0.2177239403843063
            }
        }
    ]
}

接口输出字段解释:

字段 类型 是否必须 说明
header.err_no int 错误码,请求成功为200
header.err_msg string 错误信息,请求成功为success
request_id string 请求唯一标识
cost double 请求耗时,单位:秒
words_result_num int 识别结果数,表示words_result的元素个数
words_result object 识别结果
words_result.words string 识别结果字符串
words_result.location object 识别结果位置信息
words_result.location.top_left_x double 左上坐标的x值
words_result.location.top_left_y double 左上坐标的y值
words_result.location.bottom_right_x double 右下坐标的x值
words_result.location.bottom_right_y double 右下坐标的y值
words_result.location.top_right_x double 右上坐标的x值
words_result.location.top_right_y double 右上坐标的y值
words_result.location.bottom_left_x double 左下坐标的x值
words_result.location.bottom_left_y double 左下坐标的y值

注:为保证图片缩放后坐标点不变,此处返回坐标值均为相对图片长宽的百分比。

身份证识别接口

输入:

GET参数部分

参数名 必选 类型 说明
Action=RecognizeIdCard string 固定此值
Version=2020-02-15 string API版本号,固定此值

POST请求示例

{
    "card_side":"front",
    "image_url":"xxxxx"
}

POST参数说明

参数 必选 类型 说明
image_url string 图片url (image_url和image_data二选一)
image_data string 图片内容的BASE64编码,不能超过1MB (image_url和image_data二选一)
card_side string 身份证正反面,有人像面:front,无人像面:back

接口返回:

{
    "header": {
        "err_no": 200,
        "err_msg": "success"
    },
    "request_id": "197fce95-52bb-4b24-a82a-8765c07ab71b",
    "cost": 1.787,
    "result": {
        "name": "XX",
        "gender": "X",
        "nationality": "X",
        "birth": "XXXXXXX",
        "address": "XXXXXXXXXXX",
        "id_card_num": "XXXXXXXXXXXX"
    }
}

接口输出字段解释:

字段 类型 是否必须 说明
header.err_no int 错误码,请求成功为200
header.err_msg string 错误信息,请求成功为success
request_id string 请求唯一标识
cost double 请求耗时,单位:秒
result object 识别结果
result.name string 姓名
result.gender string 性别
result.nationality string 民族
result.birth string 出生日期
result.address string 住址
result.id_card_num string 身份证号码
result.issue string 身份证签发机构
result.start_time string 身份证有效期起始时间
result.end_time string 身份证有效期结束时间

增值税发票识别接口

输入:

GET参数部分

参数名 必选 类型 说明
Action=RecognizeInvoice string 固定此值
Version=2020-03-06 string API版本号,固定此值

POST请求示例

{
    "tpye":"normal",
    "image_url":"xxxxx"
}

POST参数说明

参数 必选 类型 说明
image_url string 图片url (image_url和image_data二选一)
image_data string 图片内容的BASE64编码,不能超过1MB (image_url和image_data二选一)
type string normal:普通增值税发票,roll:卷票,如不填默认 normal

接口返回:

{
    "header": {
        "err_no": 200,
        "err_msg": "success"
    },
    "request_id": "197fce95-52bb-4b24-a82a-8765c07ab71b",
    "cost": 1.787,
    "result": {
        "invoice_type": "专用发票",
        "invoice_type_org": "北京增值税专用发票",
        "invoice_code": "1100131140",
        "invoice_num": "04798325",
        "check_code": "",
        "invoice_date": "2013年10月28日",
        "purchaser_name": "北京XX制冷设备安装有限公司",
        "purchaser_register_num": "11010505137466X",
        "purchaser_address": "北京市朝阳区朝阳北路11号楼5层2单元507010-59396803",
        "purchaser_bank": "中国农业银行股份有限公司北京常营支行1104150104000008",
        "password": "",
        "commodity_name": [
            {
                "row": 1,
                "word": "XX空调"
            },
            {
                "row": 2,
                "word": "XX空调"
            },
            {
                "row": 3,
                "word": "XX空调"
            },
            {
                "row": 4,
                "word": "XX空调"
            },
            {
                "row": 5,
                "word": "XX安调"
            },
            {
                "row": 6,
                "word": "XX空调"
            }
        ],
        "commodity_type": [
            {
                "row": 1,
                "word": "KFR-32GW"
            },
            {
                "row": 2,
                "word": "KFR-26T2W"
            },
            {
                "row": 3,
                "word": "EFR-71T2W"
            },
            {
                "row": 4,
                "word": "KFS-120T2W"
            },
            {
                "row": 5,
                "word": "KFR-1250W"
            },
            {
                "row": 6,
                "word": "KFR-23GW"
            }
        ],
        "commodity_unit": [
            {
                "row": 1,
                "word": "台"
            },
            {
                "row": 2,
                "word": "台"
            },
            {
                "row": 3,
                "word": "台"
            },
            {
                "row": 4,
                "word": "台"
            },
            {
                "row": 5,
                "word": "台"
            },
            {
                "row": 6,
                "word": "台"
            }
        ],
        "commodity_num": [
            {
                "row": 1,
                "word": "3"
            },
            {
                "row": 2,
                "word": "3"
            },
            {
                "row": 3,
                "word": "3"
            },
            {
                "row": 4,
                "word": "4"
            },
            {
                "row": 5,
                "word": "6"
            },
            {
                "row": 6,
                "word": "8"
            }
        ],
        "commodity_price": [
            {
                "row": 1,
                "word": "1923.0769231"
            },
            {
                "row": 2,
                "word": "1906.8375068"
            },
            {
                "row": 3,
                "word": "4256.4192564"
            },
            {
                "row": 4,
                "word": "5883.7606838"
            },
            {
                "row": 5,
                "word": "6410.2564103"
            },
            {
                "row": 6,
                "word": "1623.9316239"
            }
        ],
        "commodity_amount": [
            {
                "row": 1,
                "word": "5769.23"
            },
            {
                "row": 2,
                "word": "5720.51"
            },
            {
                "row": 3,
                "word": "12769.23"
            },
            {
                "row": 4,
                "word": "23535.04"
            },
            {
                "row": 5,
                "word": "38461.54"
            },
            {
                "row": 6,
                "word": "12991.45"
            }
        ],
        "commodity_tax_rate": [
            {
                "row": 1,
                "word": "17%"
            },
            {
                "row": 2,
                "word": "17%"
            },
            {
                "row": 3,
                "word": "17%"
            },
            {
                "row": 4,
                "word": "17%"
            },
            {
                "row": 5,
                "word": "17%"
            },
            {
                "row": 6,
                "word": "17%"
            }
        ],
        "commodity_tax": [
            {
                "row": 1,
                "word": "980.77"
            },
            {
                "row": 2,
                "word": "972.49"
            },
            {
                "row": 3,
                "word": "2170.70"
            },
            {
                "row": 4,
                "word": "4000.93"
            },
            {
                "row": 5,
                "word": "6538.46"
            },
            {
                "row": 6,
                "word": "2208.55"
            }
        ],
        "seller_name": "北京世纪商贸有限公司",
        "seller_register_num": "110111571253896",
        "seller_address": "北京市房山区城关街道顾八路1区1号-HN12187741358",
        "seller_bank": "中信银行金国际支行7116010195700004917",
        "total_amount": "99247.00",
        "total_tax": "16872.00",
        "amount_in_words": "壹拾壹万陆仟壹佰壹拾玖圆整",
        "amount_in_figures": "116119.00",
        "payee": "G娇",
        "checker": "",
        "note_drawer": ""
    }
}

接口输出字段解释:

字段 类型 是否必须 说明
header.err_no int 错误码,请求成功为200
header.err_msg string 错误信息,请求成功为success
request_id string 请求唯一标识
cost double 请求耗时,单位:秒
result object 识别结果
result.invoice_type String 发票种类
result.invoice_type_org String 发票名称
result.invoice_code String 发票代码
result.invoice_num String 发票号码
result.check_code String 校验码
result.invoice_date String 开票日期
result.purchaser_name String 购方名称
result.purchaser_register_num String 购方纳税人识别号
result.purchaser_address String 购方地址及电话
result.purchaser_bank String 购方开户行及账号
result.password String 密码区
result.commodity_name Object 货物名称
result.commodity_type Object 规格型号
result.commodity_unit Object 单位
result.commodity_num Object 数量
result.commodity_price Object 单价
result.commodity_amount Object 金额
result.commodity_tax_rate Object 税率
result.commodity_tax Object 税额
result.seller_name String 销售方名称
result.seller_register_num String 销售方纳税人识别号
result.seller_address String 销售方地址及电话
result.seller_bank String 销售方开户行及账号
result.total_amount String 合计金额
result.total_tax String 合计税额
result.amount_in_words String 价税合计(大写)
result.amount_in_figures String 价税合计(小写)
result.payee String 收款人
result.checker String 复核
result.note_drawer String 开票人
result.remarks String 备注
其中 Item 对象为 字段 类型 是否必须 说明
row Long 行号
word String 内容

银行卡识别接口

输入:

GET参数部分

参数名 必选 类型 说明
Action=RecognizeBankCard string 固定此值
Version=2020-03-06 string API版本号,固定此值

POST请求示例

{
    "image_url":"xxxxx"
}

POST参数说明

参数 必选 类型 说明
image_url string 图片url (image_url和image_data二选一)
image_data string 图片内容的BASE64编码,不能超过1MB (image_url和image_data二选一)

接口返回:

{
    "header": {
        "err_no": 200,
        "err_msg": "success"
    },
    "request_id": "197fce95-52bb-4b24-a82a-8765c07ab71b",
    "cost": 1.787,
    "result": {
        "bank_card_number": "6217 0001 3000 8255 555",
        "valid_date": "11/2023",
        "bank_card_type": 1,
        "bank_name": "建设银行"
    }
}

接口输出字段解释:

字段 类型 是否必须 说明
header.err_no int 错误码,请求成功为200
header.err_msg string 错误信息,请求成功为success
request_id string 请求唯一标识
cost double 请求耗时,单位:秒
result object 识别结果
result.bank_card_number String 银行卡卡号
result.valid_date String 有效期
result.bank_card_type Integer 银行卡类型,0:不能识别; 1:借记卡; 2:信用卡
result.bank_name String 银行名称

错误码说明

调用接口失败时,返回的HTTP消息体将中包含具体的错误信息,下表为错误码的具体说明,找不到错误原因时,可以联系我们,并提供Response中的RequestId/request_id,以便尽快解决问题。

签名错误码

错误代码(Code) 错误消息(Message) 状态码 说明
IncompleteSignature Date must be in ISO-8601 'basic format'. Got '%s'. See http://en.wikipedia.org/wiki/ISO_8601. 400 Date必须符合ISO_8601基本格式,参考:http://en.wikipedia.org/wiki/ISO_8601
IncompleteSignature KSC query-string parameters must include %s. Re-examine the query-string parameters. 400 查询条件中缺少签署信息,查询条件中必须包含”X-Amz-Algorithm“、”X-Amz-Credential“、”X-Amz-SignedHeaders“、”X-Amz-Date“信息
IncompleteSignature Unsupported ksc 'algorithm': %s. 400 只支持如下签名算法:AWS4-HMAC-SHA256
IncompleteSignature Authorization header requires 'Credential' parameter. Authorization=%s. 400 请求Authorization header中需要包含“Credential”参数
IncompleteSignature Credential must have exactly 5 slash-delimited elements, e.g. accesskeyid/date/region/service/aws4_request, got: %s. 400 请求Authorization header中中“Credential”至少包含5项以斜杠分隔的元素,如:keyid/date/region/service/aws4_request
IncompleteSignature Authorization header format error. 400 请求Authorization header的格式错误
IncompleteSignature Authorization header requires existence of either a 'X-Amz-Date' or a 'Date' header, Authorization=%s 400 请求中缺少“X-Amz-Date”或者“Date” header信息
IncompleteSignature Authorization header requires 'Signature' parameter. Authorization=%s 400 请求Authorization header中缺少“Signature”信息
IncompleteSignature Authorization header requires 'SignedHeaders' parameter. Authorization=%s 400 请求Authorization header中缺少“SignedHeaders”信息
MissingAuthenticationToken Request is missing 'Host' header. 403 请求header中缺少Host
MissingAuthenticationToken Request is missing Authentication Token. 403 请求header中缺少认证token
MissingAuthenticationToken %s not in Http Header. 403 %s不在Http header中
SignatureDoesNotMatch Host' must be a 'SignedHeader' in the Authorization. 403 请求的SignedHeader中必须包含Host
SignatureDoesNotMatch Credential should be scoped with a valid terminator: 'aws4_request', not: %s. 403 请求Authorization header中的“Credential”末尾必须是“aws4_request”
SignatureDoesNotMatch Credential should be scoped to a valid region, not:%s. 403 请求Authorization header中的“Credential”中的Region信息无效
SignatureDoesNotMatch Credential should be scoped to correct service: %s. 403 请求Authorization header中的“Credential”中的Service信息无效
SignatureDoesNotMatch The request signature we calculated does not match the signature you provided. 403 请求中提供的签名与实际计算结果不匹配
SignatureDoesNotMatch Signature expired:%s. 403 签名已过期
SignatureDoesNotMatch Date in Credential scope does not match YYYYMMDD from ISO-8601 version of date from HTTP. 403 请求Authorization header中的“Credential”中的Date应该是ISO8601基本格式,形如”YYYYMMDD“
InvalidClientTokenId The security token included in the request is invalid. 403 请求中提供的AccessKeyId无效

业务层级错误码

err_msg err_no 说明
未开通相应的服务 411 账号未开通服务权限
请求太频繁 510 QPS达到限制

其他说明

图片大小限制为5M,长宽像素不大于5000,图片下载时间限制为2.5s内,如果下载时间超过2.5s返回下载超时;

图片像素建议不小于256*256,太小可能会影响识别效果;

图片检测接口响应时间依赖图片的下载时间,请保证所检测图片所在的存储服务的稳定,图片建议使用金山云对象存储或者cdn做缓存等;

接口regionId仅支持cn-beijing-6;

金山云,开启您的云计算之旅

免费注册