processRemoteImage Method

Avatar

Nikolai Kromm

  • Edited

This method is for testing purposes only. Its parameters, functionality and availability are not guaranteed in future.

This method is used to create a processing task for an image which is located on a remote server. It is designed for use with large images (size over 30 MB), which would take too long to upload in the request body. Instead, you need to upload your image to any image-hosting website and pass the link as a parameter. The image size is still limited: you cannot process images that are larger than 200 MB.

Customize the following request URL according to your application processing location:

[GET] http(s)://<PROCESSING_LOCATION_ID>.ocrsdk.com/processRemoteImage

If the task is created successfully, the server response will contain the task ID, which can be used to monitor the task status and receive the result URL when it is completed.

After creating the task the server attempts to download the image from the specified URL. If any of the following errors occur, the task receives the ProcessingFailed status:

  • no response from the server hosting the image;
  • incorrect URL;
  • the image size exceeds 200 MB;
  • the image format is not supported. See the list of supported input formats.

Important! As of March 2018, Cloud OCR SDK requires that the remote image hosting support TLS 1.0 to 1.2 security protocol. If the remote hosting supports SSL only, the image will not be downloaded and the task will receive the ProcessingFailed status.

This method allows you to specify up to three file formats for the result, in which case the server response for the completed task will contain several result URLs.

If there is not enough money on your account, the task will be created, but will be suspended with NotEnoughCredits status. You can pass this task for processing using the processDocument method after you have topped up your account.

The task will not be created, if you exceed the limit of uploaded images.

Parameters

Parameter Is required Default value Description
source Yes No The URL address of the image which must be recognized.
language No "English" Specifies recognition language of the document. This parameter can contain several language names separated with commas, for example "English,French,German". See the list of available recognition languages.
profile No "documentConversion" Specifies a profile with predefined processing settings. It can be one of the following:
  • documentConversion
  • documentArchiving
  • textExtraction
  • barcodeRecognition
textType No "normal" Specifies the type of the text on a page. This parameter may also contain several text types separated with commas, for example "normal,matrix". The following values can be used:
  • normal
  • typewriter
  • matrix
  • index
  • handprinted
  • ocrA
  • ocrB
  • e13b
  • cmc7
  • gothic
imageSource No "auto"

Specifies the source of the image. It can be either a scanned image, or a photograph created with a digital camera. Special preprocessing operations can be performed with the image depending on the selected source. For example, the system can automatically correct distorted text lines, poor focus and lighting on photos.

The value of this parameter can be one of the following:

  • auto
    The image source is detected automatically.
  • photo
  • scanner
correctOrientation No "true" Specifies whether the orientation of the image should be automatically detected and corrected. It can have one of the following values:
  • true
    The page orientation is automatically detected, and if it differs from normal the image is rotated.
  • false
    The page orientation detection and correction is not performed.
correctSkew No "true" Specifies whether the skew of the image should be automatically detected and corrected. It can have either true or false value.
readBarcodes No "true" for xml export format and "false" in other cases Specifies whether barcodes must be detected on the image, recognized and exported to the result file. It can have either true or false value.
exportFormat No "rtf" Specifies the export format. This parameter can contain up to three export formats, separated with commas (example: "pdfa,txt,xml"). The available formats are:
  • txt
  • rtf
  • docx
  • xlsx
  • pptx
  • pdfSearchable
    The entire image is saved as a picture, the recognized text is put under it.
  • pdfTextAndImages
    The recognized text is saved as text, and the pictures are saved as pictures.
  • pdfa
    The file is saved in the PDF/A-1b format, with the entire image saved as a picture, and recognized text put under it.
  • xml
  • alto

If xml export format is selected, barcodes are recognized on the image and saved to output XML no matter which profile is used for recognition.

Please note that setting multiple export formats does not affect the cost of task processing.
xml:writeRecognitionVariants No "false" Specifies whether the variants of characters recognition should be written to an output file in XML format. This parameter can be used only if the exportFormat parameter is set to xml. The parameter can have one of the following values:
  • true
  • false
pdf:writeTags No "auto"

Specifies whether the result must be written as tagged PDF. It can have one of the following values:

  • auto
    Automatic selection: the tags are written into the output PDF file if it must comply with PDF/A-1a standard, and are not written otherwise.
  • write
  • dontWrite
description No "" Contains the description of the processing task. Cannot contain more than 255 characters.
pdfPassword No "" Contains a password for accessing password-protected images in PDF format.

Status codes and response format

General status codes and response format of the method are described in HTTP Status Codes and Response Formats.

The following status codes can be returned when this method is called:

Code Description
200 Successful method call.
450 Incorrect parameters have been passed. One of the following errors occurred:
  • Image file URL has not been specified.
  • Incorrect recognition language has been specified.
  • Incorrect processing profile has been specified.
  • Incorrect export format has been specified.
  • Task description length exceeds 255 characters.
  • Exceeded quota to add images. This error is returned if the number of images you have uploaded exceeds the number of images you can process with the credits available on your account plus some threshold. You can resolve this issue by topping up your account or by removing the tasks which have been submitted but have not been processed.
550 An internal program error occurred while processing the image.

Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.