TeleOCR-KIE（算法编码8000400029）

一、接入点

环境	地址
公网	https://api-maas.teleai.com.cn/aipaas/ocr/v1/kie/ocr

• 请求方法 ：POST
• Content-Type ：application/json

二、鉴权

在请求头中携带 X-APP-ID、Authorization 两个 Header：

X-APP-ID: <从“控制台 - 应用及API Key - AppID” 处获得>
Authorization: <鉴权头，其生成逻辑详见 https://www.teleai.com.cn/doc/wv8U2R0iUcsuLqxKURBA/uGTzGNO3S6jlkNyHt4lk 文档中，“Authorization生成方式”一节>

带鉴权的请求头形如：

头部标签	必填	说明	示例
Content-Type	是	内容类型，请设置为application/json	application/json
X-APP-ID	是	从“控制台 - 应用及API Key - AppID” 处获得	c27a**** **0ed5d64
Authorization	是	鉴权头，其生成逻辑详见https://www.teleai.com.cn/doc/wv8U2R0iUcsuLq2KURBA/uGTzGNO3S6jkNyHt4lk 文档中，“Authorization生成方式”一节	teleai-cloud-auth-v1/c27a**** *

三、模型能力与模型限制

3.1 模型能力

能力项	说明
自定义字段抽取	根据用户输入schema 中的自定义字段，对 jpg / png / pdf / webp 格式输入文件进行信息提取
结构化输出	返回 “字段-值” JSON 结构
HTML 转义保护	html_escape=true 时对识别文本做 HTML 转义，上层展示无需再处理 XSS 注入

3.2 模型限制

限制项	说明
图片大小与边长	图片 base64 编码后大小不超过 10MB，最短边至少 20px
图片格式	支持 jpg / jpeg / png / webp
PDF 处理	当前版本仅支持 pdf 首页处理
image_type 取值	只能填 0、1；0 代表 url，1 代表 base64
schema 字段类型	V1.0 版本仅支持配置String 类型字段

四、请求体与响应体

4.1 请求体

请求体为 JSON Object，Content-Type 为 application/json。

字段	类型	必填	说明
seqid	string	是	接口跟踪 ID，每次调用需不同，可使用 UUID，用于日志排查、链路跟踪；长度不超过 32 位
image	string	是	支持图像、PDF等文件的Base64编码、或图像、PDF等文件的URL，具体类型需要通过image_type 指定
image_type	int	是	用于指定image 字段的输入类型，image_type设置为0时，image字段必须为URL，默认为 0；image_type设置为1时，image必须为base64码
html_escape	boolean	否	是否 HTML 转义，用于解决 XSS 漏洞，默认true
schema	object	是	抽取字段及其定义，标准 JSON Schema 格式，V1.0 仅支持配置String 类型字段

schema 结构示例：

{
    "type": "object",
    "properties": {
        "姓名": { "type": "string" },
        "编号": { "type": "string" },
        "地址": { "type": "string" }
    }
}

4.2 请求体示例

{
    "seqid": "test_seq0",
    "image": "/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAMCAgICAgMCAgIDAwMDBAYEBAQEBAgGBgUGC...==",
    "html_escape": true,
    "image_type": 1,
    "schema": {
        "type": "object",
        "properties": {
            "姓名": { "type": "string" },
            "编号": { "type": "string" },
            "地址": { "type": "string" }
        }
    }
}

4.3 响应体

成功时返回 HTTP 200，响应体为 JSON Object。

字段	类型	说明
seqid	string	调用时传入的跟踪 ID
code	string	状态响应码，10000 为成功，其他为失败
message	string	调用结果描述
flag	int	业务上成功或失败：1 成功，0 失败
data	object	识别结果
data>>time_second	double	识别耗时（秒）
data>>words_result	object	提取结果，字段名为 schema 中定义的字段
data>>usage>>completion_tokens	int	生成 tokens
data>>usage>>prompt_tokens	int	prompt 的 tokens
data>>usage>>total_tokens	int	总 tokens
data>>total_page_number	int	处理的文档页数

4.4 响应体示例

{
    "seqid": "req-20260310-7b8c9d2e",
    "code": "10000",
    "message": "成功",
    "flag": 1,
    "data": {
        "time_second": 0.452,
        "words_result": {
            "姓名": "张三",
            "编号": "",
            "地址": "北京市朝阳区xx路xx号"
        },
        "usage": {
            "completion_tokens": 40,
            "prompt_tokens": 23,
            "total_tokens": 63
        },
        "total_page_number": 1
    }
}

4.5 响应体 Code 码说明

Code 码	状态描述	状态说明
10000	请求成功	服务执行成功
10301	服务必填参数缺失	服务必填参数缺失或未填写
10304	服务参数错误	服务参数数据类型或取值错误
10305	图片相关错误	图片大小错误、格式错误或获取失败
10903	服务执行失败	模型推理结果异常，或服务执行失败

五、调用示例

5.1 curl

curl -X POST 'https://api-maas.teleai.com.cn/aipaas/ocr/v1/kie/ocr' \
  -H 'Content-Type: application/json' \
  -H 'X-APP-ID: <your_app_id>' \
  -H 'Authorization: <your_authorization>' \
  -d '{
        "seqid": "test_seq0",
        "image": "<base64_or_url>",
        "html_escape": true,
        "image_type": 1,
        "schema": {
            "type": "object",
            "properties": {
                "姓名": { "type": "string" }
            }
        }
      }'

5.2 Python

import base64
import hashlib
import hmac
import json
import time
import urllib.parse
import uuid

import requests

# 配置
X_APP_ID = "your_app_id"
X_APP_KEY = "your_app_key"
REGION = "BJ"
EXPIRATION_IN_SECONDS = "43200"
SIGNED_HEADERS = "x-app-id"
SIGNING_HEADER = "teleai-cloud-auth-v1"
URL = "https://api-maas.teleai.com.cn/aipaas/ocr/v1/kie/ocr"


def normalize(s, encoding_slash=True):
    return urllib.parse.quote(s, safe="~()*!'/" if encoding_slash else "~()*!'")


def generate_canonical_uri(path):
    parsed = urllib.parse.urlparse(path)
    return "/".join(normalize(seg, False) for seg in parsed.path.split("/"))


def generate_canonical_headers(headers_map):
    signed = SIGNED_HEADERS.split(";")
    signed_set = set(signed)
    sorted_headers = sorted(
        (k.lower(), urllib.parse.quote(v.strip(), safe=""))
        for k, v in headers_map.items()
        if k.lower() in signed_set
    )
    canonical_headers = "".join(f"{k}:{v}" for k, v in sorted_headers)
    return canonical_headers, ";".join(sorted(signed_set))


def get_authorization(app_id, app_key, method, path, query=""):
    timestamp = str(int(time.time()))
    canonical_uri = generate_canonical_uri(path)
    base_headers = {"Content-Type": "application/json", "X-APP-ID": app_id}
    canonical_headers, signed_headers_str = generate_canonical_headers(base_headers)
    signing_key_str = f"{SIGNING_HEADER}/{app_id}/{REGION}/{timestamp}/{EXPIRATION_IN_SECONDS}"
    signing_key = hmac.new(app_key.encode(), signing_key_str.encode(), hashlib.sha256).hexdigest()
    canonical_request = f"{method.upper()}\n{canonical_uri}\n{query}\n{canonical_headers}"
    signature = hmac.new(signing_key.encode(), canonical_request.encode(), hashlib.sha256).hexdigest()
    authorization = f"{signing_key_str}/{signed_headers_str}/{signature}"
    return timestamp, authorization


def encode_image(path):
    with open(path, "rb") as f:
        return base64.b64encode(f.read()).decode("ascii")


def main():
    image_path = "test.png"  # 修改为你的图片路径
    timestamp, authorization = get_authorization(X_APP_ID, X_APP_KEY, "POST", "/aipaas/ocr/v1/kie/ocr")

    headers = {
        "Content-Type": "application/json",
        "X-APP-ID": X_APP_ID,
        "Authorization": authorization
    }
    payload = {
        "seqid": uuid.uuid4().hex[:32],
        "image": encode_image(image_path),
        "html_escape": True,
        "image_type": 1,
        "schema": {
            "type": "object",
            "properties": {
                "姓名": {"type": "string"},
                "编号": {"type": "string"},
                "地址": {"type": "string"},
            },
        },
    }
    resp = requests.post(URL, json=payload, headers=headers, timeout=60)
    print(json.dumps(resp.json(), ensure_ascii=False, indent=2))


if __name__ == "__main__":
    main()

5.3 Java

import cn.hutool.http.HttpRequest;
import cn.hutool.http.HttpResponse;
import com.alibaba.fastjson.JSONObject;

import java.util.HashMap;
import java.util.Map;

public class KieExample {

    public static void main(String[] args) {
        String url = "https://api-maas.teleai.com.cn/aipaas/ocr/v1/kie/ocr";

        Map<String, String> headers = new HashMap<>();
        headers.put("Content-Type", "application/json");
        headers.put("X-APP-ID", "your_app_id");
        headers.put("Authorization", "your_authorization");

        JSONObject schema = new JSONObject();
        schema.put("type", "object");
        JSONObject properties = new JSONObject();
        properties.put("姓名", new JSONObject().fluentPut("type", "string"));
        properties.put("编号", new JSONObject().fluentPut("type", "string"));
        properties.put("地址", new JSONObject().fluentPut("type", "string"));
        schema.put("properties", properties);

        JSONObject body = new JSONObject();
        body.put("seqid", "test_seq0");
        body.put("image", "<base64_or_url>");
        body.put("html_escape", true);
        body.put("image_type", 1);
        body.put("schema", schema);

        HttpResponse response = HttpRequest.post(url)
                .headerMap(headers, true)
                .body(body.toJSONString())
                .execute();
        System.out.println(response.body());
    }
}