imageapi API Reference

Image Recognition and Processing APIs let you use Machine Learning to recognize and process images, and also perform useful image modification operations.

Swagger OpenAPI Specification | .NET Framework Client | .NET Core Client | Java Client | Node.JS Client | Python Client | Drupal Client

API Endpoint
https://api.cloudmersive.com
Schemes: https
Version: v1

Authentication

Apikey

API Key Authentication

type
apiKey
name
Apikey
in
header

Artistic

Transform an image into an artistic painting automatically

POST /image/artistic/painting/{style}


Uses machine learning to automatically transform an image into an artistic painting. Due to depth of AI processing, depending on image size this operation can take up to 20 seconds.



style: string
in path

The style of the painting to apply. To start, try "udnie" a painting style. Possible values are: "udnie", "wave", "la_muse", "rain_princess".

imageFile: file
in formData

Image file to perform the operation on. Common file formats such as PNG, JPEG are supported.

Code Example:
200 OK

OK

type
string (byte)
Response Content-Types: application/octet-stream
Response Example (200 OK)
"string (byte)"

Edit

Composite two images together

POST /image/edit/composite/{location}


Composites two input images together; a layered image onto a base image. The first image you input is the base image. The second image (the layered image) will be composited on top of this base image. Supports PNG transparency. To control padding you can include transparent pixels at the border(s) of your layered images as appropriate.



location: string
in path

Location to composite the layered images; possible values are: "center", "top-left", "top-center", "top-right", "center-left", "center-right", "bottom-left", "bottom-center", "bottom-right"

baseImage: file
in formData

Image file to perform the operation on. Common file formats such as PNG, JPEG are supported.

layeredImage: file
in formData

Image to layer on top of the base image.

Code Example:
200 OK

OK

type
object
Response Content-Types: image/png
Response Example (200 OK)
"object"

Draw text onto an image

POST /image/edit/draw/text


Draw one or more pieces of text, with customized visuals, onto an image



undefined

Code Example:
Request Content-Types: application/json, text/json, application/xml, text/xml, application/x-www-form-urlencoded
Request Example
{
  "BaseImageBytes": "string (byte)",
  "BaseImageUrl": "string",
  "TextToDraw": [
    {
      "Text": "string",
      "FontFamilyName": "string",
      "FontSize": "number (double)",
      "Color": "string",
      "X": "number (double)",
      "Y": "number (double)",
      "Width": "number (double)",
      "Height": "number (double)"
    }
  ]
}
200 OK

OK

type
object
Response Content-Types: image/png
Response Example (200 OK)
"object"

Draw rectangle onto an image

POST /image/edit/draw/rectangle


Draw one or more rectangles, with customized visuals, onto an image



Code Example:
Request Content-Types: application/json, text/json, application/xml, text/xml, application/x-www-form-urlencoded
Request Example
{
  "BaseImageBytes": "string (byte)",
  "BaseImageUrl": "string",
  "RectanglesToDraw": [
    {
      "BorderColor": "string",
      "BorderWidth": "number (double)",
      "FillColor": "string",
      "X": "number (double)",
      "Y": "number (double)",
      "Width": "number (double)",
      "Height": "number (double)"
    }
  ]
}
200 OK

OK

type
object
Response Content-Types: image/png
Response Example (200 OK)
"object"

Face

Find faces in an image

POST /image/face/locate


Locate the positions of all faces in an image



imageFile: file
in formData

Image file to perform the operation on. Common file formats such as PNG, JPEG are supported.

Code Example:

OK

Response Content-Types: application/json, text/json, application/xml, text/xml
Response Example (200 OK)
{
  "ErrorDetails": "string",
  "Successful": "boolean",
  "Faces": [
    {
      "LeftX": "integer (int32)",
      "TopY": "integer (int32)",
      "RightX": "integer (int32)",
      "BottomY": "integer (int32)"
    }
  ],
  "FaceCount": "integer (int32)"
}

Crop image to face (square)

POST /image/face/crop/first


Crop an image to the face (rectangular crop). If there is more than one face present, choose the first one.



imageFile: file
in formData

Image file to perform the operation on. Common file formats such as PNG, JPEG are supported.

Code Example:
200 OK

OK

type
string (byte)
Response Content-Types: application/octet-stream
Response Example (200 OK)
"string (byte)"

Crop image to face (round)

POST /image/face/crop/first/round


Crop an image to the face (circular/round crop). If there is more than one face present, choose the first one.



imageFile: file
in formData

Image file to perform the operation on. Common file formats such as PNG, JPEG are supported.

Code Example:
200 OK

OK

type
string (byte)
Response Content-Types: application/octet-stream
Response Example (200 OK)
"string (byte)"

Detect the age of people in an image

POST /image/face/detect-age


Identify the age, position, and size of human faces in an image, along with a recognition confidence level. People in the image do NOT need to be facing the camera; they can be facing away, edge-on, etc.



imageFile: file
in formData

Image file to perform the operation on. Common file formats such as PNG, JPEG are supported.

Code Example:

OK

Response Content-Types: application/json, text/json, application/xml, text/xml
Response Example (200 OK)
{
  "Successful": "boolean",
  "PeopleWithAge": [
    {
      "FaceLocation": {
        "LeftX": "integer (int32)",
        "TopY": "integer (int32)",
        "RightX": "integer (int32)",
        "BottomY": "integer (int32)"
      },
      "AgeClassificationConfidence": "number (double)",
      "AgeClass": "string"
    }
  ],
  "PeopleIdentified": "integer (int32)"
}

Nsfw

Not safe for work (NSFW) racy content classification

POST /image/nsfw/classify


Classify an image into Not Safe For Work (NSFW)/Porn/Racy content and Safe Content.



imageFile: file
in formData

Image file to perform the operation on. Common file formats such as PNG, JPEG are supported.

Code Example:
200 OK

OK

Response Content-Types: application/json, text/json, application/xml, text/xml
Response Example (200 OK)
{
  "Successful": "boolean",
  "Score": "number (double)",
  "ClassificationOutcome": "string"
}

Recognize

Describe an image in natural language

POST /image/recognize/describe


Generate an English language text description of the image as a sentence.



imageFile: file
in formData

Image file to perform the operation on. Common file formats such as PNG, JPEG are supported.

Code Example:
Response Content-Types: application/json, text/json, application/xml, text/xml
Response Example (200 OK)
{
  "Successful": "boolean",
  "Highconfidence": "boolean",
  "BestOutcome": {
    "ConfidenceScore": "number (double)",
    "Description": "string"
  },
  "RunnerUpOutcome": {
    "ConfidenceScore": "number (double)",
    "Description": "string"
  }
}

Detect objects, including types and locations, in an image

POST /image/recognize/detect-objects


Identify the position, size and description of objects in an image, along with a recognition confidence level. Detects both human people and objects in an image.



imageFile: file
in formData

Image file to perform the operation on. Common file formats such as PNG, JPEG are supported.

Code Example:
Response Content-Types: application/json, text/json, application/xml, text/xml
Response Example (200 OK)
{
  "Successful": "boolean",
  "Objects": [
    {
      "ObjectClassName": "string",
      "Height": "integer (int32)",
      "Width": "integer (int32)",
      "Score": "number (double)",
      "X": "integer (int32)",
      "Y": "integer (int32)"
    }
  ],
  "ObjectCount": "integer (int32)"
}

Detect people, including locations, in an image

POST /image/recognize/detect-people


Identify the position, and size of human people in an image, along with a recognition confidence level. People in the image do NOT need to be facing the camera; they can be facing away, edge-on, etc.



imageFile: file
in formData

Image file to perform the operation on. Common file formats such as PNG, JPEG are supported.

Code Example:
Response Content-Types: application/json, text/json, application/xml, text/xml
Response Example (200 OK)
{
  "Successful": "boolean",
  "Objects": [
    {
      "ObjectClassName": "string",
      "Height": "integer (int32)",
      "Width": "integer (int32)",
      "Score": "number (double)",
      "X": "integer (int32)",
      "Y": "integer (int32)"
    }
  ],
  "ObjectCount": "integer (int32)"
}

Detect vehicle license plates in an image

POST /image/recognize/detect-vehicle-license-plates


Identify the position, and size, and content of vehicle license plates in an image. License plates should be within 15-20 degrees on-axis to the camera.



imageFile: file
in formData

Image file to perform the operation on. Common file formats such as PNG, JPEG are supported.

Code Example:
Response Content-Types: application/json, text/json, application/xml, text/xml
Response Example (200 OK)
{
  "Successful": "boolean",
  "DetectedLicensePlates": [
    {
      "LocationX": "integer (int32)",
      "LocationY": "integer (int32)",
      "Width": "integer (int32)",
      "Height": "integer (int32)",
      "LicensePlateText_BestMatch": "string",
      "LicensePlateText_RunnerUp": "string",
      "LicensePlateRecognitionConfidenceLevel": "number (double)"
    }
  ],
  "DetectedLicensePlateCount": "integer (int32)"
}

Detect and unskew a photo of a document

POST /image/recognize/detect-document/unskew


Detect and unskew a photo of a document (e.g. taken on a cell phone) into a perfectly square image. Great for document scanning applications; once unskewed, this image is perfect for converting to PDF using the Convert API or optical character recognition using the OCR API.



imageFile: file
in formData

Image file to perform the operation on. Common file formats such as PNG, JPEG are supported.

PostProcessingEffect: string
in header

Optional, post-processing effects to apply to the email, default is None. Possible values are None and BlackAndWhite (force the image into a black and white view to aid in OCR operations).

Code Example:
200 OK

OK

type
string (byte)
Response Content-Types: application/json, text/json, application/xml, text/xml
Response Example (200 OK)
"string (byte)"

Resize

Resize an image with parameters

POST /image/resize/preserveAspectRatio/{maxWidth}/{maxHeight}


Resize an image to a maximum width and maximum height, while preserving the image's original aspect ratio



maxWidth: integer (int32)
in path

Maximum width of the output image - final image will be as large as possible while less than or equial to this width

maxHeight: integer (int32)
in path

Maximum height of the output image - final image will be as large as possible while less than or equial to this height

imageFile: file
in formData

Image file to perform the operation on. Common file formats such as PNG, JPEG are supported.

Code Example:
200 OK

OK

type
string (byte)
Response Content-Types: image/png
Response Example (200 OK)
"string (byte)"

Schema Definitions

DrawTextRequest: object

Request to draw one or more pieces of text onto an image

BaseImageBytes: string (byte)

Image to draw text on, in bytes. You can also use the BaseImageUrl instead to supply image input as a URL

BaseImageUrl: string

Image to draw text on, as an HTTP or HTTPS fully-qualified URL

TextToDraw: DrawTextInstance

One or more pieces of text to draw onto the image

DrawTextInstance
Example
{
  "BaseImageBytes": "string (byte)",
  "BaseImageUrl": "string",
  "TextToDraw": [
    {
      "Text": "string",
      "FontFamilyName": "string",
      "FontSize": "number (double)",
      "Color": "string",
      "X": "number (double)",
      "Y": "number (double)",
      "Width": "number (double)",
      "Height": "number (double)"
    }
  ]
}

DrawTextInstance: object

Text instance to draw on an image

Text: string

Text string to draw

FontFamilyName: string

Font Family to use. Leave blank to default to "Arial".

FontSize: number (double)

Font size to use.

Color: string

Color to use - can be a hex value (with #) or HTML common color name

X: number (double)

Pixel location of the left edge of the text location

Y: number (double)

Pixel location of the top edge of the text location

Width: number (double)

Width in pixels of the text box to draw the text in; text will wrap inside this box

Height: number (double)

Height in pixels of the text box to draw the text in; text will wrap inside this box

Example
{
  "Text": "string",
  "FontFamilyName": "string",
  "FontSize": "number (double)",
  "Color": "string",
  "X": "number (double)",
  "Y": "number (double)",
  "Width": "number (double)",
  "Height": "number (double)"
}

DrawRectangleRequest: object

Request to draw one or more rectangles on a base image

BaseImageBytes: string (byte)

Image to draw rectangles on, in bytes. You can also use the BaseImageUrl instead to supply image input as a URL

BaseImageUrl: string

Image to draw rectangles on, as an HTTP or HTTPS fully-qualified URL

RectanglesToDraw: DrawRectangleInstance

Rectangles to draw on the image. Rectangles are drawn in index order.

DrawRectangleInstance
Example
{
  "BaseImageBytes": "string (byte)",
  "BaseImageUrl": "string",
  "RectanglesToDraw": [
    {
      "BorderColor": "string",
      "BorderWidth": "number (double)",
      "FillColor": "string",
      "X": "number (double)",
      "Y": "number (double)",
      "Width": "number (double)",
      "Height": "number (double)"
    }
  ]
}

DrawRectangleInstance: object

Rectangle instance to draw on an image

BorderColor: string

Border Color to use - can be a hex value (with #) or HTML common color name. Transparent colors are supported.

BorderWidth: number (double)

Width in pixels of the border. Pass in 0 to draw a rectangle with no border

FillColor: string

Fill Color to use - can be a hex value (with #) or HTML common color name. Transparent colors are supported. Leave blank to not fill the rectangle.

X: number (double)

Pixel location of the left edge of the rectangle location

Y: number (double)

Pixel location of the top edge of the rectangle location

Width: number (double)

Width in pixels of the rectangle

Height: number (double)

Height in pixels of the rectangle

Example
{
  "BorderColor": "string",
  "BorderWidth": "number (double)",
  "FillColor": "string",
  "X": "number (double)",
  "Y": "number (double)",
  "Width": "number (double)",
  "Height": "number (double)"
}

FaceLocateResponse: object

Results of locating faces in an image

ErrorDetails: string
Successful: boolean

True if the operation was successful, false otherwise

Faces: Face

Array of faces found in the image

Face
FaceCount: integer (int32)

Number of faces found in the image

Example
{
  "ErrorDetails": "string",
  "Successful": "boolean",
  "Faces": [
    {
      "LeftX": "integer (int32)",
      "TopY": "integer (int32)",
      "RightX": "integer (int32)",
      "BottomY": "integer (int32)"
    }
  ],
  "FaceCount": "integer (int32)"
}

Face: object

Location of one face in an image

LeftX: integer (int32)

X coordinate of the left side of the face

TopY: integer (int32)

Y coordinate of the top side of the face

RightX: integer (int32)

X coordinate of the right side of the face

BottomY: integer (int32)

Y coordinate of the bottom side of the face

Example
{
  "LeftX": "integer (int32)",
  "TopY": "integer (int32)",
  "RightX": "integer (int32)",
  "BottomY": "integer (int32)"
}

AgeDetectionResult: object

Result from classifying the Age of people in an image

Successful: boolean

True if the operation was successful, false otherwise

PeopleWithAge: PersonWithAge

People in the image annotated with age information

PersonWithAge
PeopleIdentified: integer (int32)

Number of people identified in the image with an age

Example
{
  "Successful": "boolean",
  "PeopleWithAge": [
    {
      "FaceLocation": {
        "LeftX": "integer (int32)",
        "TopY": "integer (int32)",
        "RightX": "integer (int32)",
        "BottomY": "integer (int32)"
      },
      "AgeClassificationConfidence": "number (double)",
      "AgeClass": "string"
    }
  ],
  "PeopleIdentified": "integer (int32)"
}

PersonWithAge: object

A person identified in an image age classification operation

FaceLocation: Face

Location and other information about the person's face corresponding to this age classification

AgeClassificationConfidence: number (double)

Confidence level of age classification; possible values are between 0.0 and 1.0; higher is better, with values > 0.50 being high confidence results

AgeClass: string

The person's age range classification result in years; possible values are "0-2", "4-6", "8-13", "15-20", "25-32", "38-43", "48-53", "60+"

Example
{
  "FaceLocation": {
    "LeftX": "integer (int32)",
    "TopY": "integer (int32)",
    "RightX": "integer (int32)",
    "BottomY": "integer (int32)"
  },
  "AgeClassificationConfidence": "number (double)",
  "AgeClass": "string"
}

NsfwResult: object

Result of an NSFW classification

Successful: boolean

True if the classification was successfully run, false otherwise

Score: number (double)

Score between 0.0 and 1.0. Scores of 0.0-0.2 represent high probability safe content, while scores 0.8-1.0 represent high probability unsafe content. Content between 0.2 and 0.8 is of increasing raciness.

ClassificationOutcome: string

Classification result into four categories: SafeContent_HighProbability, UnsafeContent_HighProbability, RacyContent, SafeContent_ModerateProbability

Example
{
  "Successful": "boolean",
  "Score": "number (double)",
  "ClassificationOutcome": "string"
}

ImageDescriptionResponse: object

Result of recognizing an image

Successful: boolean

Was the image processed successfully?

Highconfidence: boolean

Is the resulting best outcome recognition a high confidence outcome?

BestOutcome: RecognitionOutcome

The best Machine Learning outcome

RunnerUpOutcome: RecognitionOutcome

Best backup ("runner up") Machine Learning outcome

Example
{
  "Successful": "boolean",
  "Highconfidence": "boolean",
  "BestOutcome": {
    "ConfidenceScore": "number (double)",
    "Description": "string"
  },
  "RunnerUpOutcome": {
    "ConfidenceScore": "number (double)",
    "Description": "string"
  }
}

RecognitionOutcome: object

Specific recognition outcome

ConfidenceScore: number (double)

Scores closer to 1 are better than scores closer to 0

Description: string

English language description of the image

Example
{
  "ConfidenceScore": "number (double)",
  "Description": "string"
}

ObjectDetectionResult: object

Result of detecting objects in an image

Successful: boolean

Was the image processed successfully?

Objects: DetectedObject

Array of objects detected in the scene

DetectedObject
ObjectCount: integer (int32)

Number of objects detected in the scene

Example
{
  "Successful": "boolean",
  "Objects": [
    {
      "ObjectClassName": "string",
      "Height": "integer (int32)",
      "Width": "integer (int32)",
      "Score": "number (double)",
      "X": "integer (int32)",
      "Y": "integer (int32)"
    }
  ],
  "ObjectCount": "integer (int32)"
}

DetectedObject: object

Single object instance, and associated details, detected in an image

ObjectClassName: string

Class of the object. Example values are "person", "car", "dining table", etc.

Height: integer (int32)

Height, in pixels, of the object

Width: integer (int32)

Width, in pixels, of the object

Score: number (double)

Confidence score of detected object; possible values are between 0.0 and 1.0; values closer to 1.0 are higher confidence

X: integer (int32)

X location, in pixels, of the left side location of the object, with the right side being X + Width

Y: integer (int32)

Y location, in pixels, of the top side location of the object, with the bottom side being Y + Height

Example
{
  "ObjectClassName": "string",
  "Height": "integer (int32)",
  "Width": "integer (int32)",
  "Score": "number (double)",
  "X": "integer (int32)",
  "Y": "integer (int32)"
}

VehicleLicensePlateDetectionResult: object

Result of detecting vehicle license plates in an image

Successful: boolean

Was the image processed successfully?

DetectedLicensePlates: DetectedLicensePlate

License plates found in the image

DetectedLicensePlate
DetectedLicensePlateCount: integer (int32)

The number of license plates detected in the image

Example
{
  "Successful": "boolean",
  "DetectedLicensePlates": [
    {
      "LocationX": "integer (int32)",
      "LocationY": "integer (int32)",
      "Width": "integer (int32)",
      "Height": "integer (int32)",
      "LicensePlateText_BestMatch": "string",
      "LicensePlateText_RunnerUp": "string",
      "LicensePlateRecognitionConfidenceLevel": "number (double)"
    }
  ],
  "DetectedLicensePlateCount": "integer (int32)"
}

DetectedLicensePlate: object

License plate found in the image

LocationX: integer (int32)
LocationY: integer (int32)
Width: integer (int32)
Height: integer (int32)
LicensePlateText_BestMatch: string

Text from the license plate, highest-confidence result

LicensePlateText_RunnerUp: string

Alternate text from the license plate, based on second-highest-confidence result

LicensePlateRecognitionConfidenceLevel: number (double)

Confidence score on a range of 0.0 - 1.0 of the accuracy of the detected license plate, with higher scores being better; values about 0.75 are high confidence

Example
{
  "LocationX": "integer (int32)",
  "LocationY": "integer (int32)",
  "Width": "integer (int32)",
  "Height": "integer (int32)",
  "LicensePlateText_BestMatch": "string",
  "LicensePlateText_RunnerUp": "string",
  "LicensePlateRecognitionConfidenceLevel": "number (double)"
}