雲識別 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