Introduction to cloud recognition APIs

Api list

Rest api interface protocol and authentication mechanism

CRS API follows standard HTTP REST transmission standards.

Http Header

Authorization:

Http request parameters are divided into two types:

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

API documentation no longer describes common parameters for authentication

Api key authentication

Authentication methods are divided into two types:

Token-based authentication

Http header Authorization contains Token, common parameters include:

appId

Signature authentication

Do not use Http header Authorization.

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

appId
timestamp
apiKey
signature

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

Usage examples and property analysis

Api usage example

Here is an example - calling the API interface 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 interface input/output.

Production environment requires more validations before creating target images. Please refer to Best practices to create a new target image.

Request example

Add a new target image file test-target.jpg. When creating a target image, the image file needs to be base64 encoded.

The API documentation will provide detailed descriptions of request parameters. Refer to API - Create target image, base64 encode the image file to request the API.

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 all adopt a unified format. The following is an example:

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

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

Property	Description
targetId	Unique ID of the target image
trackingImage	Base64 encoded processed grayscale image for client-side image tracking
name	Target image name
size	Image size, the size used for overlaying virtual content in applications
meta	User-associated data, which can be files, text or URL, needs base64 encoding
type	"ImageTarget"
active	Only enabled target images can be recognized, disabled ones will not be recognized
trackableRate	Tracking difficulty rating, smaller is better
detectableRate	Comprehensive recognition difficulty rating, smaller is better
detectableDistinctiveness	Recognition distinctiveness difficulty rating, smaller is better
detectableFeatureCount	Recognition feature aspect difficulty rating, smaller is better
trackableDistinctiveness	Tracking distinctiveness difficulty rating, smaller is better
trackableFeatureCount	Tracking feature aspect difficulty rating, smaller is better
trackableFeatureDistribution	Tracking feature distribution difficulty rating, smaller is better

Error codes

Cloud recognition APIs error code explanation

Table of Contents