视觉智能开放平台JavaSDK_视觉智能开放平台(VIAPI)-阿里云帮助中心

本文介绍了如何使用阿里云视觉智能开放平台的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
人脸核身服务端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_ID和ALIBABA_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_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET，并写入已准备好的AccessKey ID和AccessKey Secret。然后重启Windows系统。本操作以Windows 10为例进行说明。
1. 打开文件资源管理器，在此电脑上右键单击属性。
2. 在右侧导航栏，单击高级系统配置。
3. 在系统属性对话框的高级页签下，单击环境变量。
4. 在环境变量对话框中，单击新建(W)。
5. 在弹出的新建系统变量对话框中，添加环境变量ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_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());
        }
    }
}

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

引入包的时候，需要引入相应类目的包和相关类。包名可参考上文SDK包名称，能力名称可参考对应API文档中的Action参数。
例如，您想使用通用分割能力，通过通用分割API文档可知该能力属于分割抠图类目（imageseg20191230），能力名称为SegmentCommonImage，您需要将代码中的ocr20191230改为imageseg20191230，将RecognizeBankCard改为SegmentCommonImage。
访问的域名一定要修改为相应类目的域名，如果域名类目不匹配会报错InvalidAction.NotFound。关于域名详情，请参见访问域名。
Client类需要使用相应类目的包下的Client类。
Request和Response需要使用相应类目的包和类。
调用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());
        }
    }
}

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

引入包的时候，需要引入相应类目的包和相关类。包名可参考上文SDK包名称，能力名称可参考对应API文档中的Action参数。
例如，您想使用通用分割能力，通过通用分割API文档可知该能力属于分割抠图类目（imageseg20191230），能力名称为SegmentCommonImage，您需要将代码中的ocr20191230改为imageseg20191230，将RecognizeBankCard改为SegmentCommonImage。
访问的域名一定要修改为相应类目的域名，如果域名类目不匹配会报错InvalidAction.NotFound。关于域名详情，请参见访问域名。
Client类需要使用相应类目的包下面的Client类。
Request和Response需要使用相应类目的包和类。
调用Client的方法时，方法名需要改成对应能力的方法名。方法名是根据能力名称按照一定规范形成的。例如，能力名称为SegmentCommonImage，对应方法名应该为segmentCommonImageAdvance。

常见问题

调用报错如何解决？

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

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

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

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

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

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

报错信息

解决方案

升级版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）加入阿里云视觉智能开放平台咨询群联系我们，届时会有专业的技术人员与您对接解决问题。