图片相似度搜索
<p>[TOC]</p>
<h3>简介</h3>
<p>实现输入的图片和图片库中的图片作比较，返回相似度
可创建多个图片库，但检索不能跨库</p>
<h3>接入流程</h3>
<p>1、先把图片通过入库API入图片库，调用入库接口之前先联系我们创建图片库
2、再用要检索的图片去调用检索API，和库里的图片作比较，返回相似度</p>
<h3>接口调用说明</h3>
<h4>请求方式</h4>
<p>所有接口均为：<strong>POST</strong></p>
<h4>请求格式</h4>
<p>所有接口均为：<strong>application/form-data</strong></p>
<h4>请求参数</h4>
<p>请求参数均包括公共参数和业务参数（业务参数见具体接口说明）
接口调用时，均需要把<strong>公共参数</strong>和<strong>业务参数</strong>一并放在<strong>请求参数</strong>中提交</p>
<p><a name="公共请求参数"></a></p>
<h5>公共请求参数</h5>
<table>
<thead>
<tr>
<th>名称</th>
<th>类型</th>
<th>必须</th>
<th><div style="width:420px;">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>appId</td>
<td>String</td>
<td>是</td>
<td>服务商分配的唯一标识</td>
</tr>
<tr>
<td>timestamp</td>
<td>Long</td>
<td>是</td>
<td>当前时间戳（毫秒）</td>
</tr>
<tr>
<td>sign</td>
<td>String</td>
<td>是</td>
<td>签名，详见签名算法说明</td>
</tr>
</tbody>
</table>
<h5>签名算法说明</h5>
<pre><code>sign = sha256(appId + appSecret + timestamp)</code></pre>
<p>用服务商分配的 <strong>appId</strong>、服务商分配的 <strong>appSecret</strong>，当前时间戳（毫秒） <strong>timestamp</strong>，按上述顺序拼接成字符串，再进行 <strong>sha256</strong> 哈希得到。如下：</p>
<pre><code class="language-java">String appId = &quot;xyzxy2121zxyz&quot;；
String timestamp = &quot;1555378976238&quot;；
String appSecret = &quot;efcefcef1121cefcefc1212121&quot;；
String str = appId + appSecret + timestamp；
String sign = sha256(str)；</code></pre>
<h4>返回说明</h4>
<h5>返回字段说明</h5>
<table>
<thead>
<tr>
<th>字段名</th>
<th><div style="width:420px">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>code</td>
<td>返回码，详见：code返回码说明</td>
</tr>
<tr>
<td>msg</td>
<td>code对应的描述</td>
</tr>
<tr>
<td>charge</td>
<td>计费标志 true为计费，false为不计费</td>
</tr>
<tr>
<td>taskNo</td>
<td>本次请求号</td>
</tr>
<tr>
<td>data</td>
<td>返回具体结果，详见具体接口返回体说明</td>
</tr>
</tbody>
</table>
<h5>code返回码说明</h5>
<table>
<thead>
<tr>
<th>code</th>
<th><div style="width:420px;">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>200</td>
<td>成功</td>
</tr>
<tr>
<td>301</td>
<td>入库失败</td>
</tr>
<tr>
<td>400</td>
<td>参数错误</td>
</tr>
<tr>
<td>404</td>
<td>接口地址不正确</td>
</tr>
<tr>
<td>500</td>
<td>系统维护，请稍候再试</td>
</tr>
<tr>
<td>601</td>
<td>接口未开通</td>
</tr>
<tr>
<td>602</td>
<td>账号停用</td>
</tr>
<tr>
<td>604</td>
<td>接口停用</td>
</tr>
<tr>
<td>606</td>
<td>调用超限，请稍候再试</td>
</tr>
<tr>
<td>607</td>
<td>ip不在白名单</td>
</tr>
<tr>
<td>609</td>
<td>请求过于频繁，请稍候再试</td>
</tr>
<tr>
<td>610</td>
<td>请求超时</td>
</tr>
<tr>
<td>999</td>
<td>其他，以实际返回为准</td>
</tr>
</tbody>
</table>
<hr />
<h3>图片入库</h3>
<h4>请求地址</h4>
<p><code>https://api.jumdata.com/image/similarity/input</code></p>
<h4>请求参数</h4>
<table>
<thead>
<tr>
<th>名称</th>
<th>类型</th>
<th>必须</th>
<th><div style="width:420px">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>lib</td>
<td>String</td>
<td>是</td>
<td>图片库标识，可包含：英文，数字，-, _ ，调用图片入库之前先联系我们创建图片库</td>
</tr>
<tr>
<td>url</td>
<td>String</td>
<td>否</td>
<td>入库图片的URL</td>
</tr>
<tr>
<td>base64</td>
<td>String</td>
<td>否</td>
<td>入库图片的base64，需要带前缀，例如：data:image/jpeg;base64,/9jxxxx</td>
</tr>
<tr>
<td>description</td>
<td>String</td>
<td>否</td>
<td>入库图片的描述</td>
</tr>
</tbody>
</table>
<ul>
<li>base64、url 必须提供一个，优先级：url > base64，图片格式支持jpg、JPG、png、PNG、jpeg、JEPG格式</li>
</ul>
<p>公共请求参数请参阅：<a href="#公共请求参数">公共请求参数</a></p>
<h4>入库成功返回样例</h4>
<pre><code class="language-json">{
&quot;code&quot;: 200, // 返回码，详见返回码说明
&quot;msg&quot;: &quot;成功&quot;,// 返回码对应描述
&quot;taskNo&quot;: &quot;043439882226367117195632&quot;,// 本次请求号
&quot;charge&quot;: true, // 计费标志
&quot;data&quot;: {
&quot;mediaId&quot;: &quot;ykLlVn0BePlv8pCOv1dX&quot;, // 入库后的图片id
&quot;url&quot;: &quot;https://img2.jumdata.com/imageSimilarity/xxxxxx.jpeg&quot; //入库图片url
}
}</code></pre>
<h4>入库失败返回样例</h4>
<pre><code class="language-json">{
&quot;code&quot;: 301,
&quot;msg&quot;: &quot;入库失败，请重试&quot;,
&quot;taskNo&quot;: &quot;043439882226367117195632&quot;,
&quot;charge&quot;: false
}</code></pre>
<h4>接口调用失败返回样例</h4>
<pre><code class="language-json">{
&quot;code&quot;: 400,
&quot;msg&quot;: &quot;url不能为空&quot;
}</code></pre>
<h3>图片检索</h3>
<h4>请求地址</h4>
<p><code>https://api.jumdata.com/image/similarity/search</code></p>
<h4>请求参数</h4>
<table>
<thead>
<tr>
<th>名称</th>
<th>类型</th>
<th>必须</th>
<th><div style="width:420px">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>lib</td>
<td>String</td>
<td>是</td>
<td>检索的图片库，可包含：英文，数字，-, _ 。</td>
</tr>
<tr>
<td>url</td>
<td>String</td>
<td>否</td>
<td>检索图片的URL</td>
</tr>
<tr>
<td>base64</td>
<td>String</td>
<td>否</td>
<td>检索图片的base64，需要带前缀，例如：data:image/jpeg;base64,/9jxxxx</td>
</tr>
</tbody>
</table>
<ul>
<li>base64、url 必须提供一个，优先级：url > base64，图片格式支持jpg、JPG、png、PNG、jpeg、JEPG格式</li>
</ul>
<p>公共请求参数请参阅：<a href="#公共请求参数">公共请求参数</a></p>
<h4>检索有结果返回样例</h4>
<pre><code class="language-json">{
&quot;code&quot;: 200,// 返回码，详见返回码说明
&quot;msg&quot;: &quot;成功&quot;,// 返回码对应描述
&quot;taskNo&quot;: &quot;043439882226367117195632&quot;,// 本次请求号
&quot;charge&quot;: true, // 计费标志
&quot;data&quot;: {
&quot;resultCount&quot;: 21,
&quot;results&quot;: [
{
&quot;distance&quot;: 0.12, // 检索图片的相似度，取值范围为[0, 1]，越小越相似
&quot;source&quot;: &quot;https://img.jumdata.com/img/test3.jpg&quot;, //结果图片的URL
&quot;description&quot;:&quot;&quot; // 图片入库时的描述
},
...
]
}
}</code></pre>
<h4>检索无结果返回样例</h4>
<pre><code class="language-json">{
&quot;code&quot;: 200,
&quot;msg&quot;: &quot;成功&quot;,
&quot;taskNo&quot;: &quot;043439882226367117195632&quot;,
&quot;charge&quot;: true,
&quot;data&quot;: {
&quot;resultCount&quot;: 0
}
}</code></pre>
<h4>接口调用失败返回样例</h4>
<pre><code class="language-json">{
&quot;code&quot;: 400,
&quot;msg&quot;: &quot;url不能为空&quot;
}</code></pre>
<h3>查询图片列表</h3>
<h4>请求地址</h4>
<p><code>https://api.jumdata.com/image/similarity/list</code></p>
<h4>请求参数</h4>
<table>
<thead>
<tr>
<th>名称</th>
<th>类型</th>
<th>必须</th>
<th><div style="width:420px">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>libId</td>
<td>String</td>
<td>是</td>
<td>检索的图片库id，请联系我们提供</td>
</tr>
<tr>
<td>pageNo</td>
<td>Integer</td>
<td>否</td>
<td>页码，默认1</td>
</tr>
<tr>
<td>pageSize</td>
<td>Integer</td>
<td>否</td>
<td>每页数量，默认10</td>
</tr>
</tbody>
</table>
<p>公共请求参数请参阅：<a href="#公共请求参数">公共请求参数</a></p>
<h4>检索有结果返回样例</h4>
<pre><code class="language-json">{
&quot;msg&quot;: &quot;成功&quot;,//返回码对应描述
&quot;code&quot;: 200,//返回码，详见返回码说明
&quot;taskNo&quot;: &quot;991824559141136645118738&quot;,//本次请求号
&quot;charge&quot;: true,//计费标志
&quot;data&quot;: {
&quot;pageNo&quot;: 1,//页码
&quot;pageSize&quot;: 10,//每页数量
&quot;totalCount&quot;: 15,// 总数
&quot;result&quot;: [
{
&quot;duration&quot;: 0,//入库时的描述
&quot;name&quot;: &quot;xxxxxx.png&quot;,//图片的名字
&quot;id&quot;: &quot;xxxxx&quot;,//图片的ID
&quot;source&quot;: &quot;https://xxxxxxxx.png&quot;,//结果图片的URL
&quot;status&quot;: &quot;SUCCESS&quot; //图片的入库状态
}
]
}
}</code></pre>
<h4>接口调用失败返回样例</h4>
<pre><code class="language-json">{
&quot;charge&quot;: false,
&quot;code&quot;: 999,
&quot;msg&quot;: &quot;请求的库不存在&quot;,
&quot;taskNo&quot;: &quot;594546003180864495178423&quot;
}</code></pre>
<h3>删除图片</h3>
<h4>请求地址</h4>
<p><code>https://api.jumdata.com/image/similarity/delete</code></p>
<h4>请求参数</h4>
<table>
<thead>
<tr>
<th>名称</th>
<th>类型</th>
<th>必须</th>
<th><div style="width:420px">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>libId</td>
<td>String</td>
<td>是</td>
<td>检索的图片库id，请联系我们提供</td>
</tr>
<tr>
<td>mediaId</td>
<td>String</td>
<td>是</td>
<td>图片id</td>
</tr>
</tbody>
</table>
<p>公共请求参数请参阅：<a href="#公共请求参数">公共请求参数</a></p>
<h4>检索有结果返回样例</h4>
<pre><code class="language-json">{
&quot;msg&quot;: &quot;成功&quot;,//返回码对应描述
&quot;code&quot;: 200,//返回码，详见返回码说明
&quot;taskNo&quot;: &quot;991824559141136645118228&quot;,//本次请求号
&quot;charge&quot;: true,//计费标志
&quot;data&quot;: {
&quot;status&quot;: &quot;success&quot;
}
}</code></pre>
<h4>接口调用失败返回样例</h4>
<pre><code class="language-json">{
&quot;charge&quot;: false,
&quot;code&quot;: 999,
&quot;msg&quot;: &quot;请求的库不存在&quot;,
&quot;taskNo&quot;: &quot;594546003180864495178423&quot;
}</code></pre>