Clova OCR Custom API Spec.

Status: finished v1.0

version date update
v1.0 2019-10-17 version 1.0

1. General Object Model Spec

1.1. Bounding
Json Model field Description
{ "top": 0.0, "left": 0.0, "width": 0.0, "height": 0.0 } top Bounding top Y coordinate.
left Bounding left X coordinate.
with Bounding with.
height Bounding height.

1.2. ImageField

Json Model field Description
{ "name": "string", "valueType": "string", "inferText": "string", "inferConfidence": 0.0, "bounding": {} } name Field name.
valueType Not always exists. The field text value type. “ALL”: both text and number “TEXT”: text priority “NUMERIC”: number priority
inferText The inferred text of this field.
inferConfidence The confidence of inferred result. 0-1, the bigger the more precise.
bounding [Bounding] Object refer to 1.1 If field is sub-field in area, the bounding axis is relative to parent area bounding.

1.3. ImageArea

Json Model field Description
{ "name": "string", "type": "string", "bounding": {}, "fields": [ {} ] } name Area name.
type The area type. “NORMAL”: normal area “EXCLUDE”: exclude area, will not contains infer result
bounding [Bounding] Object refer to 1.1
fields Json object array. Elements are ImageField Object. [ImageField] Object refer to 1.2 All sub-fields in the area.

1.4. Image Infer Request

Json Model field Description
{ "version": "string", "requestId": "string", "timestamp": 0, , "lang": "string", "images": [ { "format": "string", "url": "string", "data": "string", "name": "string", "templateIds": [ 0 ] } ] } version Required. “V1” Custom API major version string. Current is “V1”.
requestId Required. Request unique id to trace, will response. Recommended uuid.
timestamp Required. Current timestamp.
lang Optional. Specify which language used to infer.
images Required. Json array. Currently only support 1 image.
images.format Image format. Currently support “jpg”, “jpeg”, “png”.
images.url One of URL and data must exists. URL is the public URL to get the image.
image.data One of URL and data must exists. Data is base64 encode image bytes. If both URL and data exists, will use data, URL will ignore.
image.name Required. Image name is used to identify image. Currently not used. Only response.
image.templateIds Optional. Integer array. Template id list. Define use which templates to infer image. Text OCR API: not used. Domain Image Infer API: if not set, will auto classify with all service deployed templates in domain.

1.5. Image Infer Response

Json Model field Description
{ "uid": "string", "name": "string", "inferResult": "string", "message": "string", "matchedTemplate": { "id": 0, "name": "string" }, "title": {}, "areas": [ {} ], "fields": [ {} ], "validationResult": { "result": "string", "message": "string", } } uid An unique id which is delivered to validate API.
name Image name in request.
inferResult Image infer result. “SUCCESS”: infer success. “FAILURE”: infer failure.
message “SUCCESS”: infer success. If infer failure, will response some details error message.
matchedTemplate The matched template information. Contains template id and name. If infer failure, or not found matched template, will not contains this field in response.
title Image title. [ImageField] Object refer to 1.2 Not contains valueType filed.
areas Image areas in matched template, contains sub-fields. Json array object. Element is [ImageArea] Object refer to 1.3
fields Fields in matched template. Json array object. Element is [ImageField] Object refer to 1.2
validationResult The validation result. Always exists.
validationResult.result Result code. “NO_REQUESTED”: template not set validate action. “UNCHECKED”: validate action response not checked. “ERROR”: invoke validate action error. “VALID”: infer result valid. “INVALID”: infer result is invalid.
validationResult.message Some detail message. Not always exists.

2. Custom API

Custom API should access via API Gateway. Before use custom API, you should subscription Ncloud API Gateway product and interlock with API Gateway first.

2.1. Custom API Interlock

2.1.1. API Gateway interlock guide

Automatic Interlock

  • If you have not interlocked with API Gateway, you could click “Automatic linkage” button, we’ll try to create API Gateway product for you automatically. But if you not subscription API Gateway, interlock will failed.

ocr_api_01.jpg

  • After interlocked, you could get one “APIGW Invoke URL”. APIGW Invoke URL is the full custom API request URL.

ocr_api_02.jpg

  • You can find one product in API Gateway named “CLOVA_OCR_CUSTOM_API”. But please don’t modify any resource in it.

Pay Attention: Please don’t modify that product.

ocr_api_03.jpg

  • If “CLOVA_OCR_CUSTOM_API” in API Gateway have been modified or deleted, you also could use interlock button to repair.

Manual Interlock

  • You could get API Gateway swagger json file “OCR_CUSTOM_API_EXTERNAL_V1.json” from custom interlock page.

ocr_api_04.jpg

  • Then you could create API in API Gateway by “Import from Swagger”.

ocr_api_05.jpg

  • Next, create one stage, and use custom endpoint. ocr_api_06.jpg
  • The endpoint URL could find in custom interlock page, use the “OCR Invoke URL”. ocr_api_07.jpg

  • After create stage, there is an “Invoke URL”, the full custom API URL is concatenate “Invoke URL” and the custom API path. For example: The “General Text OCR” API path is general, so the full request URL is https://9240qacz2i.apigw.ntruss.com/interlock/demo/general.

ocr_api_08.jpg

2.1.2. Configure Text OCR API
  • If you want to use “Text OCR API”, you can find custom configure in NCloud Console. ocr_api_09.jpg

  • Please create “Secret Key”. This key will used in custom API request header as token. ocr_api_10.jpg

  • The APIGW Invoke URL is like this: https://sld5c1k4iy. apigw.ntruss.com/custom/v1/56/4340d8b9ca9222e71d58c64a38587f96cdfa4ef40d488e9dd4a1034c60d8d47b/**general**

2.1.3. Configure Text OCR API
  • If you want to use image infer API in one domain, you can find custom configure in Clova OCR web.

ocr_api_11.jpg

  • Please create “Secret Key”. This key will used in custom API request header as token

ocr_api_12.jpg

  • The APIGW Invoke URL is like this: https://sld5c1k4iy.apigw.ntruss.com/custom/v2/80/3f7d3abd68d04bb791c3b993276c778119ed874bde00db68d57344c2df7e973c/infer

3. Custom API Spec

3.1. Basic Information

Protocol Https
Http Method POST
Request Body Content Type application/json
Required Request Header X-OCR-SECRET
Response Body Content Type application/json
Body Charset UTF-8

X-OCR-SECRET: The secret key from custom interlock configure page.

3.2. Error Response

Http Status Code Reason
400 Request parameters invalid or constraint problem.
401 Api secret(X-CHATBOT-API-KEY) wrong
500 Internal server error

Error Response Body:

{
  "code": "Error Code",
  "message": "error details message.",
  "path": "request API path",
  "timestamp": 1570776853475
}

Error Code Define

Error Code Define
0001 URL is invalid.
0002 Secret key validate failed.
0011 Request body invalid.
0021 Protocol version not support.
0022 Request domain invalid.
0023 API request count reach the upper limit.
0500 Unknown service error.
1021 Not found deploy infomation.

3.3. General Text OCR

This API could infer all text on image without domain or template define.

Request
Path /general
Body [Image Infer Request] Object Required Refer to 1.4.
Response
Body [Image Infer Response] Object Required Refer to 1.5. matchedTemplate, areas title and validationResult will not exists.

3.4. Domain Infer API

This API could infer image with service deployed templates in one domain.

Request
Path /infer
Body [Image Infer Request] Object Required Refer to 1.4.
Response
Body [Image Infer Response] Object Required Refer to 1.5.

4. Validate API Spec.

Http Method POST
Request Body Content Type application/json
Response Body Content Type application/json
Body Charset UTF-8
URL The validate action URL
Timeout 1 second. If timeout, process as validate error.
Response Http Status 200 ? success Not 200 - error

Request Body:

Json Model field Description
{ image:{} } image The image infer result should be validated. Is [Image Infer Response] Object refer to 1.5.

Respsonse Body:

Json Model field Description
{ "uid": "string", "validationResult": "string", "message": "string" } uid Required. The uid in request body image.uid field. If this not match, result will not be accepted. Is [Image Infer Response Object] refer to 1.5.
validationResult Required. “VALID”: infer result valid. “INVALID”: infer result is invalid. Other string is not accepted, will be ignored as “UNCHECKED”.
message Optional. The details message of validate. Will response in [Image Infer Response] Object.

""에 대한 건이 검색되었습니다.

    ""에 대한 검색 결과가 없습니다.

    처리중...