本文介绍了如何使用阿里云视觉智能开放平台的Java SDK,具体包括SDK的安装方法以及SDK代码示例。

说明

阿里云视觉智能开放平台各类目视觉AI能力SDK接入、接口使用或问题咨询等,请通过钉钉群(23109592)加入阿里云视觉智能开放平台咨询群联系我们。

该版本是升级版SDK只支持Java8及以上,如不满足SDK版本所需环境要求请升级Java版本。如必须使用Java8以下版本请使用旧版Java(不推荐)

您可以根据使用不同服务,下载对应服务的SDK包。具体服务的SDK包名称如下:

AI类目

SDK包名称

SDK链接

Github链接

生成专区

aigen20240111

Aliyun Java SDK Aigen

aigen-20240111

人脸人体

facebody20191230

Aliyun Java SDK Facebody

facebody-20191230

文字识别

ocr20191230

Aliyun Java SDK OCR

ocr-20191230

商品理解

goodstech20191230

Aliyun Java SDK Goodstech

goodstech-20191230

内容审核

imageaudit20191230

Aliyun Java SDK Imageaudit

imageaudit-20191230

图像识别

imagerecog20190930

Aliyun Java SDK Imagerecog

imagerecog-20190930

图像生产

imageenhan20190930

Aliyun Java SDK Imageenhan

imageenhan-20190930

分割抠图

imageseg20191230

Aliyun Java SDK Imageseg

imageseg-20191230

目标检测

objectdet20191230

Aliyun Java SDK Objectdet

objectdet-20191230

视觉搜索

imgsearch20200320

Aliyun Java SDK Imgsearch

imgsearch-20200320

图像分析处理

imageprocess20200320

Aliyun Java SDK Imageprocess

imageprocess-20200320

视频理解

videorecog20200320

Aliyun Java SDK Videorecog

videorecog-20200320

视频生产

videoenhan20200320

Aliyun Java SDK Videoenhan

videoenhan-20200320

视频分割

videoseg20200320

Aliyun Java SDK Videoseg

videoseg-20200320

异步任务管理

viapi20230117

Aliyun Java SDK Viapi

viapi-20230117

自学习

viapi_regen20211119

Aliyun Java SDK ViapiRegen

viapi-regen-20211119

人脸核身服务端20200910专用版本

facebody20200910

Aliyun Java SDK Facebody

facebody-20200910

准备工作

  • 在使用阿里云SDK前,确保您已经注册阿里云账号并生成访问密钥(AccessKey)。具体操作,请参见创建AccessKey

  • 已安装视觉智能API相关服务Java SDK。

查看SDK版本

pom.xml文件中version的值以SDK获取地址中的最新版本为准。您可以通过https://mvnrepository.com/artifact/com.aliyun/SDK包名称查看不同服务SDK的版本。

例如,通过https://mvnrepository.com/artifact/com.aliyun/facebody20191230可以查看facebody20191230的版本。

安装方法1:使用Maven(推荐)

如果您使用Maven管理Java项目,可以通过在pom.xml文件中添加Maven依赖安装Java SDK。例如您需要人脸人体类目下的能力,您只需引入facebody20191230

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>facebody20191230</artifactId>
    <version>${aliyun.facebody.version}</version>
</dependency>

安装方法2:在集成开发环境(IDE)中导入JAR文件

无论您使用Eclipse还是IntelliJ作为集成开发环境,都可以通过导入JAR文件的方式安装Java SDK。

  • Eclipse安装

    1. 将下载的xxx.jar及其依赖文件复制到您的项目文件夹中。

    2. 在Eclipse中打开您的项目,右键单击该项目,选择Properties

    3. 在弹出的对话框中,单击Java Build PathLibrariesAdd JARs添加下载的JAR文件。

    4. 单击Apply and Close

  • IntelliJ安装

    1. 将下载的xxx.jar及其依赖文件复制到您的项目文件夹中。

    2. 在IntelliJ中打开您的项目,右键单击xxx.jar,选择Add as Library

    3. 单击Apply,然后单击OK

配置环境变量

配置环境变量ALIBABA_CLOUD_ACCESS_KEY_IDALIBABA_CLOUD_ACCESS_KEY_SECRET

重要
  • 阿里云账号AccessKey拥有所有API的访问权限,建议您使用RAM用户进行API访问或日常运维,具体操作,请参见创建RAM用户

  • 请不要将AccessKey ID和AccessKey Secret保存到工程代码里,否则可能导致AccessKey泄露,威胁您账号下所有资源的安全。

  • Linux和macOS系统配置方法

    1. 在IntelliJ IDEA中打开终端Terminal。

    2. 执行以下命令,配置环境变量。

      <access_key_id>需替换为您RAM用户的AccessKey ID,<access_key_secret>替换为您RAM用户的AccessKey Secret。如果后续需要进行更多权限相关的配置,具体操作请参见使用RAM Policy控制访问权限

      export ALIBABA_CLOUD_ACCESS_KEY_ID=<access_key_id> 
      export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<access_key_secret>
  • Windows系统配置方法

    新建环境变量文件,添加环境变量ALIBABA_CLOUD_ACCESS_KEY_IDALIBABA_CLOUD_ACCESS_KEY_SECRET,并写入已准备好的AccessKey ID和AccessKey Secret。然后重启Windows系统。本操作以Windows 10为例进行说明。

    1. 打开文件资源管理器,在此电脑上右键单击属性。

    2. 在右侧导航栏,单击高级系统配置

    3. 系统属性对话框的高级页签下,单击环境变量

    4. 环境变量对话框中,单击新建(W)image.png

    5. 在弹出的新建系统变量对话框中,添加环境变量ALIBABA_CLOUD_ACCESS_KEY_IDALIBABA_CLOUD_ACCESS_KEY_SECRET,并写入已准备好的AccessKey ID和AccessKey Secret。

    6. 重启Windows系统,使配置生效。

SDK示例

本文以RecognizeBankCard为例。

文件在上海地域OSS

说明

每个类目的访问域名与对应地域的开通详情,请参见访问域名

package com.aliyun.sample;

// 1、这里只是以ocr下的RecognizeBankCard能力为例,其他能力请引入相应类目的包和相关类。包名可参考本文档上方的SDK包名称,能力名可参考对应API文档中的Action参数。例如您想使用通用分割,其文档为https://help.aliyun.com/document_detail/151960.html,可以知道该能力属于分割抠图类目,能力名称为SegmentCommonImage,那么您需要将代码中ocr20191230改为imageseg20191230,将RecognizeBankCard改为SegmentCommonImage。
import com.aliyun.ocr20191230.models.RecognizeBankCardResponse;
import com.aliyun.tea.*;

public class Sample {

    /**
    * 使用AK&SK初始化账号Client
    * @param accessKeyId
    * @param accessKeySecret
    * @return Client
    * @throws Exception
    */
    // 这里只是以ocr为例,其他能力请使用相应类目的包下面的Client类
    public static com.aliyun.ocr20191230.Client createClient(String accessKeyId, String accessKeySecret) throws Exception {
        /*
          初始化配置对象com.aliyun.teaopenapi.models.Config
          Config对象存放AccessKeyId、AccessKeySecret、endpoint等配置
         */
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
            .setAccessKeyId(accessKeyId)
            .setAccessKeySecret(accessKeySecret);
        
        // 2、访问的域名。注意:这个地方需要求改为相应类目的域名,参考:https://help.aliyun.com/document_detail/143103.html
        config.endpoint = "ocr.cn-shanghai.aliyuncs.com";
        
        // 3、这里只是以ocr为例,其他能力请使用相应类目的包下面的Client类
        return new com.aliyun.ocr20191230.Client(config);
    }

    public static void main(String[] args) throws Exception {
      
        // 4、"YOUR_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_SECRET" 的生成请参考https://help.aliyun.com/document_detail/175144.html
        // 如果您用的是RAM用户(子账号)AccessKey,还需要为RAM用户(子账号)授予权限AliyunVIAPIFullAccess,请参考https://help.aliyun.com/document_detail/145025.html
        // 这里只是以ocr为例,其他能力请使用相应类目的包下面的Client类

        // 创建AccessKey ID和AccessKey Secret,请参考https://help.aliyun.com/document_detail/175144.html。
        // 如果您使用的是RAM用户的AccessKey,还需要为RAM用户授予权限AliyunVIAPIFullAccess,请参考https://help.aliyun.com/document_detail/145025.html。
        // 从环境变量读取配置的AccessKey ID和AccessKey Secret。运行代码示例前必须先配置环境变量。
        com.aliyun.ocr20191230.Client client = Sample.createClient(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
      
        // 5、这里只是以ocr下的RecognizeBankCard为例,其他能力请使用相应类目的包和类,具体入参设置需要参考具体能力的文档
        com.aliyun.ocr20191230.models.RecognizeBankCardRequest recognizeBankCardRequest = new com.aliyun.ocr20191230.models.RecognizeBankCardRequest()
            .setImageURL("http://viapi-test.oss-cn-shanghai.aliyuncs.com/viapi-3.0domepic/ocr/RecognizeBankCard/yhk1.jpg");
        com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
        try {
          
            // 6、这里只是以ocr下的RecognizeBankCard为例,其他能力请使用相应类目的包和类,注意,recognizeBankCardWithOptions方法名也需要改成对应能力的方法名。方法名是根据能力名称按照一定规范形成的,如能力名称为SegmentCommonImage,对应方法名应该为segmentCommonImageWithOptions。
            RecognizeBankCardResponse resp = client.recognizeBankCardWithOptions(recognizeBankCardRequest, runtime);
            // 获取整体结果。部分能力会输出url链接,通过toJSONString转换后可能有编码问题,但是通过单个字段获取是没问题的。
            System.out.println(com.aliyun.teautil.Common.toJSONString(TeaModel.buildMap(resp)));
            // 获取单个字段,这里只是一个例子,具体能力下的字段需要看具体能力的文档
            System.out.println(resp.getBody().getData().getCardNumber());
        } catch (com.aliyun.tea.TeaException teaException) {
            // 获取整体报错信息
            System.out.println(com.aliyun.teautil.Common.toJSONString(teaException));
            // 获取单个字段
            System.out.println(teaException.getCode());
        }
    }
}

需要修改的地方均在上述代码注释中标明,总结如下:

  1. 引入包的时候,需要引入相应类目的包和相关类。包名可参考上文SDK包名称,能力名称可参考对应API文档中的Action参数。

    例如,您想使用通用分割能力,通过通用分割API文档可知该能力属于分割抠图类目(imageseg20191230),能力名称为SegmentCommonImage,您需要将代码中的ocr20191230改为imageseg20191230,将RecognizeBankCard改为SegmentCommonImage。

  2. 访问的域名一定要修改为相应类目的域名,如果域名类目不匹配会报错InvalidAction.NotFound。关于域名详情,请参见访问域名

  3. Client类需要使用相应类目的包下的Client类。

  4. Request和Response需要使用相应类目的包和类。

  5. 调用Client的方法时,方法名需要改成对应能力的方法名。方法名是根据能力名称按照一定规范形成的。例如,能力名称为SegmentCommonImage,对应方法名应为segmentCommonImageWithOptions。

文件在本地或可访问的URL

重要

与文件在同地域的区别在于需要使用xxxAdvanceRequest,文件是以Stream形式通过ImageURLObject参数传入。

package com.aliyun.sample;

// 1、这里只是以ocr下的RecognizeBankCard能力为例,其他能力请引入相应类目的包和相关类。包名可参考本文档上方的SDK包名称,能力名可参考对应API文档中的Action参数。例如您想使用通用分割,其文档为https://help.aliyun.com/document_detail/151960.html,可以知道该能力属于分割抠图类目,能力名称为SegmentCommonImage,那么您需要将代码中ocr20191230改为imageseg20191230,将RecognizeBankCard改为SegmentCommonImage。
import com.aliyun.ocr20191230.models.RecognizeBankCardResponse;
import com.aliyun.tea.*;

import java.io.File;
import java.io.FileInputStream;
import java.io.InputStream;
import java.net.URL;
import java.net.URLConnection;

public class Sample {

    /**
    * 使用AK&SK初始化账号Client
    * @param accessKeyId
    * @param accessKeySecret
    * @return Client
    * @throws Exception
    */
    // 这里只是以ocr为例,其他能力请使用相应类目的包下面的Client类
    public static com.aliyun.ocr20191230.Client createClient(String accessKeyId, String accessKeySecret) throws Exception {
        /*
          初始化配置对象com.aliyun.teaopenapi.models.Config
          Config对象存放 AccessKeyId、AccessKeySecret、endpoint等配置
         */
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
            .setAccessKeyId(accessKeyId)
            .setAccessKeySecret(accessKeySecret);
      
        // 2、访问的域名。注意:这个地方需要求改为相应类目的域名,参考:https://help.aliyun.com/document_detail/143103.html
        config.endpoint = "ocr.cn-shanghai.aliyuncs.com";
      
        // 3、这里只是以ocr为例,其他能力请使用相应类目的包下面的Client类
        return new com.aliyun.ocr20191230.Client(config);
    }

    public static void main(String[] args) throws Exception {
      
        // 4、"YOUR_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_SECRET" 的生成请参考https://help.aliyun.com/document_detail/175144.html
        // 如果您是用的子账号AccessKey,还需要为子账号授予权限AliyunVIAPIFullAccess,请参考https://help.aliyun.com/document_detail/145025.html
        // 这里只是以ocr为例,其他能力请使用相应类目的包下面的Client类
        
        // 创建AccessKey ID和AccessKey Secret,请参考https://help.aliyun.com/document_detail/175144.html。
        // 如果您使用的是RAM用户的AccessKey,还需要为RAM用户授予权限AliyunVIAPIFullAccess,请参考https://help.aliyun.com/document_detail/145025.html。
        // 从环境变量读取配置的AccessKey ID和AccessKey Secret。运行代码示例前必须先配置环境变量。
        com.aliyun.ocr20191230.Client client = Sample.createClient(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        // 场景一,使用本地文件
        // InputStream inputStream = new FileInputStream(new File("/tmp/bankCard.png"));
        // 场景二,使用任意可访问的url
        URL url = new URL("https://viapi-test-bj.oss-cn-beijing.aliyuncs.com/viapi-3.0domepic/ocr/RecognizeBankCard/yhk1.jpg");
        InputStream inputStream = url.openConnection().getInputStream();
      
        // 5、这里只是以ocr下的RecognizeBankCard为例,其他能力请使用相应类目的包和类,具体入参设置需要参考具体能力的文档
        com.aliyun.ocr20191230.models.RecognizeBankCardAdvanceRequest recognizeBankCardAdvanceRequest = new com.aliyun.ocr20191230.models.RecognizeBankCardAdvanceRequest()
            .setImageURLObject(inputStream);
        com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
        try {
          
            // 6、这里只是以ocr下的RecognizeBankCard为例,其他能力请使用相应类目的包和类,注意,recognizeBankCardAdvance方法名也需要改成对应能力的方法名。方法名是根据能力名称按照一定规范形成的,如能力名称为SegmentCommonImage,对应方法名应该为segmentCommonImageAdvance。
            RecognizeBankCardResponse resp = client.recognizeBankCardAdvance(recognizeBankCardAdvanceRequest, runtime);
            // 获取整体结果。部分能力会输出url链接,通过toJSONString转换后可能有编码问题,但是通过单个字段获取是没问题的。
            System.out.println(com.aliyun.teautil.Common.toJSONString(TeaModel.buildMap(resp)));
            // 获取单个字段,这里只是一个例子,具体能力下的字段需要看具体能力的文档
            System.out.println(resp.getBody().getData().getCardNumber());
        } catch (com.aliyun.tea.TeaException teaException) {
            // 获取整体报错信息
            System.out.println(com.aliyun.teautil.Common.toJSONString(teaException));
            // 获取单个字段
            System.out.println(teaException.getCode());
        }
    }
}

需要修改的地方均在上述代码注释中标明,总结如下:

  1. 引入包的时候,需要引入相应类目的包和相关类。包名可参考上文SDK包名称,能力名称可参考对应API文档中的Action参数。

    例如,您想使用通用分割能力,通过通用分割API文档可知该能力属于分割抠图类目(imageseg20191230),能力名称为SegmentCommonImage,您需要将代码中的ocr20191230改为imageseg20191230,将RecognizeBankCard改为SegmentCommonImage。

  2. 访问的域名一定要修改为相应类目的域名,如果域名类目不匹配会报错InvalidAction.NotFound。关于域名详情,请参见访问域名

  3. Client类需要使用相应类目的包下面的Client类。

  4. Request和Response需要使用相应类目的包和类。

  5. 调用Client的方法时,方法名需要改成对应能力的方法名。方法名是根据能力名称按照一定规范形成的。例如,能力名称为SegmentCommonImage,对应方法名应该为segmentCommonImageAdvance。

常见问题

调用报错如何解决?

如果您的调用出现报错,请先尝试升级SDK包到最新版本,最新版本请参考各类目SDK链接。如果您的程序中同时引入了多个类目的包,可以先尝试将这些包都升级到最新版本,避免版本之间的包冲突问题。也有可能是引入的包和您已经在使用的包发生冲突,可先通过Maven依赖分析工具解决包冲突问题。

OpenAPI界面显示的最新包在Maven仓库中找不到如何解决?

如果您发现OpenAPI界面显示的最新版本的包,在Maven仓库中找不到,这是因为新版本的包刚刚发布,仓库同步可能会有延迟,如果遇到版本不存在的情况,请稍后再试或使用Maven仓库中的最新版本。

该SDK是否可以用于Android开发?

可以。Android端调用请参考Android端直接调用

Java升级版SDK默认不忽略证书,HTTPS请求下缺少证书会报错应如何解决?

报错信息

image

解决方案

升级版SDK中可以通过在Client中设置OpenAPI的请求协议,Client设置的优先级高于默认设置。更多关于忽略证书的信息,请参见HTTPS 请求配置

文件在本地或可访问的URL场景下,使用xxxAdvanceRequest类引入SDK报错,应如何解决?

报错信息

Exception in thread "main" java.lang.NoSuchMethodError: com.aliyun.credentials.Client.getCredential()Lcom/aliyun/credentials/models/CredentialModel;
    at com.aliyun.teaopenapi.Client.doRequest(Client.java:814)
    at com.aliyun.teaopenapi.Client.callApi(Client.java:1083)
    at com.aliyun.openplatform20191219.Client.authorizeFileUploadWithOptions(Client.java:46)
    at com.aliyun.facebody20191230.Client.compareFaceAdvance(Client.java:894)
    at com.test.CompareFace.main(CompareFace.java:56)

解决方案

该报错是由于出现依赖冲突导致,您需要将credentials包更新到最新版即可,依赖如下最新SDK。

<!-- https://mvnrepository.com/artifact/com.aliyun/credentials-java -->
<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>credentials-java</artifactId>
    <version>0.3.0</version>
</dependency>

技术支持

如果以上方法未能解决您的问题,请通过搜索钉钉群号(23109592)加入阿里云视觉智能开放平台咨询群联系我们,届时会有专业的技术人员与您对接解决问题。