分析中 已回复 待规划 {{opt.name}}

分析中 已回复 待规划

Java 获取淘宝图搜接口（拍立淘）开发文档

淘宝图片搜索 API（拍立淘）支持通过图片或图片 URL 检索淘宝/天猫同款商品，广泛应用于电商比价、内容带货、运营监控等场景。本文将系统性地介绍 Java 环境下的完整接入方案，涵盖官方淘宝开放平台 API 和阿里云图像搜索服务两种主流路径。

一、接入路径对比

二、路径一：淘宝开放平台 TOP 接口

2.1 接入准备

1. 访问 淘宝开放平台
2. 完成实名认证（个人或企业）
3. 创建应用，获取 App Key 和 App Secret
4. 在应用权限管理中申请 taobao.item.search.img 或 taobao.image.search 接口权限
5. 等待审核通过（通常 1-3 个工作日）

2.2 图片要求

2.3 核心请求参数

2.4 MD5 签名生成算法

淘宝开放平台采用 MD5 签名，规则如下：

sign = MD5(AppSecret + key1value1 + key2value2 + ... + AppSecret).toUpperCase()

关键规则：

• 参数按 key 的 ASCII 升序 排列
• 参数值为空（null 或空字符串）的参数不参与签名
• sign 和 sign_method 本身不参与签名
• 参数值需进行 URL 编码（UTF-8）

2.5 完整 Java 实现代码点击测试

import okhttp3.*;
import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import com.alibaba.fastjson.JSONArray;

import java.io.*;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.*;
import java.util.concurrent.TimeUnit;

/**
 * 淘宝开放平台拍立淘图搜接口 Java 客户端
 * 支持图片 URL 和本地图片 Base64 两种方式
 */
public class TaobaoImageSearchClient {
    
    // 淘宝开放平台网关地址
    private static final String GATEWAY_URL = "https://eco.taobao.com/router/rest";
    
    private final String appKey;
    private final String appSecret;
    private final OkHttpClient httpClient;
    
    public TaobaoImageSearchClient(String appKey, String appSecret) {
        this.appKey = appKey;
        this.appSecret = appSecret;
        this.httpClient = new OkHttpClient.Builder()
            .connectTimeout(10, TimeUnit.SECONDS)
            .readTimeout(30, TimeUnit.SECONDS)
            .writeTimeout(10, TimeUnit.SECONDS)
            .build();
    }
    
    /**
     * 生成淘宝开放平台 MD5 签名
     */
    public String generateSign(Map<String, String> params) {
        // 1. 过滤空值并按键 ASCII 升序排序
        List<Map.Entry<String, String>> sortedEntries = params.entrySet().stream()
            .filter(e -> e.getValue() != null && !e.getValue().isEmpty())
            .filter(e -> !e.getKey().equals("sign") && !e.getKey().equals("sign_method"))
            .sorted(Map.Entry.comparingByKey())
            .toList();
        
        // 2. 拼接签名字符串：AppSecret + key1value1 + key2value2 + ... + AppSecret
        StringBuilder signBuilder = new StringBuilder(appSecret);
        for (Map.Entry<String, String> entry : sortedEntries) {
            signBuilder.append(entry.getKey()).append(entry.getValue());
        }
        signBuilder.append(appSecret);
        
        // 3. MD5 加密并转大写
        return md5Encrypt(signBuilder.toString()).toUpperCase();
    }
    
    /**
     * MD5 加密工具
     */
    private String md5Encrypt(String input) {
        try {
            MessageDigest md = MessageDigest.getInstance("MD5");
            byte[] digest = md.digest(input.getBytes(StandardCharsets.UTF_8));
            StringBuilder sb = new StringBuilder();
            for (byte b : digest) {
                String hex = Integer.toHexString(b & 0xFF);
                if (hex.length() == 1) sb.append("0");
                sb.append(hex);
            }
            return sb.toString();
        } catch (NoSuchAlgorithmException e) {
            throw new RuntimeException("MD5 加密失败", e);
        }
    }
    
    /**
     * 通过图片 URL 搜索商品
     */
    public ImageSearchResult searchByImageUrl(String imageUrl, String categoryId, int pageNo, int pageSize) throws IOException {
        Map<String, String> params = new HashMap<>();
        params.put("method", "taobao.item.search.img");
        params.put("app_key", appKey);
        params.put("timestamp", LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")));
        params.put("format", "json");
        params.put("v", "2.0");
        params.put("sign_method", "md5");
        params.put("img_url", imageUrl);
        
        if (categoryId != null && !categoryId.isEmpty()) {
            params.put("cat", categoryId);
        }
        params.put("page_no", String.valueOf(pageNo));
        params.put("page_size", String.valueOf(pageSize));
        
        return executeRequest(params);
    }
    
    /**
     * 通过本地图片文件搜索商品（Base64 编码）
     */
    public ImageSearchResult searchByLocalImage(String imagePath, String categoryId, int pageNo, int pageSize) throws IOException {
        // 读取图片并转 Base64
        File file = new File(imagePath);
        byte[] imageBytes = new FileInputStream(file).readAllBytes();
        String base64Image = Base64.getEncoder().encodeToString(imageBytes);
        
        // 去掉 Base64 前缀（如 data:image/jpeg;base64,）
        if (base64Image.contains(",")) {
            base64Image = base64Image.split(",")[1];
        }
        
        Map<String, String> params = new HashMap<>();
        params.put("method", "taobao.item.search.img");
        params.put("app_key", appKey);
        params.put("timestamp", LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")));
        params.put("format", "json");
        params.put("v", "2.0");
        params.put("sign_method", "md5");
        params.put("img", base64Image);
        
        if (categoryId != null && !categoryId.isEmpty()) {
            params.put("cat", categoryId);
        }
        params.put("page_no", String.valueOf(pageNo));
        params.put("page_size", String.valueOf(pageSize));
        
        return executeRequest(params);
    }
    
    /**
     * 执行 HTTP 请求并解析响应
     */
    private ImageSearchResult executeRequest(Map<String, String> params) throws IOException {
        // 生成签名
        params.put("sign", generateSign(params));
        
        // 构建表单请求体
        FormBody.Builder formBuilder = new FormBody.Builder();
        for (Map.Entry<String, String> entry : params.entrySet()) {
            formBuilder.add(entry.getKey(), entry.getValue());
        }
        
        Request request = new Request.Builder()
            .url(GATEWAY_URL)
            .post(formBuilder.build())
            .addHeader("Content-Type", "application/x-www-form-urlencoded")
            .build();
        
        try (Response response = httpClient.newCall(request).execute()) {
            if (!response.isSuccessful()) {
                throw new IOException("HTTP 请求失败: " + response.code());
            }
            
            String responseBody = response.body().string();
            return parseResponse(responseBody);
        }
    }
    
    /**
     * 解析 JSON 响应
     */
    private ImageSearchResult parseResponse(String jsonResponse) {
        JSONObject root = JSON.parseObject(jsonResponse);
        
        // 检查错误
        if (root.containsKey("error_response")) {
            JSONObject error = root.getJSONObject("error_response");
            return ImageSearchResult.error(
                error.getString("code"),
                error.getString("msg"),
                error.getString("sub_code"),
                error.getString("sub_msg")
            );
        }
        
        // 解析正常响应
        JSONObject searchResponse = root.getJSONObject("item_search_img_response");
        if (searchResponse == null) {
            searchResponse = root.getJSONObject("image_search_response");
        }
        
        if (searchResponse == null) {
            return ImageSearchResult.error("UNKNOWN", "无法解析响应结构", null, null);
        }
        
        ImageSearchResult result = new ImageSearchResult();
        result.setSuccess(true);
        result.setTotalResults(searchResponse.getIntValue("total_results"));
        
        JSONArray items = searchResponse.getJSONObject("items").getJSONArray("item");
        List<<SearchItem> itemList = new ArrayList<>();
        
        for (int i = 0; i < items.size(); i++) {
            JSONObject item = items.getJSONObject(i);
            SearchItem searchItem = new SearchItem();
            searchItem.setItemId(item.getString("num_iid"));
            searchItem.setTitle(item.getString("title"));
            searchItem.setPrice(item.getString("price"));
            searchItem.setPicUrl(item.getString("pic_url"));
            searchItem.setDetailUrl(item.getString("detail_url"));
            searchItem.setSales(item.getIntValue("sales"));
            searchItem.setMatchRate(item.getDoubleValue("match_rate"));
            searchItem.setSimilarityScore(item.getDoubleValue("similarity_score"));
            searchItem.setSellerNick(item.getString("seller_nick"));
            searchItem.setArea(item.getString("area"));
            itemList.add(searchItem);
        }
        
        result.setItems(itemList);
        return result;
    }
    
    // ==================== 数据模型 ====================
    
    public static class ImageSearchResult {
        private boolean success;
        private String errorCode;
        private String errorMsg;
        private String subCode;
        private String subMsg;
        private int totalResults;
        private List<<SearchItem> items;
        
        public static ImageSearchResult error(String code, String msg, String subCode, String subMsg) {
            ImageSearchResult r = new ImageSearchResult();
            r.success = false;
            r.errorCode = code;
            r.errorMsg = msg;
            r.subCode = subCode;
            r.subMsg = subMsg;
            return r;
        }
        
        // Getters & Setters
        public boolean isSuccess() { return success; }
        public void setSuccess(boolean success) { this.success = success; }
        public String getErrorCode() { return errorCode; }
        public void setErrorCode(String errorCode) { this.errorCode = errorCode; }
        public String getErrorMsg() { return errorMsg; }
        public void setErrorMsg(String errorMsg) { this.errorMsg = errorMsg; }
        public int getTotalResults() { return totalResults; }
        public void setTotalResults(int totalResults) { this.totalResults = totalResults; }
        public List<<SearchItem> getItems() { return items; }
        public void setItems(List<<SearchItem> items) { this.items = items; }
    }
    
    public static class SearchItem {
        private String itemId;
        private String title;
        private String price;
        private String picUrl;
        private String detailUrl;
        private int sales;
        private double matchRate;
        private double similarityScore;
        private String sellerNick;
        private String area;
        
        // Getters & Setters
        public String getItemId() { return itemId; }
        public void setItemId(String itemId) { this.itemId = itemId; }
        public String getTitle() { return title; }
        public void setTitle(String title) { this.title = title; }
        public String getPrice() { return price; }
        public void setPrice(String price) { this.price = price; }
        public String getPicUrl() { return picUrl; }
        public void setPicUrl(String picUrl) { this.picUrl = picUrl; }
        public String getDetailUrl() { return detailUrl; }
        public void setDetailUrl(String detailUrl) { this.detailUrl = detailUrl; }
        public int getSales() { return sales; }
        public void setSales(int sales) { this.sales = sales; }
        public double getMatchRate() { return matchRate; }
        public void setMatchRate(double matchRate) { this.matchRate = matchRate; }
        public double getSimilarityScore() { return similarityScore; }
        public void setSimilarityScore(double similarityScore) { this.similarityScore = similarityScore; }
        public String getSellerNick() { return sellerNick; }
        public void setSellerNick(String sellerNick) { this.sellerNick = sellerNick; }
        public String getArea() { return area; }
        public void setArea(String area) { this.area = area; }
    }
    
    // ==================== 使用示例 ====================
    
    public static void main(String[] args) {
        TaobaoImageSearchClient client = new TaobaoImageSearchClient(
            "your_app_key",
            "your_app_secret"
        );
        
        try {
            // 方式1：通过图片 URL 搜索
            ImageSearchResult result = client.searchByImageUrl(
                "https://example.com/product.jpg",
                "50010788",  // 女装类目
                1,           // 第1页
                20           // 每页20条
            );
            
            if (result.isSuccess()) {
                System.out.println("搜索成功，共找到 " + result.getTotalResults() + " 个商品");
                for (SearchItem item : result.getItems()) {
                    System.out.println("商品: " + item.getTitle());
                    System.out.println("价格: ¥" + item.getPrice());
                    System.out.println("销量: " + item.getSales());
                    System.out.println("相似度: " + item.getMatchRate());
                    System.out.println("链接: " + item.getDetailUrl());
                    System.out.println("---");
                }
            } else {
                System.err.println("搜索失败: " + result.getErrorCode() + " - " + result.getErrorMsg());
            }
            
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

2.6 Maven 依赖

xml

<<dependencies>
    <!-- OkHttp HTTP 客户端 -->
    <dependency>
        <groupId>com.squareup.okhttp3</groupId>
        <artifactId>okhttp</artifactId>
        <version>4.12.0</version>
    </dependency>
    
    <!-- FastJSON JSON 解析 -->
    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>fastjson</artifactId>
        <version>1.2.83</version>
    </dependency>
</dependencies>

三、路径二：阿里云图像搜索服务（淘宝联盟版）

阿里云提供的图像搜索服务封装了更高级的图像识别能力，支持淘宝联盟商品搜索，适合高并发、推广场景。

3.1 准备工作

1. 注册阿里云账号并创建 AccessKey ID 和 AccessKey Secret
2. 开通阿里云图像搜索服务
3. 获取淘宝联盟 PID（推广位 ID，格式如 mm_xxx_xxx_xxx）

3.2 Maven 依赖

xml

<<dependencies>
    <!-- 阿里云图像搜索 SDK -->
    <dependency>
        <groupId>com.aliyun</groupId>
        <artifactId>imagesearch20210501</artifactId>
        <version>1.2.2</version>
    </dependency>
    
    <!-- 阿里云核心 SDK -->
    <dependency>
        <groupId>com.aliyun</groupId>
        <artifactId>aliyun-java-sdk-core</artifactId>
        <version>4.6.0</version>
    </dependency>
    
    <!-- FastJSON -->
    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>fastjson</artifactId>
        <version>1.2.83_noneautotype</version>
    </dependency>
</dependencies>

3.3 本地图片搜索（SearchByPic）

java

import com.alibaba.fastjson.JSON;
import com.aliyun.imagesearch20210501.Client;
import com.aliyun.imagesearch20210501.models.*;
import com.aliyun.tea.TeaException;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;

import java.io.FileInputStream;
import java.io.InputStream;
import java.util.List;

/**
 * 阿里云图像搜索 - 淘宝联盟版本地图片搜索
 */
public class AliyunImageSearchClient {
    
    public static void main(String[] args) throws Exception {
        // 配置认证信息（建议从环境变量读取）
        Config authConfig = new Config();
        authConfig.accessKeyId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
        authConfig.accessKeySecret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
        authConfig.endpoint = "imagesearch.cn-shanghai.aliyuncs.com";
        authConfig.regionId = "cn-shanghai";
        
        Client client = new Client(authConfig);
        
        // 构建请求
        SearchByPicAdvanceRequest request = new SearchByPicAdvanceRequest();
        
        // 读取本地图片文件
        InputStream inputStream = new FileInputStream("/path/to/your/image.jpg");
        request.picContentObject = inputStream;
        
        // 必填：淘宝联盟 PID
        request.pid = "mm_123456_789012_345678";
        
        // 可选：需要返回的字段列表
        request.fields = "Title,PicUrl,ReservePrice,ZkFinalPrice,UserType," +
            "Provcity,Nick,SellerId,Volume,CategoryName," +
            "CommissionRate,CouponInfo,CouponShareUrl,Url,ShopTitle";
        
        // 可选：图片类目 ID，限定搜索范围
        // request.categoryId = 88888888L;
        
        // 可选：是否进行主体识别，默认 true
        // request.crop = false;
        
        // 可选：主体区域，格式为 x1,x2,y1,y2
        // request.region = "518,1524,398,1632";
        
        // 可选：返回结果起始位置，范围 0-499，默认 0
        request.start = 0;
        
        // 可选：返回结果数目，范围 1-20，默认 10
        request.num = 10;
        
        // 可选：渠道 ID（淘宝联盟渠道区分）
        // request.relationId = 1145L;
        
        // 运行时选项
        RuntimeOptions runtimeOptions = new RuntimeOptions();
        runtimeOptions.autoretry = true;  // 自动重试
        
        try {
            SearchByPicResponse response = client.searchByPicAdvance(request, runtimeOptions);
            
            System.out.println("Request ID: " + response.getBody().getRequestId());
            System.out.println("Code: " + response.getBody().getCode());
            System.out.println("Message: " + response.getBody().getMessage());
            
            // 解析商品列表
            List<<SearchByPicResponseBody.SearchByPicResponseBodyDataAuctions> auctions = 
                response.getBody().getData().getAuctions();
            
            for (SearchByPicResponseBody.SearchByPicResponseBodyDataAuctions auction : auctions) {
                System.out.println("---------------");
                System.out.println("排序得分: " + auction.getRankScore());
                
                SearchByPicResponseBody.SearchByPicResponseBodyDataAuctionsResult result = 
                    auction.getResult();
                System.out.println("商品信息: " + result.toMap());
            }
            
            // 解析图片主体信息
            SearchByPicResponseBody.SearchByPicResponseBodyPicInfo picInfo = 
                response.getBody().getPicInfo();
            
            if (picInfo != null && picInfo.getMainRegion() != null) {
                System.out.println("---------------");
                System.out.println("主体区域: " + picInfo.getMainRegion().getRegion());
                
                // 主体区域预测类目
                for (SearchByPicResponseBody.SearchByPicResponseBodyPicInfoMainRegionMultiCategoryId categoryId : 
                     picInfo.getMainRegion().getMultiCategoryId()) {
                    System.out.println("预测类目: " + categoryId.getCategoryId() + 
                                     ", 置信度: " + categoryId.getScore());
                }
            }
            
            // 多主体识别
            if (picInfo != null && picInfo.getMultiRegion() != null) {
                for (SearchByPicResponseBody.SearchByPicResponseBodyPicInfoMultiRegion region : 
                     picInfo.getMultiRegion()) {
                    System.out.println("多主体区域: " + region.getRegion());
                }
            }
            
        } catch (TeaException e) {
            System.err.println("阿里云错误码: " + e.getCode());
            System.err.println("错误数据: " + e.getData());
            System.err.println("错误信息: " + e.getMessage());
            e.printStackTrace();
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            inputStream.close();
        }
    }
}

3.4 图片 URL 搜索（SearchByUrl）

java

import com.aliyun.imagesearch20210501.Client;
import com.aliyun.imagesearch20210501.models.*;
import com.aliyun.tea.TeaException;
import com.aliyun.teaopenapi.models.Config;

import java.util.List;

/**
 * 阿里云图像搜索 - 通过图片 URL 搜索
 */
public class AliyunImageSearchByUrl {
    
    public static void main(String[] args) throws Exception {
        Config authConfig = new Config();
        authConfig.accessKeyId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
        authConfig.accessKeySecret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
        authConfig.endpoint = "imagesearch.cn-shanghai.aliyuncs.com";
        authConfig.regionId = "cn-shanghai";
        
        Client client = new Client(authConfig);
        
        SearchByUrlRequest request = new SearchByUrlRequest();
        request.pid = "mm_123456_789012_345678";
        request.picUrl = "https://img.alicdn.com/tfs/TB1.jpg";
        
        // 可选参数
        // request.fields = "Title,PicUrl,ReservePrice,ZkFinalPrice";
        // request.categoryId = 8L;
        // request.crop = false;
        // request.region = "88,266,59,517";
        // request.start = 1;
        // request.num = 20;
        // request.relationId = 1145L;
        
        try {
            SearchByUrlResponse response = client.searchByUrl(request);
            
            System.out.println("Request ID: " + response.getBody().getRequestId());
            List<<SearchByUrlResponseBody.SearchByUrlResponseBodyDataAuctions> auctions = 
                response.getBody().getData().getAuctions();
            
            for (SearchByUrlResponseBody.SearchByUrlResponseBodyDataAuctions auction : auctions) {
                SearchByUrlResponseBody.SearchByUrlResponseBodyDataAuctionsResult result = 
                    auction.getResult();
                System.out.println("商品: " + result.getTitle());
                System.out.println("价格: " + result.getZkFinalPrice());
                System.out.println("链接: " + result.getUrl());
                System.out.println("---");
            }
            
        } catch (TeaException e) {
            System.err.println("错误: " + e.getMessage());
        }
    }
}

3.5 通过商品 ID 查询详情（GetProductInfoByIds）

java

import com.alibaba.fastjson.JSON;
import com.aliyun.imagesearch20210501.Client;
import com.aliyun.imagesearch20210501.models.GetProductInfoByIdsRequest;
import com.aliyun.imagesearch20210501.models.GetProductInfoByIdsResponse;
import com.aliyun.tea.TeaException;
import com.aliyun.teaopenapi.models.Config;

/**
 * 根据商品 ID 批量查询商品详情
 */
public class AliyunProductInfoQuery {
    
    public static void main(String[] args) throws Exception {
        Config authConfig = new Config();
        authConfig.accessKeyId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
        authConfig.accessKeySecret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
        authConfig.endpoint = "imagesearch.cn-shanghai.aliyuncs.com";
        authConfig.regionId = "cn-shanghai";
        
        Client client = new Client(authConfig);
        
        GetProductInfoByIdsRequest request = new GetProductInfoByIdsRequest();
        request.pid = "mm_123456_789012_345678";
        
        // 商品 ID 串，用逗号分割，最多 40 个
        request.setItemIds("12345678901,12345678902,12345678903");
        
        // 需要返回的字段
        request.fields = "Title,PicUrl,ReservePrice,ZkFinalPrice,CommissionRate,Volume";
        
        try {
            GetProductInfoByIdsResponse response = client.getProductInfoByIds(request);
            System.out.println(JSON.toJSONString(response.getBody(), true));
            
        } catch (TeaException e) {
            System.out.println("错误信息: " + e.getMessage());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

四、返回结果字段详解

4.1 淘宝开放平台返回结构

JSON

{
  "item_search_img_response": {
    "items": {
      "item": [
        {
          "num_iid": "123456789012",
          "title": "2026夏季新款连衣裙",
          "price": "199.00",
          "pic_url": "https://img.alicdn.com/xxx.jpg",
          "detail_url": "https://item.taobao.com/item.htm?id=123456789012",
          "match_rate": 0.95,
          "similarity_score": 92.5,
          "sales": 2560,
          "seller_nick": "xx旗舰店",
          "area": "浙江杭州"
        }
      ]
    },
    "total_results": 100
  }
}

4.2 阿里云图像搜索返回字段

表格

五、常见问题与解决方案

六、最佳实践建议

1. 安全存储密钥：App Secret 和 AccessKey Secret 严禁硬编码，使用环境变量或密钥管理服务
2. 图片预处理：上传前压缩图片至 2MB 以内，提高响应速度
3. 缓存策略：搜索结果缓存 5-15 分钟，减少重复调用
4. 异常降级：接口失败时提供文本搜索兜底方案
5. 日志记录：记录请求参数、响应耗时、错误码，便于排查问题
6. 限流保护：实现令牌桶或滑动窗口限流，避免触发平台限流
7. 合规注意：仅用于合法业务场景，遵守淘宝开放平台使用协议

七、扩展应用场景

基于淘宝图搜接口可构建以下应用：

• 同款比价系统：上传商品图，自动搜索全网最低价
• 内容电商工具：图文/视频内容自动匹配商品链接
• 竞品监控：定期搜索竞品图片，监控价格和销量变化
• 智能选品：通过图片分析市场趋势，辅助采购决策
• 防伪溯源：验证商品图片真伪，识别山寨商品