CLOVA OCR Custom API

version

リクエスト

• TEXT OCR認識と Template OCR認識をリクエスト

リクエストヘッダ

リクエストボディ

Content-Type : application/json

1. 画像認識リクエスト

画像認識リクエストフィールドの詳細説明

CURL example:

curl --request POST 'your apigw invoke url' \
--header 'X-OCR-SECRET: your secret key' \
--data-raw '{"images":[{"format":"jpg","name":"demo","url":"your image url"}],"requestId":"guide-json-demo","version":"V2","timestamp":1584062336793}'

Content-Type : multipart/form-data

1. Image Recognition Request

Form Data Message Value Description

CURL example:

curl --request POST 'your apigw invoke url' \
--header 'X-OCR-SECRET: your secret key' \
--form 'message={"images":[{"format":"png","name":"demo"}],"requestId":"guide-demo","version":"V2","timestamp":1584062336793}' \
--form 'file=@image.png'

レスポンス

V1レスポンスボディ

Request version is 'V1'

1. 画像認識結果

画像認識結果フィールドの詳細説明

2. ImageFieldオブジェクト

ImageFieldオブジェクトフィールドの詳細説明

3. boundingオブジェクト

boundingオブジェクトフィールドの詳細説明

V2レスポンスボディ

Request version is 'V2'

1. Image Recognition Results

Detailed description of the Image Recognition Results field

2. ImageField object

ImageField Object Field Details

3. boundingPoly object

boundingPoly Object Field Details

4. vertices object

vertices Object Field Details

5. SubField Object

subField Object Field Details

6. ImageTable Object

ImageTable Object Field Details

7. TableCell Object

TableCell Object Field Details

8. CellTextLine Object

CellTextLine Object Field Details

9. CellWord Object

CellWord Object Field Details

例

TEXT OCRのリクエスト例

{
  "version": "V2",
  "requestId": "string",
  "timestamp": 0,
  "lang":"ko",
  "images": [
    {
      "format": "jpg",
      "name": "test 1",
      "url": "https://www.ncloud.com/ocr-test/test.jpg"
    }
  ]
}

TEXT OCRのレスポンス例

{
    "version": "V2",
    "requestId": "string",
    "timestamp": 1576569034247,
    "images": [{
        "uid": "9fd73a6aacad4025b3099a36ee55aacd",
        "name": "medium",
        "inferResult": "SUCCESS",
        "message": "SUCCESS",
        "fields": [{
                "valueType": "ALL",
                "inferText": "美しい",
                "inferConfidence": 0.99992156,
                "type": "NORMAL",
                "lineBreak": true,
                "boundingPoly": {
                    "vertices": [{
                        "x": 2713.7295,
                        "y": 1277.0492
                    }, {
                        "x": 2713.7295,
                        "y": 977.7408
                    }, {
                        "x": 2841.4343,
                        "y": 977.7408
                    }, {
                        "x": 2841.4343,
                        "y": 1277.0492
                    }]
                }
            },
            {
                "valueType": "ALL",
                "inferText": "これ",
                "inferConfidence": 0.99958915,
                "type": "NORMAL",
                "lineBreak": false,
                "boundingPoly": {
                    "vertices": [{
                        "x": 2314.6516,
                        "y": 1468.6066
                    }, {
                        "x": 2314.6516,
                        "y": 1328.9293
                    }, {
                        "x": 2426.3936,
                        "y": 1328.9293
                    }, {
                        "x": 2426.3936,
                        "y": 1468.6066
                    }]
                }
            },
            {
                "valueType": "ALL",
                "inferText": "世界",
                "inferConfidence": 0.9998707,
                "type": "NORMAL",
                "lineBreak": false,
                "boundingPoly": {
                    "vertices": [{
                        "x": 2314.6516,
                        "y": 1604.2931
                    }, {
                        "x": 2314.6516,
                        "y": 1460.625
                    }, {
                        "x": 2430.3843,
                        "y": 1460.625
                    }, {
                        "x": 2430.3843,
                        "y": 1604.2931
                    }]
                }
            }
        ],
        "validationResult": {
            "result": "NO_REQUESTED"
        }
    }]
}

Template OCRのリクエスト例

{
  "version": "V1",
  "requestId": "string",
  "timestamp": 0,
  "lang":"ko",
  "images": [
    {
      "format": "jpg",
      "name": "test 1",
      "url": "https://www.ncloud.com/ocr-test/test.jpg",
      "templateIds":[390]
    }
  ]
}

Template OCRのレスポンス例

{
    "version": "V2",
    "requestId": "string",
    "timestamp": 1584067653255,
    "images": [
        {
            "uid": "1b220cd049de4a7c9e0dc1942d982867",
            "name": "test 1",
            "inferResult": "SUCCESS",
            "message": "SUCCESS",
            "matchedTemplate": {
                "id": 390,
                "name": "template"
            },
            "validationResult": {
                "result": "NO_REQUESTED"
            },
            "title": {
                "name": "title",
                "boundingPoly": {
                    "vertices": [
                        {
                            "x": 453.7125,
                            "y": 54.1125
                        },
                        {
                            "x": 961.5375,
                            "y": 54.1125
                        },
                        {
                            "x": 961.5375,
                            "y": 108.225
                        },
                        {
                            "x": 453.7125,
                            "y": 108.225
                        }
                    ]
                },
                "inferText": "保険金請求書(人保険月)",
                "inferConfidence": 0.94674826
            },
            "fields": [
                {
                    "name": "id",
                    "valueType": "NUMERIC",
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 488.88235,
                                "y": 284.92896
                            },
                            {
                                "x": 550.3732,
                                "y": 284.93716
                            },
                            {
                                "x": 550.39166,
                                "y": 333.93698
                            },
                            {
                                "x": 488.90073,
                                "y": 333.9292
                            }
                        ]
                    },
                    "inferText": "102831",
                    "inferConfidence": 0.9319761,
                    "type": "MULTI_BOX",
                    "subFields": [
                        {
                            "boundingPoly": {
                                "vertices": [
                                    {
                                        "x": 488.88235,
                                        "y": 284.92896
                                    },
                                    {
                                        "x": 550.3732,
                                        "y": 284.93716
                                    },
                                    {
                                        "x": 550.39166,
                                        "y": 333.93698
                                    },
                                    {
                                        "x": 488.90073,
                                        "y": 333.9292
                                    }
                                ]
                            },
                            "inferText": "1",
                            "inferConfidence": 0.9798796
                        },
                        {
                            "boundingPoly": {
                                "vertices": [
                                    {
                                        "x": 551.37305,
                                        "y": 284.9373
                                    },
                                    {
                                        "x": 612.86285,
                                        "y": 284.9455
                                    },
                                    {
                                        "x": 612.88153,
                                        "y": 333.94495
                                    },
                                    {
                                        "x": 551.39154,
                                        "y": 333.9371
                                    }
                                ]
                            },
                            "inferText": "0",
                            "inferConfidence": 0.6391636
                        },
                        {
                            "boundingPoly": {
                                "vertices": [
                                    {
                                        "x": 613.86273,
                                        "y": 284.94562
                                    },
                                    {
                                        "x": 675.3515,
                                        "y": 284.95383
                                    },
                                    {
                                        "x": 675.3702,
                                        "y": 333.95288
                                    },
                                    {
                                        "x": 613.8812,
                                        "y": 333.94504
                                    }
                                ]
                            },
                            "inferText": "2",
                            "inferConfidence": 0.99591047
                        },
                        {
                            "boundingPoly": {
                                "vertices": [
                                    {
                                        "x": 676.3513,
                                        "y": 284.95395
                                    },
                                    {
                                        "x": 737.8392,
                                        "y": 284.9622
                                    },
                                    {
                                        "x": 737.8579,
                                        "y": 333.96082
                                    },
                                    {
                                        "x": 676.37006,
                                        "y": 333.953
                                    }
                                ]
                            },
                            "inferText": "8",
                            "inferConfidence": 0.99782735
                        },
                        {
                            "boundingPoly": {
                                "vertices": [
                                    {
                                        "x": 738.83887,
                                        "y": 284.96228
                                    },
                                    {
                                        "x": 800.3257,
                                        "y": 284.97052
                                    },
                                    {
                                        "x": 800.34454,
                                        "y": 333.96872
                                    },
                                    {
                                        "x": 738.8577,
                                        "y": 333.9609
                                    }
                                ]
                            },
                            "inferText": "3",
                            "inferConfidence": 0.99916536
                        },
                        {
                            "boundingPoly": {
                                "vertices": [
                                    {
                                        "x": 801.3255,
                                        "y": 284.97064
                                    },
                                    {
                                        "x": 862.8112,
                                        "y": 284.97882
                                    },
                                    {
                                        "x": 862.8301,
                                        "y": 333.97662
                                    },
                                    {
                                        "x": 801.3443,
                                        "y": 333.96884
                                    }
                                ]
                            },
                            "inferText": "1",
                            "inferConfidence": 0.9799099
                        }
                    ]
                },
                {
                    "name": "name",
                    "valueType": "ALL",
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 287.2125,
                                "y": 287.2125
                            },
                            {
                                "x": 380.86874,
                                "y": 287.2125
                            },
                            {
                                "x": 380.86874,
                                "y": 328.8375
                            },
                            {
                                "x": 287.2125,
                                "y": 328.8375
                            }
                        ]
                    },
                    "inferText": "David",
                    "inferConfidence": 0.99630755,
                    "type": "NORMAL"
                },
                {
                    "name": "fax-checkbox",
                    "valueType": "ALL",
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 87.08151,
                                "y": 736.90735
                            },
                            {
                                "x": 140.0801,
                                "y": 736.91125
                            },
                            {
                                "x": 140.10016,
                                "y": 791.9156
                            },
                            {
                                "x": 87.101494,
                                "y": 791.9121
                            }
                        ]
                    },
                    "inferText": "",
                    "inferConfidence": 0.99464625,
                    "type": "CHECKBOX",
                    "checked": true
                }
            ]
        }
    ]
}

APIのユースケース

以下は、言語別の CLOVA OCR APIを実装するユースケースです

• Request with multipart/form-data

import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.UUID;

import org.json.JSONArray;
import org.json.JSONObject;

public class OCRGeneralAPIDemo {

	public static void main(String[] args) {
		String apiURL = "YOUR_API_URL";
		String secretKey = "YOUR_SECRET_KEY";
		String imageFile = "YOUR_IMAGE_FILE";

		try {
			URL url = new URL(apiURL);
			HttpURLConnection con = (HttpURLConnection)url.openConnection();
			con.setUseCaches(false);
			con.setDoInput(true);
			con.setDoOutput(true);
			con.setReadTimeout(30000);
			con.setRequestMethod("POST");
			String boundary = "----" + UUID.randomUUID().toString().replaceAll("-", "");
			con.setRequestProperty("Content-Type", "multipart/form-data; boundary=" + boundary);
			con.setRequestProperty("X-OCR-SECRET", secretKey);

			JSONObject json = new JSONObject();
			json.put("version", "V2");
			json.put("requestId", UUID.randomUUID().toString());
			json.put("timestamp", System.currentTimeMillis());
			JSONObject image = new JSONObject();
			image.put("format", "jpg");
			image.put("name", "demo");
			JSONArray images = new JSONArray();
			images.put(image);
			json.put("images", images);
			String postParams = json.toString();

			con.connect();
			DataOutputStream wr = new DataOutputStream(con.getOutputStream());
			long start = System.currentTimeMillis();
			File file = new File(imageFile);
			writeMultiPart(wr, postParams, file, boundary);
			wr.close();

			int responseCode = con.getResponseCode();
			BufferedReader br;
			if (responseCode == 200) {
				br = new BufferedReader(new InputStreamReader(con.getInputStream()));
			} else {
				br = new BufferedReader(new InputStreamReader(con.getErrorStream()));
			}
			String inputLine;
			StringBuffer response = new StringBuffer();
			while ((inputLine = br.readLine()) != null) {
				response.append(inputLine);
			}
			br.close();

			System.out.println(response);
		} catch (Exception e) {
			System.out.println(e);
		}
	}

	private static void writeMultiPart(OutputStream out, String jsonMessage, File file, String boundary) throws
		IOException {
		StringBuilder sb = new StringBuilder();
		sb.append("--").append(boundary).append("\r\n");
		sb.append("Content-Disposition:form-data; name=\"message\"\r\n\r\n");
		sb.append(jsonMessage);
		sb.append("\r\n");

		out.write(sb.toString().getBytes("UTF-8"));
		out.flush();

		if (file != null && file.isFile()) {
			out.write(("--" + boundary + "\r\n").getBytes("UTF-8"));
			StringBuilder fileString = new StringBuilder();
			fileString
				.append("Content-Disposition:form-data; name=\"file\"; filename=");
			fileString.append("\"" + file.getName() + "\"\r\n");
			fileString.append("Content-Type: application/octet-stream\r\n\r\n");
			out.write(fileString.toString().getBytes("UTF-8"));
			out.flush();

			try (FileInputStream fis = new FileInputStream(file)) {
				byte[] buffer = new byte[8192];
				int count;
				while ((count = fis.read(buffer)) != -1) {
					out.write(buffer, 0, count);
				}
				out.write("\r\n".getBytes());
			}

			out.write(("--" + boundary + "--\r\n").getBytes("UTF-8"));
		}
		out.flush();
	}
}

import requests
import uuid
import time
import json

api_url = 'YOUR_API_URL'
secret_key = 'YOUR_SECRET_KEY'
image_file = 'YOUR_IMAGE_FILE'

request_json = {
    'images': [
        {
            'format': 'jpg',
            'name': 'demo'
        }
    ],
    'requestId': str(uuid.uuid4()),
    'version': 'V2',
    'timestamp': int(round(time.time() * 1000))
}

payload = {'message': json.dumps(request_json).encode('UTF-8')}
files = [
  ('file', open(image_file,'rb'))
]
headers = {
  'X-OCR-SECRET': secret_key
}

response = requests.request("POST", api_url, headers=headers, data = payload, files = files)

print(response.text.encode('utf8'))

<?php
  $client_secret = "YOUR_SECRET_KEY";
  $url = "YOUR_API_URL";
  $image_file = "YOUR_IMAGE_FILE";

  $params->version = "V2";
  $params->requestId = uniqid();
  $params->timestamp = time();
  $image->format = "jpg";
  $image->name = "demo";
  $images = array($image);
  $params->images = $images;
  $json = json_encode($params);
  
  $boundary = uniqid();
  $is_post = true;
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_POST, $is_post);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $post_form = array("message" => $json, "file" => new CURLFILE($image_file));
  curl_setopt($ch, CURLOPT_POSTFIELDS, $post_form);
  $headers = array();
  $headers[] = "X-OCR-SECRET: ".$client_secret;
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  $response = curl_exec($ch);
  $err = curl_error($ch);
  $status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close ($ch);

  echo $status_code;
  if($status_code == 200) {
    echo $response;
  } else {
    echo "ERROR: ".$response;
  }
?>

const FormData = require('form-data')
const axios = require('axios')

function requestWithBase64 () {
  axios
    .post(
      '', // APIGW Invoke URL
      {
        images: [
          {
            format: '', // file format
            name: '', // image name
            data: '' // image base64 string(only need part of data). Example: base64String.split(',')[1]
          }
        ],
        requestId: '', // unique string
        timestamp: 0,
        version: 'V2'
      },
      {
        headers: {
          'X-OCR-SECRET': '' // Secret Key 
        }
      }
    )
    .then(res => {
      if (res.status === 200) {
        console.log('requestWithBase64 response:', res.data)
      }
    })
    .catch(e => {
      console.warn('requestWithBase64 error', e.response)
    })
}

function requestWithFile () {
  const file = '' // image file object. Example: fs.createReadStream('./example.png')
  const message = {
    images: [
      {
        format: '', // file format
        name: '' // file name
      }
    ],
    requestId: '', // unique string
    timestamp: 0,
    version: 'V2'
  }
  const formData = new FormData()

  formData.append('file', file)
  formData.append('message', JSON.stringify(message))

  axios
    .post(
      '', // APIGW Invoke URL
      formData,
      {
        headers: {
          'X-OCR-SECRET': '', // Secret Key 
          ...formData.getHeaders()
        }
      }
    )
    .then(res => {
      if (res.status === 200) {
        console.log('requestWithFile response:', res.data)
      }
    })
    .catch(e => {
      console.warn('requestWithFile error', e.response)
    })
}

• Request with application/json

import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.UUID;

import org.json.JSONArray;
import org.json.JSONObject;

public class OCRGeneralAPIDemo {

	public static void main(String[] args) {
		String apiURL = "YOUR_API_URL";
		String secretKey = "YOUR_SECRET_KEY";

		try {
			URL url = new URL(apiURL);
			HttpURLConnection con = (HttpURLConnection)url.openConnection();
			con.setUseCaches(false);
			con.setDoInput(true);
			con.setDoOutput(true);
			con.setRequestMethod("POST");
			con.setRequestProperty("Content-Type", "application/json; charset=utf-8");
			con.setRequestProperty("X-OCR-SECRET", secretKey);

			JSONObject json = new JSONObject();
			json.put("version", "V2");
			json.put("requestId", UUID.randomUUID().toString());
			json.put("timestamp", System.currentTimeMillis());
			JSONObject image = new JSONObject();
			image.put("format", "jpg");
			image.put("url", "https://kr.object.ncloudstorage.com/ocr-ci-test/sample/1.jpg"); // image should be public, otherwise, should use data
			// FileInputStream inputStream = new FileInputStream("YOUR_IMAGE_FILE");
			// byte[] buffer = new byte[inputStream.available()];
			// inputStream.read(buffer);
			// inputStream.close();
			// image.put("data", buffer);
			image.put("name", "demo");
			JSONArray images = new JSONArray();
			images.put(image);
			json.put("images", images);
			String postParams = json.toString();

			DataOutputStream wr = new DataOutputStream(con.getOutputStream());
			wr.writeBytes(postParams);
			wr.flush();
			wr.close();

			int responseCode = con.getResponseCode();
			BufferedReader br;
			if (responseCode == 200) {
				br = new BufferedReader(new InputStreamReader(con.getInputStream()));
			} else {
				br = new BufferedReader(new InputStreamReader(con.getErrorStream()));
			}
			String inputLine;
			StringBuffer response = new StringBuffer();
			while ((inputLine = br.readLine()) != null) {
				response.append(inputLine);
			}
			br.close();

			System.out.println(response);
		} catch (Exception e) {
			System.out.println(e);
		}
	}

}

import requests
import uuid
import time
import base64
import json

api_url = 'YOUR_API_URL'
secret_key = 'YOUR_SECRET_KEY'
image_url = 'YOUR_IMAGE_URL'
# image_file = 'YOUR_IMAGE_FILE'
# with open(image_file,'rb') as f:
#     file_data = f.read()

request_json = {
    'images': [
        {
            'format': 'jpg',
            'name': 'demo',
#             'data': base64.b64encode(file_data).decode()
            'url': image_url
        }
    ],
    'requestId': str(uuid.uuid4()),
    'version': 'V2',
    'timestamp': int(round(time.time() * 1000))
}

payload = json.dumps(request_json).encode('UTF-8')
headers = {
  'X-OCR-SECRET': secret_key,
  'Content-Type': 'application/json'
}

response = requests.request("POST", api_url, headers=headers, data = payload)

print(response.text)

<?php
  $client_secret = "YOUR_SECRET_KEY";
  $url = "YOUR_API_URL";
  $image_url = "YOUR_IMAGE_URL";
  // $image_file = "YOUR_IMAGE_FILE";

  $params->version = "V2";
  $params->requestId = "uuid";
  $params->timestamp = time();
  $image->format = "jpg";
  $image->url = $image_url;
  // $image->data = base64_encode(file_get_contents($image_file));
  $image->name = "demo";
  $images = array($image);
  $params->images = $images;
  $json = json_encode($params);

  $is_post = true;
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_POST, $is_post);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
  $headers = array();
  $headers[] = "X-OCR-SECRET: ".$client_secret;
  $headers[] = "Content-Type:application/json; charset=utf-8";
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  $response = curl_exec($ch);
  $err = curl_error($ch);
  $status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close ($ch);

  echo $status_code;
  if($status_code == 200) {
    echo $response;
  } else {
    echo "ERROR: ".$response;
  }
?>

<%
Function ASPPostJSON()
    Dim objXmlHttp
    Set objXmlHttp = Server.CreateObject("Microsoft.XMLHTTP")
    url = "YOUR_INVOKE_URL"
    secret = "YOUR_SECRET_KEY"
    base64 = """"+ToBase64(getBinaryFile(Server.MapPath("test.jpg")))+""""
    body = "{""images"":[{""format"":""jpg"",""name"":""test 1"",""data"":"+base64+"}],""requestId"":""string"",""timestamp"":0,""version"":""V2"",""lang"":""ko""}"
    objXmlHttp.Open "POST", url, False
    objXmlHttp.SetRequestHeader "Content-Type", "application/json"
    objXmlHttp.SetRequestHeader "X-OCR-SECRET", secret

    objXmlHttp.Send body

    ASPPostJSON = CStr(objXmlHttp.ResponseText)

    Response.write(ASPPostJSON)
    Set objXmlHttp = Nothing

End Function

Function getBinaryFile(strFilePath)
  Dim TypeBinary, oStream

  TypeBinary = 1

  Set oStream = Server.CreateObject("ADODB.Stream")

  oStream.Open

  oStream.Type = TypeBinary
  oStream.LoadFromFile strFilePath

  getBinaryFile = oStream.read

  Set oStream = Nothing

End Function

Function ToBase64(rabyt)

     Dim xml: Set xml = CreateObject("MSXML2.DOMDocument.3.0")
     xml.LoadXml "<root />"
     xml.documentElement.dataType = "bin.base64"
     xml.documentElement.nodeTypedValue = rabyt

     ToBase64 = xml.documentElement.Text

End Function

call ASPPostJSON()
%>

Error code

Error Response Body:

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