Table of Contents

搜索识别目标| POST /v2/search

搜索图像目标，以图搜图识别接口。

Action

POST /v2/search

认证

需要

Http Header

Content-Type : multipart/form-data

HTTP Header: Authorization (当采用 API Key Token 方式认证)

请求参数

Field Type Required Description
image Multipart Yes 图像内容的 base64 编码字符串，支持 JPG 和 PNG 格式图像。
notracking String No "false" 表示返回 trackingImage 跟踪图像。"true" 表示仅返回检测到的 targetId 属性，不返回跟踪图像。WebAR 默认建议带上降低请求延迟。

Token 认证的请求示例

curl -X POST -H "Authorization:xxx"  --form "image=@trackingImage.jpg;type=image/jpg"  
          https://<your-domain>-cn1.crs.easyar.com:8443/v2/search

签名认证请求示例

curl -X POST --form "image=@trackingImage;type=image/jpg" 
              --form apiKey=YOUR-APIKEY  --form appId=YOUR-APPID 
              --form timestamp=1514736000000 
              --form signature=xxx 
          https://<your-domain>-cn1.crs.easyar.com:8443/v2/search
重要事项
  • 一定要使用 Client-end-URL 才是识别入口，https 是 8443 端口
  • http header 设置 Connection: Keep-Alive 优化重复连接开销

返回字段

字段 描述
statusCode 状态码 0 表示认证正确，更多参考 状态码
result 错误消息，或者目标图信息
timestamp 响应返回时的服务器端时间。使用 Unix 时间戳格式，以毫秒为单位
result.targetId 目标图的唯一 ID
result.trackingImage 跟踪图像的 base64 编码字符串
result.name 目标名称
result.size 识别图宽度（单位 cm ）。识别图的高度将由系统根据您上传的图片自动计算。识别图的大小和叠加虚拟内容的大小对应
result.meta base64 编码的附加信息，例如将 json 字符串 base64 编码后生成的字符串
result.type 固定为 ImageTarget
result.active "1" 启用，"0" 停用

主要返回码

Response HTTPCODE Status Result
OK 200 0 result: { imageBody }
NO_RESULT 404 17 result: { message: "No result: there is no matching." }
NO_TARGET 500 18 result: { message: "Target not found: there is a matching but no target, please report this issue: IMAGE-UUID" }
TIMEOUT 408 19 result: { message: "Request timeout." }
OUT_OF_LIMIT 402 21 result: { message: "You have exceeded the limit of daily scanning." }
OUT_OF_QPS 200 21 result: { message: "Exceed your QPS limitation." }
RPC_ERROR 500 20 result: { message: "Error retrieving results." }
OTHER_ERROR 501 30 result: { message: "Other error occur: details" }

错误码

参见 状态码以及错误码大全

请求示例

POST /search/ HTTP/1.1
Host:
Date: Mon, 1 Jan 2018 00:00:00 GMT
Content-Type: application/json
{
    "image":"/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMCAgM...",
    "timestamp": 1514736000000,
    "appKey": "test_app_key",
    "signature": "89985e2420899196db5bdf16b3c2ed0922c0c221"
}

返回示例

  • 如果命中识别到，返回结构如图：

    HTTP/1.1 200 OK
    Content-Type: application/json
    {
        "statusCode": 0,
        "result": {
          "target": {
            "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
    }
  • 如果没有匹配的目标图，返回示例如下：

    HTTP/1.1 404 NOT FOUND
    Content-Type: application/json
    {
      "statusCode": 17,
      "result": {
        "message": "No result: there is no matching."
      }
    }