API文档

更新时间：2025-04-28

在线调试

您可以在示例代码中心中调试该接口，可进行签名验证、查看在线调用的请求内容和返回结果、示例代码的自动生成。

请求说明

请求示例

HTTP 方法：POST

请求URL： https://aip.baidubce.com/rest/2.0/solution/v1/iocr/recognise

URL参数：

参数	值
access_token	通过API Key和Secret Key获取的access_token,参考“Access Token获取”

Header如下：

参数	值
Content-Type	application/x-www-form-urlencoded

Body中放置请求参数，参数详情如下：

请求参数

参数	是否必选	类型	可选值范围	说明
image	和 url/pdf_file 三选一	string	-	图像数据，base64编码后进行urlencode，需去掉编码头（data:image/jpeg;base64, ）要求base64编码和urlencode后大小不超过4M，最短边至少15px，最长边最大4096px，支持jpg/jpeg/png/bmp格式
url	和 image/pdf_file 三选一	string	-	图片完整URL，URL长度不超过1024字节，URL对应的图片base64编码后大小不超过4M，最短边至少15px，最长边最大4096px，支持jpg/jpeg/png/bmp格式，当image字段存在时url字段失效请注意关闭URL防盗链
pdf_file	和 image/url 三选一	string	-	PDF文件，base64编码后进行urlencode，需去掉编码头（data:application/pdf;base64, ）要求base64编码和urlencode后大小不超过4M 注：目前仅支持单页PDF识别，如上传的为多页PDF，仅识别第一页
templateSign	和 classifierId 二选一	string	-	模板 ID，自定义模板或预置模板的唯一标示，可用于调用指定的识别模板进行结构化识别，可在「模板管理」页查看并复制使用
classifierId	和 templateSign 二选一	string	-	分类器Id，分类器的唯一标示，可用于调用指定的分类器对传入的图片进行自动分类及识别与 templateSign 至少存在一个，如同时存在，则优先级 templateSign > classfierId

请求代码示例

提示一：使用示例代码前，请记得替换其中的示例Token、图片地址或Base64信息。

提示二：部分语言依赖的类或库，请在代码注释中查看下载地址。

            Bash
        
            Python
        
            JAVA
        
            C++
        
            PHP
        
            C#
        
            Objective-C
        

            # 请求模板id
curl -i -k 'https://aip.baidubce.com/rest/2.0/solution/v1/iocr/recognise?access_token=【调用鉴权接口获取的token】' --data 'templateSign=xxx&image=【图片Base64编码，需UrlEncode】' -H 'Content-Type:application/x-www-form-urlencoded'
# 请求分类器id
curl -i -k 'https://aip.baidubce.com/rest/2.0/solution/v1/iocr/recognise?access_token=【调用鉴权接口获取的token】' --data 'classifierId=xxx&image=【图片Base64编码，需UrlEncode】' -H 'Content-Type:application/x-www-form-urlencoded'
        

            # -*- coding:UTF-8 -*-
# -*- encoding: utf-8 -*-
import base64
import requests
import sys

if sys.version_info.major == 2:
    from urllib import quote
else:
    from urllib.parse import quote



headers = {
        'Content-Type': "application/x-www-form-urlencoded",
        'charset': "utf-8"
    }
if __name__ == '__main__':
    recognise_api_url = "https://aip.baidubce.com/rest/2.0/solution/v1/iocr/recognise"
    access_token = "your_access_token"
    templateSign = "your_template_sign"

    classifierId = "your_classifier_id"
    # 测试数据路径
    image_path = "your_image_path"
    try:
        with open(image_path, 'rb') as f:
            image_data = f.read()
        if sys.version_info.major == 2:
            image_b64 = base64.b64encode(image_data).replace("\r", "")
        else:
            image_b64 = base64.b64encode(image_data).decode().replace("\r", "")

        # 请求模板的bodys
        recognise_bodys = "access_token=" + access_token + "&templateSign=" + templateSign + \
                "&image=" + quote(image_b64.encode("utf8"))
        # 请求分类器的bodys
        classifier_bodys = "access_token=" + access_token + "&classifierId=" + classifierId + \
                "&image=" + quote(image_b64.encode("utf8"))

        # 请求模板识别
        response = requests.post(recognise_api_url, data=recognise_bodys, headers=headers)
        # 请求分类器识别
        # response = requests.post(recognise_api_url, data=classifier_bodys, headers=headers)

        print(response.text)
    except Exception as e:
        print (e)
        

            package com.baidu.ocr;

import com.baidu.ai.aip.utils.Base64Util;
import com.baidu.ai.aip.utils.FileUtil;
import com.baidu.ai.aip.utils.HttpUtil;


public class App 
{
    public static void main(String[] args) throws Exception
    {
        /**
         * 重要提示代码中所需工具类
         * FileUtil,Base64Util,HttpUtil,GsonUtils请从
         * https://ai.baidu.com/file/658A35ABAB2D404FBF903F64D47C1F72
         * https://ai.baidu.com/file/C8D81F3301E24D2892968F09AE1AD6E2
         * https://ai.baidu.com/file/544D677F5D4E4F17B4122FBD60DB82B3
         * https://ai.baidu.com/file/470B3ACCA3FE43788B5A963BF0B625F3
         * 下载
         */
        // iocr识别apiUrl
        String recogniseUrl = "https://aip.baidubce.com/rest/2.0/solution/v1/iocr/recognise";


        String filePath = "path\to\your\image.jpg";
        try {
                byte[] imgData = FileUtil.readFileByBytes(filePath);
                String imgStr = Base64Util.encode(imgData);
                // 请求模板参数
                String recogniseParams = "templateSign=your_template_sign&image=" + URLEncoder.encode(imgStr, "UTF-8");
                // 请求分类器参数
                String classifierParams = "classifierId=your_classfier_id&image=" + URLEncoder.encode(imgStr, "UTF-8");
                
                
                String accessToken = "your_access_token";
                // 请求模板识别
                String result = HttpUtil.post(recogniseUrl, accessToken, recogniseParams);
                // 请求分类器识别
                // String result = HttpUtil.post(recogniseUrl, accessToken, classifierParams);
                
                System.out.println(result);
        } catch (Exception e) {
                e.printStackTrace();
        }
    }
}
        

            #include <iostream>
#include "curl_install/include/curl/curl.h"
#include <fstream>
#include "Base64.h"
#include <cctype>
#include <iomanip>
#include <sstream>
#include <string>

using namespace std;
// libcurl库下载链接：https://curl.haxx.se/download.html
// 通用iocr的接口url
static string ocr_result;
/**
 * curl发送http请求调用的回调函数，回调函数中对返回的json格式的body进行了解析，解析结果储存在全局的静态变量当中
 * @param 参数定义见libcurl文档
 * @return 返回值定义见libcurl文档
 */
static size_t callback(void *ptr, size_t size, size_t nmemb, void *stream) {
    // 获取到的body存放在ptr中，先将其转换为string格式
    ocr_result = string((char *) ptr, size * nmemb);
    return size * nmemb;
}

string url_encode(const std::string &value) {
    ostringstream escaped;
    escaped.fill('0');
    escaped << hex;
    for (std::string::const_iterator i = value.begin(), n = value.end(); i != n; ++i) {
        std::string::value_type c = (*i);
        // Keep alphanumeric and other accepted characters intact
        if (isalnum(c) || c == '-' || c == '_' || c == '.' || c == '~') {
            escaped << c;
            continue;
        }
        // Any other characters are percent-encoded
        escaped << uppercase;
        escaped << '%' << setw(2) << int((unsigned char) c);
        escaped << nouppercase;
    }

    return escaped.str();
}
// base64.h下载地址
// https://bj.bcebos.com/v1/iocr-movie/Base64.h
int iocr_regenize(const std::string &image_base64, const std::string &access_token, 
    const std::string &templateSign, const std::int classifierId) {
    // iocr识别apiUrl
    const static string recognise_api_url = "https://aip.baidubce.com/rest/2.0/solution/v1/iocr/recognise";
    // 请求模板的参数
    std::string recognise_params = "access_token=" + access_token + "&templateSign=" + templateSign + "&image=" + image_base64;
    // 请求分类器的参数
    std::string classifier_params = "access_token=" + access_token 
        + "&classifierId=" + std::to_string(classifierId) 
        + "&image=" + image_base64;
    struct curl_slist * headers = NULL;
    headers = curl_slist_append(headers, "Content-Type:application/x-www-form-urlencoded");
    headers = curl_slist_append(headers, "charset:utf-8");
    CURL *curl;
    CURLcode result_code;
    int is_success;
    curl = curl_easy_init();
    if (curl) {
        // 使用libcurl post数据：设定待post的url等
        curl_easy_setopt(curl, CURLOPT_URL, recognise_api_url.c_str());
        curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
        curl_easy_setopt(curl, CURLOPT_POST, 1);
        curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, false);
        curl_easy_setopt(curl,CURLOPT_WRITEFUNCTION,callback);
        // 请求模板
        curl_easy_setopt(curl, CURLOPT_POSTFIELDS, recognise_params.c_str());
        curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, recognise_params.size());
        // 请求分类器
        // curl_easy_setopt(curl, CURLOPT_POSTFIELDS, classifier_params.c_str());
        // curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, classifier_params.size());
        
        result_code = curl_easy_perform(curl);
        // http post不成功时错误处理
        if (result_code != CURLE_OK) {
            fprintf(stderr, "curl_easy_perform() failed: %s\n",
                    curl_easy_strerror(result_code));
            is_success = 1;
            return is_success;
        }
        curl_easy_cleanup(curl);
        curl_slist_free_all(headers);
        // 控制台输出识别结果
        cout << ocr_result << endl;
        is_success = 0;
    } else {
        fprintf(stderr, "curl_easy_init() failed.");
        is_success = 1;
    }
    return is_success;
}

std::string get_image_b64(const std::string &image_path) {
    ifstream f;
    f.open(image_path, ios::in | ios::binary);
    // 定位指针到文件末尾
    f.seekg(0, ios::end);
    int size = f.tellg();
    // 指针重新回到文件头部
    f.seekg(0, ios::beg);
    char* buffer = (char*)malloc(sizeof(char)*size);
    f.read(buffer,size);
    f.close();
    // base64编码
    std::string image_b64 = base64_encode(buffer, size);
    return image_b64;
}

int main() {
    std::string access_token = "your_access_token";
    std::string image_path = "your_file_path";
    std::string templateSign = "your_templateSign";
    std::int classifierId = "your_classifier_id";
    // 获取本地图片的base64
    std::string image_b64 = get_image_b64(image_path);
    // urlcode编码
    image_b64 = url_encode(image_b64);
    // 对api发送post请求
    iocr_regenize(image_b64, access_token, templateSign, classifierId);
    return 0;
}
        

            <?php
/**
 * 发起http post请求(REST API), 并获取REST请求的结果
 * @param string $url
 * @param string $param
 * @return - http response body if succeeds, else false.
 */
function request_post($url = '', $params = '')
{
    if (empty($url) || empty($params)) {
        return false;
    }
    $headers = array("Content-Type" => "application/x-www-form-urlencoded", "charset" => "utf-8");
    // 初始化curl
    $curl = curl_init();
    curl_setopt($curl, CURLOPT_URL, $url);
    curl_setopt($curl, CURLOPT_HEADER, 0);
    // 要求结果为字符串且输出到屏幕上
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
    // post提交方式
    //curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'POST');
    curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($curl, CURLOPT_POST, 1);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $params);
    // 运行curl
    $data = curl_exec($curl);
    curl_close($curl);

    return $data;
}

function get_image_b64($image_path = '')
{
    $image_b64 = '';
    if(file_exists($image_path)) {
        $image_data = file_get_contents($image_path);
        print("file exists\n");
        $image_b64_tmp = base64_encode($image_data);
        $image_b64 = urlencode($image_b64_tmp);
        //print($image_b64);
    } else {
        print("file doesn't exists\n");
    }
    return $image_b64;
}
// iocr识别api_url
$recognise_api_url = "https://aip.baidubce.com/rest/2.0/solution/v1/iocr/recognise";


$access_token = "your_access_token";
$templateSign = "your_templateSign";

$classifierId = "your_classifier_id";
$image_path = "your_file_path";
$image_b64 = get_image_b64($image_path);
// iocr识别bodys
$recognise_bodys = "access_token=". $access_token. "&templateSign=". $templateSign. "&image=". $image_b64;
# 分类器请求的bodys
$classifier_bodys = "access_token=". $access_token. "&classifierId=". $classifierId. "&image=". $image_b64;

# 请求分类器识别
# $response = request_post($recognise_api_url, $classifier_bodys);
# 请求模板识别
$response = request_post($recognise_api_url, $recognise_bodys);
var_dump($response)
?>
        

            using System;
using System.Net;
using System.IO;
using System.Text;
using System.Web;

namespace iocr_api_demo
{
    class IocrApiDemo
    {
        static void Main(string[] args)
        {
            PostHttp();
        }
        public static void PostHttp(){
            // fileUtils.cs 类下载地址
            // https://bj.bcebos.com/v1/iocr-movie/FileUtils.cs
            // iocr识别api_url
            string recognise_api_url = "https://aip.baidubce.com/rest/2.0/solution/v1/iocr/recognise";
            string access_token = "your_access_token";
            string templateSign = "yout_templateSign";
            int detector = 0;
            int classifierId = "your_classifier_id";
            string image_path = "your_file_path";
            string image_b64 = FileUtils.getFileBase64(image_path);
            // iocr按模板id识别的请求bodys
            string recognise_bodys = "access_token=" + access_token + "&templateSign=" + templateSign + 
                            "&image=" + HttpUtility.UrlEncode(image_b64);
            // iocr按分类器id识别的请求bodys
            int classifierId = "your_classifier_id";
            String classifier_bodys = "access_token=" + access_token + "&classifierId=" + classifierId + "&image=" + HttpUtility.UrlEncode(image_b64);
            
            HttpWebRequest httpWebRequest = (HttpWebRequest)WebRequest.Create(recognise_api_url);
            httpWebRequest.ContentType = "application/x-www-form-urlencoded";
            httpWebRequest.Method = "POST";
            httpWebRequest.KeepAlive = true;
            try{
                byte[] btBodys = Encoding.UTF8.GetBytes(recognise_bodys);
                // 请求分类器id
                // byte[] btBodys = Encoding.UTF8.GetBytes(classifier_bodys);
                
                httpWebRequest.ContentLength = btBodys.Length;
                httpWebRequest.GetRequestStream().Write(btBodys, 0, btBodys.Length);
                HttpWebResponse httpWebResponse = (HttpWebResponse)httpWebRequest.GetResponse();
                StreamReader streamReader = new StreamReader(httpWebResponse.GetResponseStream());
                string responseContent = streamReader.ReadToEnd();
                Console.WriteLine(responseContent);
                httpWebResponse.Close();
                streamReader.Close();
                httpWebRequest.Abort();
                httpWebResponse.Close();
            } catch (Exception e){
                Console.Write(e.Message);
            }         
        }
    }
}
        

            #import <Foundation/Foundation.h>

static NSString *const recognise_api_url = @"https://aip.baidubce.com/rest/2.0/solution/v1/iocr/recognise";

@interface iocrDemo : NSObject

- (NSData *)get_image_b64: (NSString *)image_path ;

- (void) iocr_regenize:(NSData *)image_b64 :(NSString *)templateID : (NSString *)classifierId :(NSString *)token;

@end

@implementation iocrDemo

- (NSData *)get_image_b64: (NSString *)image_path {
    
    NSInputStream *inputStream = [[NSInputStream alloc] initWithFileAtPath:image_path];
    [inputStream open];
    //初始化:NSData创建后不可以再修改，NSMutableData可以再次修改。
    NSMutableData *mData = [[NSMutableData alloc] init];
    //填充数据
    NSData *appData=[[NSData alloc] init];
    while([inputStream hasBytesAvailable]){
        //单次读入的最大长度
        uint8_t buf[1024];
        NSUInteger len = [inputStream read:buf maxLength:sizeof(buf)];
        appData = [NSData dataWithBytes:buf length:len];
        //填充数据
        [mData appendData:appData];
    }
    [inputStream close];
    return mData;
}

+ (NSString *)base64Escape:(NSString *)string {
    NSCharacterSet *URLBase64CharacterSet = [[NSCharacterSet characterSetWithCharactersInString:@"/+=\n"] invertedSet];
    return [string stringByAddingPercentEncodingWithAllowedCharacters:URLBase64CharacterSet];
}
+ (NSString *)wwwFormWithDictionary:(NSDictionary *)dict {
    NSMutableString *result = [[NSMutableString alloc] init];
    if (dict != nil) {
        for (NSString *key in dict) {
            if (result.length)
                [result appendString:@"&"];
            [result appendString:[self base64Escape:key]];
            [result appendString:@"="];
            [result appendString:[self base64Escape:dict[key]]];
        }
    }
    return result;
}
/**
 * 通用的请求API服务的方法
 */
- (void)custom_apiRequestWithURL:(NSString *)URL
                       withToken:(NSString *)token
                   options:(NSDictionary *)options {
    NSLog(@"start......");
    
    NSDictionary *getParams = @{
                                @"access_token": token
                                };
    NSLog(@"------------%@",getParams);
    
    NSURL *url = [NSURL URLWithString:[NSString stringWithFormat:@"%@?%@", URL, [iocrDemo wwwFormWithDictionary:getParams]]];
    NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:url];
    [request setHTTPMethod:@"POST"];
    [request setValue:@"application/x-www-form-urlencoded" forHTTPHeaderField:@"Content-Type"];
    [request setValue:@"application/json" forHTTPHeaderField:@"Accept"];
    
    NSString *formData = [iocrDemo wwwFormWithDictionary:options];
    [request setHTTPBody:[formData dataUsingEncoding:NSUTF8StringEncoding]];
    // 开始发送请求，并把服务器返回的数据放到data变量里面
    NSData * data = [NSURLConnection sendSynchronousRequest:request returningResponse:nil error:nil];
    //把网页的原始数据解析出来并保存在字典里面，这里说的是json数据解析
    NSString *zhuanma = [[NSString alloc]initWithData:data encoding:NSUTF8StringEncoding];
    //把字典里面的数据转化为我们能看得懂的中文或者英文。
    NSLog(@"%@",zhuanma);//打印测试数据是否成功获取
}

- (void) iocr_regenize:(NSData *)image_b64 :(NSString *)templateID :(NSString *)classifierId :(NSString *)token{
    
    NSDictionary * options = nil;
    NSMutableDictionary *dict = [NSMutableDictionary dictionaryWithDictionary:options];
    
    dict[@"image"] = [image_b64 base64EncodedStringWithOptions:0];
    //请求分类器识别
    dict[@"classifierId"] = classifierId;
    //请求模板识别
    //dict[@"templateSign"] = templateID;
    //successHandler 成功回调 ,failHandler 失败回调
    [self custom_apiRequestWithURL:recognise_api_url withToken:token options:dict ];
}
@end

int main(int argc, const char * argv[]) {
    @autoreleasepool {
        NSString* token = @"your_access_token";
        NSString* image_path = @"your_file_path";
        NSString* templateSign = @"your_templateSign";
        NSString* classifierId = @"your_classifier_id";
        iocrDemo *i_demo = [iocrDemo new];
        // 获取本地图片的base64
        NSData *image_b64 = [i_demo get_image_b64:image_path];
        // 请求识别
        [i_demo iocr_regenize:image_b64 :templateSign :classifierId :token];
    }
    return 0;
}
        

返回说明

返回参数

字段	是否必选	类型	说明
logid	是	uint64	唯一的log id，用于问题定位
error_code	是	int	0代表成功，如果有错误码返回可以参考错误码列表排查问题
error_msg	是	string	如果error_code具体的失败信息，可以参考下方错误码列表排查问题
data	是	jsonObject	识别返回的结果
+ isStructured	是	string	表示是否结构化成功，true为成功，false为失败；成功时，返回结构化的识别结果；失败时，如果能识别，按行返回识别结果，如果不能识别，返回空
+ templateSign	否	string	图片分类结果对应的模板id或指定使用的模版id
+ scores	否	float	分类置信度，如果指定templateSign，则该值为1
+ ret	否	jsonArray	识别出来的字段数组，每一个单元里包含以下几个元素
++ word_name	否	string	isStructured 为 true 时存在，表示字段的名字；如果 isStructured 为 false 时，不存在
++ word	否	string	识别的字符串或单字
++ location	否	jsonObject	字段在原图上对应的矩形框
++ probability	否	jsonObject	字段的置信度，包括平均、最小和方差

返回示例

                JSON
                
            

                {
    "data": {
        "ret": [
            {
                "probability": {
                    "average": 0.998482,
                    "min": 0.9957,
                    "variance": 0.000002
                },
                "location": {
                    "height": 88,
                    "left": 1202,
                    "top": 437,
                    "width": 267
                },
                "word_name": "终点站",
                "word": "天津"
            },
            {
                "probability": {
                    "average": 0.994316,
                    "min": 0.629856,
                    "variance": 0.000281
                },
                "location": {
                    "height": 82,
                    "left": 359,
                    "top": 593,
                    "width": 660
                },
                "word_name": "发车时间",
                "word": "201706092107"
            },
            {
                "probability": {
                    "average": 0.998482,
                    "min": 0.9957,
                    "variance": 0.000002
                },
                "location": {
                    "height": 90,
                    "left": 432,
                    "top": 432,
                    "width": 261
                },
                "word_name": "始发站",
                "word": "北京南"
            },
            {
                "probability": {
                    "average": 0.952242,
                    "min": 0.77037,
                    "variance": 0.008272
                },
                "location": {
                    "height": 79,
                    "left": 879,
                    "top": 464,
                    "width": 252
                },
                "word_name": "车次",
                "word": "C2097"
            },
            {
                "probability": {
                    "average": 0.980604,
                    "min": 0.932502,
                    "variance": 0.000352
                },
                "location": {
                    "height": 74,
                    "left": 982,
                    "top": 877,
                    "width": 206
                },
                "word_name": "乘车人",
                "word": "向宇波"
            },
            {
                "probability": {
                    "average": 0.994155,
                    "min": 0.903164,
                    "variance": 0.000396
                },
                "location": {
                    "height": 65,
                    "left": 1171,
                    "top": 593,
                    "width": 248
                },
                "word_name": "座位号",
                "word": "07车无座"
            },
            {
                "probability": {
                    "average": 0.993914,
                    "min": 1.2888,
                    "variance": 0.000009
                },
                "location": {
                    "height": 67,
                    "left": 429,
                    "top": 674,
                    "width": 193
                },
                "word_name": "价格",
                "word": "54.50"
            }
        ],
        "templateSign": "1c65a67f151df56ba4e29c4dddace5ee",
        "scores": 1,
        "isStructured": true,
        "logId": "153206517722624"
    },
    "error_code": 0,
    "error_msg": ""
}
            

使用流程

iOCR财会版

百度智能云

文字识别

文字识别

API文档

在线调试

请求说明

返回说明