Introduction to cloud recognition APIs

Api complete list

Rest API interface protocol and authentication mechanism

CRS API follows standard HTTP REST transmission standards.

Http Header

Authorization:

Http request parameters, divided into two types:

Common parameters (including these in total, different authentication methods are used in different combinations):
- appId
- timestamp (Long integer: milliseconds elapsed since 00:00:00 UTC on January 1, 1970)
- apiKey
- signature (request signature, token authentication method is optional)
CRS API parameters: The API's own parameters

API documentation no longer describes common parameters for authentication

Api key authentication

Token-based authentication

The Http header Authorization contains the token, and the common parameters include:

appId

Signature authentication

Do not use the HTTP header Authorization.

The request parameters contain signature information. All parameters are included in the signature calculation (except for images).

appId
timestamp
apiKey
signature

For detailed algorithms on signature calculation, please refer to the document API Key signature method.

Usage examples and property analysis

API usage example

Here is an example of calling the API to create a target image, helping developers get a glimpse of the CRS API request process, understand the attribute structure of the target image, and the input and output of the interface.

Before creating a target image in a production environment, more validations are required. Please 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 needs to be base64-encoded.

The API documentation provides detailed descriptions of the request parameters. Refer to API —— Create target image to request the API with the 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

The responses follow a unified format. Below is an example:

{
  "statusCode": 119,
  "msg": "Parameter has errors",
  "date": "2022-06-15T09:56:30.000Z",
  "result":  //statusCode is 0, the result field is present; if an error occurs, the result field is empty
}

As shown in the example above, this is the normal structure for returning target image details. A target image includes the following attributes:

Attribute	Description
targetId	The unique ID of the target image
trackingImage	The base64-encoded grayscale image after processing, used for image tracking on the device
name	The name of the target image
size	The size of the image, used for overlaying virtual content in the application
meta	User-associated data, which can be a file, text, or URL, and must be base64-encoded
type	"ImageTarget"
active	Only enabled target images can be recognized; disabled ones will not be recognized
trackableRate	Tracking difficulty score—the smaller, the better
detectableRate	Comprehensive detection difficulty score—the smaller, the better
detectableDistinctiveness	Detection distinctiveness difficulty score—the smaller, the better
detectableFeatureCount	Feature count difficulty score for detection—the smaller, the better
trackableDistinctiveness	Tracking distinctiveness difficulty score—the smaller, the better
trackableFeatureCount	Feature count difficulty score for tracking—the smaller, the better
trackableFeatureDistribution	Feature distribution difficulty score for tracking—the smaller, the better

Error codes

Error code description for cloud recognition APIs

Table of Contents