Introduction to cloud recognition APIs

API list

REST API protocol and authentication mechanism

CRS API follows the standard HTTP REST transport standard.

Http Header

Authorization:

Http request parameters are divided into two types:

Common parameters (including all of these; different authentication methods use different combinations):
- appId
- timestamp (Long integer: milliseconds elapsed since 00:00:00 UTC on January 1, 1970)
- apiKey
- signature (request signature, used as an alternative to token authentication)
CRS API parameters: parameters of the API itself

API documentation no longer describes common parameters used for authentication

API Key authentication

Authentication is divided into two types:

Token-based authentication

The Http header Authorization contains the Token. Common parameters include:

appId

Signature authentication

No Http header Authorization is used.

Common parameters contain signature information. All parameters are included in signature calculation, except images.

appId
timestamp
apiKey
signature

For the detailed algorithm and code of signature calculation, refer to API Key signature method.

Usage examples and property parsing

API usage example

This example calls the API to create a target image, helping developers understand the CRS API request process, the property structure of a target image, and API input and output.

More validation is required before creating a target image in production. For details, refer to best practices to create a new target image.

Request example

Add a target image file named test-target.jpg. When creating a target image, the image file must be base64 encoded.

The API documentation provides detailed descriptions of request parameters. Refer to API - Create target image to request the API with a base64-encoded image file.

POST /targets HTTP/1.1
Host:
Date: Mon, 1 Jan 2018 00:00:00 GMT
Content-Type: application/json
{
    "image":"/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMCAgM...",
    "active":"1",
    "name":"easyar",
    "size":"5",
    "meta":"496fbbabc2b38ecs3460a...",
    "type":"ImageTarget",
    "timestamp": 1514736000000,
    "apiKey": "8b485c648c3056e79c2a85ee9b51f9dc",
    "appId": "C:CN1:f9f903c36da8bd64d71d491077bba...",
    "signature": "89985e2420899196db5bdf16b3c2ed0922c0c221"
}

Response example

HTTP/1.1 200 OK
Content-Type: application/json
{
    "statusCode": 0,
    "result": {
        "targetId":"e61db301-e80f-4025-b822-9a00eb48d8d2",
        "trackingImage":"/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMCAgM..."，
        "name": "easyar",
        "size": "5",
        "meta": "496fbbabc2b38ecs3460a...",
        "type": "ImageTarget",
        "modified":1514735000000
        "active":"1"，
        "trackableRate": 0,
        "detectableRate": 0,
        “detectableDistinctiveness”：0,
        "detectableFeatureCount": 0,
        "trackableDistinctiveness": 0,
        "trackableFeatureCount": 0,
        "trackableFeatureDistribution": 0,
        "trackablePatchContrast": 0,
        "trackablePatchAmbiguity": 0
    },
    "timestamp": 1514736000000
}

Response format

Responses use a unified format. The following is an example:

{
  "statusCode": 119,
  "msg": "Parameter has errors",
  "date": "2022-06-15T09:56:30.000Z",
  "result":  //result exists only when statusCode is 0. If an error occurs, the result field is empty
}

As shown in the example above, this is the normal returned target image detail structure. A target image includes the following properties.

Property	Description
targetId	Unique Id of the target image
trackingImage	Base64 encoding of the processed grayscale image, used for image tracking on the device side
name	Target image name
size	Image size, the practical size used for overlaying virtual content in the application
meta	User-associated data, which can be a file, text, or url and needs to be base64 encoded
type	"ImageTarget"
active	Only enabled target images can be recognized. After being disabled, they will not be recognized
trackableRate	Tracking difficulty score. Smaller is better
detectableRate	Overall recognition difficulty score. Smaller is better
detectableDistinctiveness	Recognition distinctiveness difficulty score. Smaller is better
detectableFeatureCount	Recognition feature difficulty score. Smaller is better
trackableDistinctiveness	Tracking distinctiveness difficulty score. Smaller is better
trackableFeatureCount	Tracking feature difficulty score. Smaller is better
trackableFeatureDistribution	Tracking feature distribution difficulty score. Smaller is better

Error codes

Cloud recognition APIs error code description

Table of Contents