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.

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

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.

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.

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

Next, create one stage, and use custom endpoint.

The endpoint URL could find in custom interlock page, use the “OCR Invoke URL”.
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.

2.1.2. Configure Text OCR API

If you want to use “Text OCR API”, you can find custom configure in NCloud Console.
Please create “Secret Key”. This key will used in custom API request header as token.
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.

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

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.

포털 바로가기 네이버 클라우드 플랫폼 설명서