云识别 APIs 简介

API 大全

REST API 接口协议与鉴权机制

CRS API 遵循标准 HTTP REST 传输标准。

Http Header

Authorization: <填入 APIKey 中获取的 Token>

Http 请求参数，分为两种类型：

公共参数（总共包括这些，认证方式不同搭配不同使用）：
- appId
- timestamp（Long 长整型：1970年1月1日00:00:00 UTC 以来经过的毫秒数）
- apiKey
- signature（请求签名，token 方式认证二选一）
CRS API 参数：API 自己的参数

API 文档不再描述认证用的公共参数

API Key 认证

基于 Token 认证

Http 头部 Authorization 包含 Token，公共参数包括：

appId

签名认证

不用 Http 头部 Authorization。

请求参数含有 signature 签名信息。所有参数纳入签名计算（图像除外）。

appId
timestamp
apiKey
signature

有关签名计算的详细算法，请参考文档 API Key 签名方法。

使用示例与属性解析

API 使用示例

这里通过一个示例 —— 调用 API 接口创建一个目标图像，帮助开发者一窥 CRS API 请求过程，了解目标图的属性结构，以及接口输入输出。

生产环境创建目标图前需要验证更多，具体请参考最佳实践来新建一个目标图像。

请求示例

新增一个 test-target.jpg 的目标图像文件。创建目标图时，图像文件需经过 base64 编码。

API 文档中会对请求参数做详细说明。参考 API —— 创建目标图像，图像文件 base64 编码请求 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"
}

返回示例

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
}

响应格式

响应均采用统一格式。以下是一个示例：

{
  "statusCode": 119,
  "msg": "Parameter has errors",
  "date": "2022-06-15T09:56:30.000Z",
  "result":  //statusCode 为 0 的情况才有 result，如果发生错误，结果字段为空
}

如上面示例所示，这是正常返回目标图详情结构，一个目标图包括以下属性

属性	描述
targetId	目标图的唯一 Id
trackingImage	处理后灰度图的 base64 编码，用于设备端图像跟踪
name	目标图名称
size	图片尺寸大小，应用中叠加虚拟内容实用的尺寸
meta	用户关联数据，可以文件可以文本或者 url，需要 base64 编码
type	"ImageTarget"
active	启用的目标图才能识别到，停用以后将不被识别到
trackableRate	跟踪难度评分，越小越好
detectableRate	识别综合难度评分，越小越好
detectableDistinctiveness	识别可区分难度评分，越小越好
detectableFeatureCount	识别特征方面难度评分，越小越好
trackableDistinctiveness	跟踪可区分难度评分，越小越好
trackableFeatureCount	跟踪特征方面难度评分，越小越好
trackableFeatureDistribution	跟踪特征分布难度评分，越小越好

错误码

云识别 APIs 错误码说明

Table of Contents