# Generated by ShowAPI OpenAPI generator
# source: market/1429
# generated-at: 2026-06-26T06:01:27.992Z
openapi: 3.0.3
info:
  title: 个人证照OCR识别
  description: 身份证OCR-银行卡OCR-护照OCR-户口页OCR文字识别等个人证件类的图片内容自动识别，快速提取图片中的字段信息，包括姓名、性别、民族、出生日期、住址、身份证号、签发机关、有效期限等可用内容。
  termsOfService: https://www.showapi.com/helpcenter/view#/4019/2
  version: 1.0.0
servers:
  - url: https://route.showapi.com
paths:
  /1429-7:
    x-pointCode: 7
    x-mode: mapping
    x-read-timeout: 45
    x-connect-timeout: 15
    post:
      summary: 银行卡识别标准版
      description: |-
        输入主流银行卡图像，输出4个信息，包括：银行卡号、银行名称、银行卡类型、错误信息。
        建议图片不要超过1M。
      responses:
        "200":
          description: 成功响应
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ShowapiResEnvelope"
                  - type: object
                    properties:
                      showapi_res_body:
                        type: object
                        properties:
                          ret_code:
                            type: number
                            description: |-
                              0 表示调用成功
                               10 参数错误
                               20 文件格式错误
                               30 操作失败,请勿重复提交
                               40 文件下载失败
                               50 文件内容过大
                               60 图片解析失败
                               70 OCR识别失败
                               80 服务超时
                               90 未知错误
                          remark:
                            type: string
                            description: 错误信息
                          card_num:
                            type: string
                            description: 银行卡号
                          card_type:
                            type: string
                            description: 银行卡类型 （借记卡、贷记卡、准贷记卡、信用卡）
                          bank_name:
                            type: string
                            description: 银行名称
                        description: 业务返回体
      operationId: 1429_7_POST
      parameters: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                img_base64:
                  type: string
                  minLength: 0
                  maxLength: 10000000
                  description: 银行卡图片的base64信息字符串，部分编程语言，如PHP，在调用时需要将ba64字符串进行urlencode处理。img_base64字符串和img_url二选一入参。
                img_url:
                  type: string
                  description: 要识别图片的URL地址。img_base64字符串和img_url二选一入参
  /1429-6:
    x-pointCode: 6
    x-mode: mapping
    x-read-timeout: 10
    x-connect-timeout: 5
    post:
      summary: 户口页识别
      description: 识别户口簿中的文字信息，输出姓名、性别、身份证号、籍贯、出生地、婚姻状况、宗教信仰、文化程度、职业、与户主的关系、身高、兵役状况、登记日期等共21个关键信息。暂无法识别户主页。
      responses:
        "200":
          description: 成功响应
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ShowapiResEnvelope"
                  - type: object
                    properties:
                      showapi_res_body:
                        type: object
                        properties:
                          sex:
                            type: string
                            description: 性别
                          birth_date:
                            type: string
                            description: 生日
                          name:
                            type: string
                            description: 姓名
                          ext_paras:
                            type: object
                            properties:
                              mar_status:
                                type: string
                                description: 婚姻状况
                              used_name:
                                type: string
                                description: 曾用名
                              belief:
                                type: string
                                description: 宗教信仰
                              edu_degree:
                                type: string
                                description: 文化程度
                              career:
                                type: string
                                description: 职业
                              relation:
                                type: string
                                description: |
                                  与户主关系
                              to_city:
                                type: string
                                description: 何时由何地迁来本市
                              blood_type:
                                type: string
                                description: 血型
                              addr:
                                type: string
                                description: 住址
                              type:
                                type: string
                                description: 户别
                              house_num:
                                type: string
                                description: 户号
                              to_here:
                                type: string
                                description: 何时由何地迁往本址
                              ret_code:
                                type: number
                                description: |-
                                  0 无异常
                                  10 参数错误
                                       20 文件格式错误
                                       30 操作失败,请勿重复提交
                                       40 文件下载失败
                                       50 文件内容过大
                                       60 图片解析失败
                                       70 OCR识别失败
                                       80 服务超时
                                       90 未知错误(error_code)
                              height:
                                type: string
                                description: 身高
                              veteran_status:
                                type: string
                                description: 兵役状况
                              record_date:
                                type: string
                                description: 登记日期
                              work_place:
                                type: string
                                description: 服务处所
                            description: 扩展字段，可能返回空字符串
                          card_no:
                            type: string
                            description: 身份证号码
                          birth_place:
                            type: string
                            description: 出生地
                          nation_place:
                            type: string
                            description: 籍贯
                          nation:
                            type: string
                            description: 民族
                          remark:
                            type: string
                            description: 错误信息
                        description: 业务返回体
      operationId: 1429_6_POST
      parameters: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                img_base64:
                  type: string
                  minLength: 0
                  maxLength: 10000000
                  description: 要识别图片的base64编码。ime_base64和img_url二选一入参
                img_url:
                  type: string
                  description: 要识别图片的url，ime_base64和img_url二选一入参
  /1429-5:
    x-pointCode: 5
    x-mode: mapping
    x-read-timeout: 35
    x-connect-timeout: 35
    post:
      summary: 中国护照识别
      description: |-
        识别中国护照关键字段内容，包括：中文姓名（带拼音）、护照号码、性别、出生日期、出生地、国籍、发证日期、结束日期、发证地址、MRZ码第一行等。
        请保证图片的清晰度。
      responses:
        "200":
          description: 成功响应
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ShowapiResEnvelope"
                  - type: object
                    properties:
                      showapi_res_body:
                        type: object
                        properties:
                          ret_code:
                            type: string
                            description: 接口查询是否成功,0为调用成功,其他值为失败
                          passport_num:
                            type: string
                            description: 护照号码
                          issue_date:
                            type: string
                            description: 签发日期
                          issue_place:
                            type: string
                            description: 签发地点
                          authority:
                            type: string
                            description: 签发机关
                          expiry_date:
                            type: string
                            description: 有效期截止
                          passport_code1:
                            type: string
                            description: MRZCode1,护照下方第一行编码
                          passport_code2:
                            type: string
                            description: MRZCode2,护照下方第二行编码
                          country_code:
                            type: string
                            description: 国家码
                          passport_type:
                            type: string
                            description: 护照类型
                          birth_place:
                            type: string
                            description: 出生地点
                          birthday:
                            type: string
                            description: 出生日期
                          chinese_name:
                            type: string
                            description: 中文名
                          name:
                            type: string
                            description: 姓名
                          nationality:
                            type: string
                            description: 国籍
                          sex:
                            type: string
                            description: 性别
                        description: 业务返回体
      operationId: 1429_5_POST
      parameters: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                img_base64:
                  type: string
                  minLength: 0
                  maxLength: 10000000
                  description: 护照图片对应的base64信息，不能超多4M
                img_url:
                  type: string
                  description: 护照图片对应的url信息
  /1429-4:
    x-pointCode: 4
    x-mode: mapping
    x-read-timeout: 45
    x-connect-timeout: 15
    post:
      summary: 银行卡识别精准版
      description: |-
        输入主流银行卡图像，输出5个信息，包括：银行卡号、银行名称、银行卡类型、错误信息。
        相对于标准版，该接口能识别卡片上的有效期，
        有较高的识别成功率，
        建议图片不要超过1M。
      responses:
        "200":
          description: 成功响应
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ShowapiResEnvelope"
                  - type: object
                    properties:
                      showapi_res_body:
                        type: object
                        properties:
                          ret_code:
                            type: number
                            description: |-
                              0 表示调用成功
                               10 参数错误
                               20 文件格式错误
                               30 操作失败,请勿重复提交
                               40 文件下载失败
                               50 文件内容过大
                               60 图片解析失败
                               70 OCR识别失败
                               80 服务超时
                               90 未知错误
                          remark:
                            type: string
                            description: 错误信息
                          card_num:
                            type: string
                            description: 银行卡号
                          card_type:
                            type: string
                            description: 银行卡类型 （借记卡、贷记卡、准贷记卡、信用卡）
                          valid_date:
                            type: string
                            description: 有效期
                          bank_name:
                            type: string
                            description: 银行名称
                        description: 业务返回体
      operationId: 1429_4_POST
      parameters: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                img_base64:
                  type: string
                  minLength: 0
                  maxLength: 10000000
                  description: 银行卡图片的base64信息字符串，部分编程语言，如PHP，在调用时需要将ba64字符串进行urlencode处理。img_base64字符串和img_url二选一入参。
                img_url:
                  type: string
                  description: 要识别图片的URL地址。img_base64字符串和img_url二选一入参
  /1429-3:
    x-pointCode: 3
    x-mode: mapping
    x-read-timeout: 10
    x-connect-timeout: 5
    post:
      summary: OCR身份证识别（正面）
      description: 这个接入点主要是识别身份证正面文字内容，如姓名、性别、民族、身份证号、家庭住址等。但需要这些额外的信息可能会使识别消耗更多时间！当未识别出身份证号码时不计费，但同一照片多次识别失败后可能会适当扣费。
      responses:
        "200":
          description: 成功响应
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ShowapiResEnvelope"
                  - type: object
                    properties:
                      showapi_res_body:
                        type: object
                        properties:
                          msg:
                            type: string
                            description: 错误信息
                          birthday:
                            type: string
                            description: 生日 (入参时need_more_info==1才会识别该字段)，没识别出返回空字符串
                          flag:
                            type: boolean
                            description: 身份证号码是否识别成功
                          nationality:
                            type: string
                            description: 民族(入参时need_more_info==1才会识别该字段)，没识别出返回空字符串
                          sex:
                            type: string
                            description: 性别(入参时need_more_info==1才会识别该字段)，没识别出返回空字符串
                          name:
                            type: string
                            description: 姓名(入参时need_more_info==1才会识别该字段)，没识别出返回空字符串
                          addr:
                            type: string
                            description: 地址(入参时need_more_info==1才会识别该字段)，没识别出返回空字符串
                          ret_code:
                            type: number
                            description: 是否扣费0表示扣费，-1表示不扣费
                          idNo:
                            type: string
                            description: 身份证号码
                        description: 业务返回体
      operationId: 1429_3_POST
      parameters:
        - name: imgData
          in: query
          description: 身份证照片的base64字符编码，建议base64编码后照片大小需小于1.5M， imgData和imgUrl必须选一个作为图片的入参方式
          required: false
          schema:
            type: string
            minLength: 0
            maxLength: 10000000
        - name: imgUrl
          in: query
          description: 身份证照片URL，建议照片大小需小于1M。imgData和imgUrl必须选一个作为图片的入参方式
          required: false
          schema:
            type: string
        - name: need_more_info
          in: query
          description: 是否需要返回除身份证号码外其他字段（包括：姓名、性别、生日、民族、住址）0表示 不需要，1表示需要。需要返回额外信息时，识别成功率会有所降低
          required: false
          schema:
            type: string
  /1429-2:
    x-pointCode: 2
    x-mode: mapping
    x-read-timeout: 30
    x-connect-timeout: 30
    post:
      summary: OCR身份证识别返照
      description: OCR身份证识别返照API接入点，能返回头像base64。可以应用于实名认证、安全验证、智能客服、身份信息核查、智能档案管理、无人机配送、酒店入住管理、边境管控、疫情防控以及智能停车系统等多个场景。
      responses:
        "200":
          description: 成功响应
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ShowapiResEnvelope"
                  - type: object
                    properties:
                      showapi_res_body:
                        type: object
                        properties:
                          msg:
                            type: string
                          birthday:
                            type: string
                          flag:
                            type: boolean
                            description: 业务识别是否成功
                          nationality:
                            type: string
                          sex:
                            type: string
                          name:
                            type: string
                          headImgBase64:
                            type: string
                          addr:
                            type: string
                          ret_code:
                            type: number
                          idNo:
                            type: string
                          depInfo:
                            type: string
                            description: 签发机关  国徽面才有该字段返回
                          effEndDate:
                            type: string
                            description: 有效期的截止日期(国徽面才返回该字段)格式：yyyy-MM-dd，可能返回“长期有效”字样
                          effDate:
                            type: string
                            description: 有效期的起始日期(国徽面才返回该字段)格式：yyyy-MM-dd
                          effBeginDate:
                            type: string
                            description: 签发日期(国徽面才返回该字段)格式：yyyy-MM-dd
                        description: 业务返回体
      operationId: 1429_2_POST
      parameters: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                imgData:
                  type: string
                  minLength: 0
                  maxLength: 10000000
                  description: 图片base64  imgData和imgUrl必须选一个作为图片的入参方式
                type:
                  type: string
                  description: 1正面，2反面，不输入我们可以自动识别。
                imgUrl:
                  type: string
                  description: 图片的URL  imgData和imgUrl必须选一个作为图片的入参方式
  /1429-1:
    x-pointCode: 1
    x-mode: mapping
    x-read-timeout: 30
    x-connect-timeout: 30
    post:
      summary: OCR身份证识别（正反面）
      description: 快速提取二代居民身份证正反面所有字段，包括姓名、性别、民族、出生日期、住址、身份证号、签发机关、有效期限等信息。
      responses:
        "200":
          description: 成功响应
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ShowapiResEnvelope"
                  - type: object
                    properties:
                      showapi_res_body:
                        type: object
                        properties:
                          name:
                            type: string
                            description: 姓名
                          sex:
                            type: string
                            description: 性别
                          nationality:
                            type: string
                            description: 民族
                          birthday:
                            type: string
                            description: 生日
                          addr:
                            type: string
                            description: 地址
                          idNo:
                            type: string
                            description: 身份证号码
                          headImgBase64:
                            type: string
                            description: 身份证图像的base64（若需要该字段值请使用身份证识别返照接口）
                          depInfo:
                            type: string
                            description: 签发部门(国徽面才返回该字段)
                          effDate:
                            type: string
                            description: 有效期的起始日期(国徽面才返回该字段)格式：yyyy-MM-dd
                          effBeginDate:
                            type: string
                            description: 签发日期(国徽面才返回该字段)格式：yyyy-MM-dd
                          effEndDate:
                            type: string
                            description: 有效期的截止日期(国徽面才返回该字段)格式：yyyy-MM-dd，可能返回“长期有效”字样
                          ret_code:
                            type: string
                            description: 接口调用是否成功,0为成功,其他为失败
                          flag:
                            type: string
                            description: 业务识别是否成功，false时，没有识别出的业务字段返回，只有错误信息返回。
                          msg:
                            type: string
                            description: 提示信息
                          quality:
                            type: array
                            items:
                              type: string
                            description: 片属性检测结果，需要入参needQuality为1才有该字段返回。shoot表示可能为翻拍，photo表示正式身份证，temporary表示为临时身份证，edited表示图片可能经过图片编辑软件的编辑，copy表示可能为复印件
                        description: 业务返回体
      operationId: 1429_1_POST
      parameters: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                imgData:
                  type: string
                  minLength: 0
                  maxLength: 10000000
                  description: 身份证图片的base64信息，建议图片小于1.5M，imgData和imgUrl必须选一个作为图片的入参方式
                type:
                  type: string
                  description: 身份证的正面或反面，正面1 反面2，不填我们可以自动识别
                imgUrl:
                  type: string
                  description: |-
                    身份证图片的URL,，议图片小于1.5M
                    imgData和imgUrl必须选一个作为图片的入参方式
                needQuality:
                  type: string
                  description: 是否需要返回图片属性检测，1表示需要，0表示不需要
components:
  securitySchemes:
    AppKeyAuth:
      type: apiKey
      in: query
      name: appKey
      description: 从 ShowAPI 控制台获取的 appKey，管理地址：https://www.showapi.com/console#/myApp
  schemas:
    ShowapiResEnvelope:
      type: object
      description: ShowAPI 统一返回包裹（业务数据位于 showapi_res_body）
      properties:
        showapi_res_code:
          type: integer
          description: API 返回的状态码
        showapi_res_error:
          type: string
          description: API 返回的错误信息
        showapi_res_id:
          type: string
          description: API 请求的唯一标识
        showapi_fee_num:
          type: integer
          description: API 调用计费次数
security:
  - AppKeyAuth: []
externalDocs:
  url: https://www.showapi.com/apiGateway/view/1429?tab=book
x-apiCode: "1429"
x-is-own: false
x-is-op: true
