文档

多媒体分析:Python SDK使用说明

PAI多媒体分析支持通过Python SDK调用各项算法服务。本文为您介绍多媒体分析Python SDK的接口详情以及使用Python SDK调用算法服务和查询结果的示例。

步骤一:安装Python SDK

环境依赖Python 3及其以上版本,安装命令如下。

wget https://ai-service-data.oss-cn-beijing.aliyuncs.com/python-sdk/ai_service_python_sdk-1.1.4-py3-none-any.whl
pip install ai_service_python_sdk-1.1.4-py3-none-any.whl

步骤二:初始化Client

使用以下命令,进行环境初始化。

from ai_service_python_sdk.client.api_client import ApiClient
client = ApiClient('<HOST>', '<YOUR-APPID>', '<YOUR-TOKEN>')

您需要根据实际情况,替换以下参数值。

参数

描述

<HOST>

服务端地址为:http://ai-service.ce8cc13b6421545749e7b4605f3d02607.cn-hangzhou.alicontainer.com

<YOUR-APPID>

开通多媒体分析服务后,您可以直接在多媒体分析页面查看AppId

<YOUR-TOKEN>

开通多媒体分析服务后,您可以直接在多媒体分析页面查看TOKEN

使用示例

图像质量评分

提供图像质量评估能力,返回[0,100]的浮点数分值,请求代码示例如下。

from ai_service_python_sdk.client.api.ai_service_image_api import AiServiceImageApi

# 请求图片URL。
image_url = 'https://your_image_url.jpg'
ai_service_api = AiServiceImageApi(client)
# 定制模型名称。
model_name = ''
# 模型返回配置,该模型没有返回配置参数,传入空字典即可。
configure = {}
# 请求服务。
response = ai_service_api.image_qa(image_url, model_name, configure)
# 请求流水号。
request_id = response.request_id
# 请求状态。
code = response.code
# 请求状态具体信息。
message = response.message
# 模型返回值。
data = response.data
# 打印返回结果。
print(response)

参数说明如下。

参数

类型

是否必选

描述

image_url

STRING

图片URL,建议图片大小不大于5 MB,分辨率不低于240 * 240。

model_name

STRING

默认输入空字符串,表示调用通用模型。

如果通用模型不能满足您的业务需求,您可以联系您的商务经理,为您提供定制模型。传入定制模型名称,即可调用定制的模型结果。

configure

Dict

模型返回配置,该模型服务输入空字典即可。

返回结果示例如下。

{
    "code":"OK",
    "data":{
        "image_height":214,
        "image_width":398,
        "iqa_result":66.88
    },
    "message":"success",
    "request_id":"1d4572a1-2800-4213-9e9c-33f9fa7e****"
}

返回字段说明如下。

参数

描述

request_id

请求流水号,STRING类型。

code

请求状态码,STRING类型。

message

请求状态具体信息,STRING类型。返回示例如下:

  • success

  • Invalid Input - image data error - base64decode error: base64decode error: incorrect base64 format data

  • Invalid Input - json format error - json parse runtime exception

更多请求状态,详情请参见返回错误码说明

data

模型返回内容,Dict类型。内部参数说明如下:

  • image_height:图片像素高度,INT类型。

  • image_width:图像像素宽度,INT类型。

  • iqa_result:质量分,FLOAT类型,精度精确到小数点后两位。

人脸属性分析

提供人脸相关属性的输出,包括脸型、发色、发型、颜值等信息。请求代码示例如下。

from ai_service_python_sdk.client.api.ai_service_image_api import AiServiceImageApi

# 请求图片URL。
image_url = 'https://your_image_url.jpg'
ai_service_api = AiServiceImageApi(client)
# 定制模型名称。
model_name = ''
# 模型返回配置,该模型没有返回配置参数,传入空字典即可。
configure = {}
# 请求服务。
response = ai_service_api.face_attr_image(image_url, model_name, configure)
# 请求流水号。
request_id = response.request_id
# 请求状态。
code = response.code
# 请求状态具体信息。
message = response.message
# 模型返回值。
data = response.data
# 打印返回结果。
print(response)

参数说明如下。

参数

类型

是否必选

描述

image_url

STRING

图片URL。图像中人脸区域大小需大于100 * 100像素。

model_name

STRING

默认输入空字符串,表示调用通用模型。

如果通用模型不能满足您的业务需求,您可以联系您的商务经理,为您提供定制模型。传入定制模型名称,即可调用定制的模型结果。

configure

Dict

模型返回配置,该模型服务输入空字典即可。

返回结果如下。

{'code': 'OK',
 'data': {'attr': [{'FaceShape': {'三角脸': 0.0013,
                                  '圆脸': 0.0147,
                                  '心形脸': 0.0405,
                                  '方形脸': 0.0001,
                                  '椭圆脸': 0.9266,
                                  '菱形脸': 0.0027,
                                  '长脸': 0.0141},
                    'FemaleHairStyle': {'BangsType': {'中分刘海': 0.5932,
                                                      '刘海编发': 0.0058,
                                                      '斜刘海': 0.0575,
                                                      '无刘海': 0.3078,
                                                      '空气刘海': 0.0143,
                                                      '齐刘海': 0.0213},
                                        'FemaleCurlyHairType': {'云朵卷': 0.1289,
                                                                '大波浪': 0.2526,
                                                                '小波浪': 0.084,
                                                                '氧气卷': 0.2027,
                                                                '空气卷': 0.1434,
                                                                '羊毛卷': 0.1539,
                                                                '蛋卷': 0.0345},
                                        'FemaleHairType': {'卷发': 0.1941,
                                                           '盘发': 0.0112,
                                                           '直发': 0.7947},
                                        'FemaleLongShortHair': {'中长发': 0.2807,
                                                                '短发': 0.0346,
                                                                '长发': 0.6846},
                                        '扎发': 0.3054,
                                        '编发': 0.3453},
                    'HairColor': {'其他颜色': 0.0001,
                                  '咖啡色': 0,
                                  '奶奶灰': 0,
                                  '栗色': 0.0025,
                                  '棕色': 0.0622,
                                  '渐变色': 0.0004,
                                  '酒红色': 0.0001,
                                  '金色': 0,
                                  '黄色': 0,
                                  '黑色': 0.9347},
                    'MaleHairStyle': {'分发': 0.9939,
                                      '圆寸': 0,
                                      '子弹头': 0.0033,
                                      '平头': 0,
                                      '板寸': 0.001,
                                      '毛寸': 0.0008,
                                      '碎发': 0,
                                      '背头': 0.0001,
                                      '莫西干': 0.0006},
                    'bbox': [91, 0, 430, 452],
                    'face_score': 3.2431,
                    'index': 0}]},
 'message': 'success',
 'request_id': '9b2f2c0e-d2c0-45f8-b922-058d00edc9ad'}

返回字段说明如下。

参数

描述

request_id

请求流水号,STRING类型。

code

请求状态码,STRING类型。

message

请求状态具体信息,STRING类型。返回示例如下:

  • success

  • Invalid Input - image data error - base64decode error: base64decode error: incorrect base64 format data

  • Invalid Input - json format error - json parse runtime exception

更多请求状态,详情请参见返回错误码说明

Data

模型返回内容,Dict类型。具体返回参数说明,详情请参见data内部字段

表 1. data内部字段

参数

描述

attr

整个图像的属性内容,List类型。列表中的每一个元素表示一个人脸的属性。

说明

如果列表内容为空,表示没有检测到人脸。

FaceShape

人脸形状,Dict类型。

FemaleHairStyle

女性发型分类,Dict类型。

BangsType

女性刘海类型,Dict类型。

FemaleCurlyHairType

女性卷发类型,Dict类型。

FemaleHairType字段中,卷发对应概率最高时读取该字段的内容。

FemaleHairType

女性发型,Dict类型。

FemaleLongShortHair

女性头发长短,Dict类型。

扎发

女性头发是否为扎发,FLOAT类型。

该值大于等于0.5时,表示头发是扎发。

编发

女性头发是否是编发,FLOAT类型。

该值大于等于0.5时,表示头发是编发。

HairColor

头发颜色,Dict类型。

MaleHairStyle

男性发型分类,Dict类型。

bbox

人脸矩形框,LIST类型。排列为[xmin,ymin,xmax,ymax]

index

人脸在该图中的编号,INT类型,从0开始递增。

年龄分析

用于识别图像中主体人脸(需唯一)的年龄区间。

说明

由于该模型属于定制模型,您需要提供AppId给您的商务经理或相关接口人,进行后台配置后才可以调用。

请求代码示例如下:

from ai_service_python_sdk.client.api.ai_service_image_api import AiServiceImageApi

# 请求图片URL
image_url = 'https://your_image_url.jpg'
ai_service_api = AiServiceImageApi(client)
# 定制模型名称
model_name = 'fairface'
# 模型返回配置,该模型没有返回配置参数,传入空字典即可
configure = {}
# 请求服务
response = ai_service_api.face_attr_image(image_url, model_name, configure)
# 请求流水号
request_id = response.request_id
# 请求状态
code = response.code
# 请求状态具体信息
message = response.message
# 模型返回值
data = response.data
# 打印返回结果
print(response)

参数说明如下:

参数

类型

是否必选

描述

image_url

STRING

图片的URL地址。图片中的人脸区域需要大于100×100像素。

model_name

STRING

自定义模型名称。

configure

Dict

模型返回配置。该模型服务输入空字典即可。

返回结果示例如下:

{
    "request_id":"10000",
    "code":"OK",
    "message":"success",
    "data":{
        "age_range":"3-9",
        "age_raneg_prob":0.9525
    }
}

参数

描述

request_id

请求流水号,STRING类型。

code

请求状态码,STRING类型。

message

请求状态具体信息,STRING类型。返回示例如下:

  • success

  • Invalid Input - image data error - {具体报错}

data

模型返回内容,Dict类型。具体返回参数说明如下:

  • age_range:年龄区间,STRING类型。可能值为'0-2', '3-9', '10-19', '20-29', '30-39', '40-49', '50-59', '60-69', '70+'

  • age_raneg_prob:年龄区间概率,FLOAT类型。

图像多标签

提供图像多标签打标能力,支持输出概率较高的Top K个标签及对应概率,也支持输出图像的高维特征。请求代码示例如下。

from ai_service_python_sdk.client.api.ai_service_image_api import AiServiceImageApi

# 请求图片URL。
image_url = 'https://your_image_url.jpg'
ai_service_api = AiServiceImageApi(client)
# 定制模型名称。
model_name = ''
# 模型返回配置。
configure = {'tag_top_k': 5, 'output_embedding': False}
# 请求服务。
response = ai_service_api.multi_label_image_v2(image_url, model_name, configure)
# 请求流水号。
request_id = response.request_id
# 请求状态。
code = response.code
# 请求状态具体信息。
message = response.message
# 模型返回值。
data = response.data
# 打印返回结果。
print(response)

参数说明如下。

参数

类型

是否必选

描述

image_url

STRING

图片URL,建议图片大小不大于5 MB,分辨率不低于240 * 240。

model_name

STRING

默认输入空字符串,表示调用通用模型。

如果通用模型不能满足您的业务需求,您可以联系阿里云机器学习支持团队,为您提供定制模型。传入定制模型名称,即可调用定制的模型结果。

configure

Dict

模型返回配置,默认输入None。具体参数配置,详情请参见configure内部参数

说明

configureNone时,configure内部参数取默认值。

configure内部参数

configure内部参数

类型

是否必选

描述

tag_top_k

INT

输出Top K个结果。取值范围:[1,10],默认为10。

output_embedding

BOOL

是否输出图片embedding,取值如下:

  • True:默认值,表示输出图片高维特征。

  • False

返回结果示例如下。

{'code': 'OK',
 'data': {'image_height': 510,
          'image_width': 516,
          'tag_result': [{'score': 0.505, 'tag': '笑容'},
                         {'score': 0.493, 'tag': '女士'},
                         {'score': 0.475, 'tag': '美女'},
                         {'score': 0.438, 'tag': '微笑'},
                         {'score': 0.432, 'tag': '蜜茶棕'}]},
 'message': 'success',
 'request_id': 'c9e5aa33-4d8d-49ce-8991-bcbb5f12e43b'}

返回字段说明如下。

参数

描述

request_id

请求流水号,STRING类型。

code

请求状态码,STRING类型。

message

请求状态具体信息,STRING类型。返回示例如下:

  • success

  • Invalid Input - image data error - base64decode error: base64decode error: incorrect base64 format data

  • Invalid Input - json format error - json parse runtime exception

更多请求状态,详情请参见返回错误码说明

data

模型返回内容,Dict类型。具体返回参数说明,详情请参见data内部字段

表 3. data内部字段

参数

描述

tag_result

标签结果,List类型,按score(概率)降序排列。

列表长度由tag_top_k决定。

score

标签概率,FLOAT类型,精度精确到小数点后三位。

tag

标签名,STRING类型。

embedding_result

512维图片特征,STRING类型,使用半角逗号(,)分隔。

仅当output_embedding为True时,存在该返回字段。

image_height

图片像素高度,INT类型。

image_width

图片像素宽度,INT类型。

AI绘图打标

提供AI绘图(Stable-Diffusion)训练使用到的图像多标签打标能力,输出为合成好的Caption以及相对于原标签集合的得分。

重要

该模型属于定制模型,您需要提供AppId给您的商务经理或相关接口人,进行后台配置后才可以调用。

请求示例如下。

from ai_service_python_sdk.client.api.ai_service_image_api import AiServiceImageApi

# 请求图片URL
image_url = 'https://your_image_url.jpg'
ai_service_api = AiServiceImageApi(client)
# 定制模型名称
model_name = 'tagger'
# 模型返回配置
configure = {'threshold': 0.5, 'tagger_type': "SmilingWolf/wd-v1-4-convnextv2-tagger-v2"}
# 请求服务
response = ai_service_api.multi_label_image_v2(image_url, model_name, configure)
# 请求流水号
request_id = response.request_id
# 请求状态
code = response.code
# 请求状态具体信息
message = response.message
# 模型返回值
data = response.data
# 打印返回结果
print(response)

参数说明如下:

参数名称

参数说明

类型

是否必须

image_url

图片URL,建议大小不大于5 M,分辨率不低于 240*240。

STRING

model_name

模型名称,输入tagger

STRING

configure

模型返回配置configure,默认输入None。内部参数说明,请参见configure内部参数

Dict

configure内部参数

configure

内部参数

参数说明

类型

是否

必须

示例

threshold

输入门限。

FLOAT

0.5

tagger_type

使用的打标模型。

  • SmilingWolf/wd-v1-4-convnext-tagger-v2

  • SmilingWolf/wd-v1-4-convnextv2-tagger-v2

  • SmilingWolf/wd-v1-4-vit-tagger-v2

  • SmilingWolf/wd-v1-4-swinv2-tagger-v2

  • RAM

  • BLIP

  • GIT

STR

SmilingWolf/wd-v1-4-convnextv2-tagger-v2

返回结果示例如下:

{
    "data": {
    	"caption": "sensitive, 1girl, solo, long hair, looking at viewer, smile, black hair, brown eyes, scarf, lips, realistic",
    	"probs": [1.1920928955078125e-07, ............, 3.5762786865234375e-07, 4.76837158203125e-07],
	}
    "request_id": "12***", 
    "code": "OK",
    "message": "success"
}

返回字段

参数说明

类型

request_id

请求流水号。

STRING

code

请求状态码。

STRING

message

请求状态具体信息,示例:

  • success

  • Invalid Input - image data error - base64decode error: incorrect base64 format data

  • Invalid Input - json format error - json parse runtime exception

STRING

data

模型返回内容。内部字段说明,请参见data内部字段说明

Dict

data内部字段说明

data内部字段

参数说明

类型

caption

打标结果,以半角逗号(,)分割。

STR

probs

使用指定的打标模型打标获得的得分。

List

人像身材修改

提供人像身材修改能力,上传人像照片,根据degree参数控制人像胖身或瘦身(degree > 0代表瘦身)

重要

该模型属于定制模型,您需要提供AppId给您的商务经理或相关接口人,进行后台配置后才可以调用。

请求代码示例如下:

from ai_service_python_sdk.client.api.ai_service_image_api import AiServiceImageApi

# 请求图片URL
image_url = 'https://your_image_url.jpg'
ai_service_api = AiServiceImageApi(client)
# 人身修改的模型名称
model_name = 'body_reshaping'
# 大码化需求下,degree 建议 [-2.5, -1.5]
configure = {'degree': -1.5}
# 请求服务
response = ai_service_api.multi_label_image_v2(image_url, model_name, configure)
# 请求流水号
request_id = response.request_id
# 请求状态
code = response.code
# 请求状态具体信息
message = response.message
# 模型返回值
data = response.data
# 打印返回结果
print(response)

请求参数说明:

参数名称

参数说明

类型

是否必须

image_url

图片URL,建议大小不大于5 M,分辨率不低于 240*240。

STRING

model_name

模型名称,填写body_reshaping

STRING

configure

模型返回配置configure,默认输入None。内部参数说明,请参见configure内部参数说明

Dict

configure内部参数说明

configure内部参数名称

参数说明

类型

是否必须

degree

身材修改程度,> 0代表对图像中的人物进行瘦身,默认值为 -1.5

FLOAT

返回结果示例如下:

{
 "code":"OK",
 "data":"imByev+I3vrryTGN****",
 "message":"success",
 "request_id":"1d4572a1-2800-4213-9e9c-33********"
}

返回字段说明如下:

返回字段

参数说明

类型

request_id

请求流水号。

STRING

code

请求状态码。

STRING

message

请求状态具体信息,示例:

  • success

  • Invalid Input - image data error - base64decode error: base64decode error: incorrect base64 format data

  • Invalid Input - json format error - json parse runtime exception

STRING

data

模型推理返回的图片base64。

STRING

图像去水印

传入带水印的图像,返回无水印图像。

重要

该模型属于定制模型,您需要提供AppId给您的商务经理或相关接口人,进行后台配置后才可以调用。

请求代码示例如下:

from ai_service_python_sdk.client.api.ai_service_image_api import AiServiceImageApi

# 请求图片URL
image_url = 'https://your_image_url.jpg'
ai_service_api = AiServiceImageApi(client)
# 定制模型名称
model_name = 'watermark_remover'
# 传入空字典即可
configure = {}
# 请求服务
response = ai_service_api.multi_label_image_v2(image_url, model_name, configure)
# 请求流水号
request_id = response.request_id
# 请求状态
code = response.code
# 请求状态具体信息
message = response.message
# 模型返回值
data = response.data
# 打印返回结果
print(response)

请求参数说明如下。

参数名称

参数说明

类型

是否必须

image_url

图片URL,建议大小不大于 5M,分辨率不低于 240*240。

STRING

model_name

模型名称,填写watermark_remover

STRING

configure

模型返回配置configure,默认输入None

Dict

返回结果示例如下:

{
 "code":"OK",
 "data":"imByev+I3vr****",
 "message":"success",
 "request_id":"1d4572a****"
}

结果字段说明:

返回字段

参数说明

类型

request_id

请求流水号。

STRING

code

请求状态码。

STRING

message

请求状态具体信息,示例:

  • success

  • Invalid Input - image data error - base64decode error: incorrect base64 format data

  • Invalid Input - json format error - json parse runtime exception

STRING

data

模型推理返回图片的base64。

STRING

图文视频动态分类打标

为包含多模态内容的动态或帖子提供分类打标服务,支持使用文本+图片或文本+视频的组合进行分类打标,并支持返回高维特征Embedding。

说明

由于该模型属于定制模型,您需要提供AppId给您的商务经理或相关接口人,进行后台配置后才可以调用。

请求代码示例如下:

from ai_service_python_sdk.client.api.ai_service_video_api import AiServiceVideoApi

ai_service_api = AiServiceVideoApi(client)
# 多模态打标模型名称
model_name = 'multi_modal_tag'
# 视频URL,若没有则传入空字符串
video_url = 'https://YOUR_VIDEO.mp4'
# 图片URL集,若没有则传入空数组
images = [
    'https://YOUR_IMAGE_0.jpg',
    'https://YOUR_IMAGE_1.jpg',
    'https://YOUR_IMAGE_2.jpg'
]
# 文本内容
text = '文本内容'
# 模型返回配置
configure = {
    'output_classification': True, 
    'classification_top_k': 1,
    'output_tag': True,
    'tag_top_k': 5, 
    'output_embedding': True
}
# 请求服务
response = ai_service_api.multimodal_classify(video_url, images, text, model_name, configure)
# 请求流水号
request_id = response.request_id
# 请求状态
code = response.code
# 请求状态具体信息
message = response.message
# 请求返回内容
data = response.data
# job id
job_id = response.data['job_id']
# 打印返回结果
print(response)

参数说明如下:

参数

类型

是否必选

描述

video_url

STRING

视频的URL地址,如果没有视频则传入空字符串。

images

List[STRING]

图片的URL集合,如果没有图片则传入空数组。多个图片URL地址使用半角逗号(,)分隔。

text

STRING

文本内容,使用标题与简介进行拼接。

model_name

STRING

模型名称。

configure

Dict

模型额外配置,Dict类型。内部参数说明,请参见configure内部参数

configure内部参数

configure内部参数

类型

是否必选

描述

output_classification

BOOL

是否输出分类结果,默认为True。

classification_top_k

INT

输出TopK的分类结果,范围为[1, 10],默认为1。

output_tag

BOOL

是否输出标签结果,默认为True。

tag_top_k

INT

输出TopK的标签结果,范围为[1, 10],默认为5。

output_embedding

BOOL

是否输出32维的多模态embedding,默认为True。

返回结果示例如下:

{'code': 'OK',
 'data': {'job_id': 1134***},
 'message': 'success',
 'request_id': '49b0c9c2-06be-4f30-9b9f-f04baecf4577'}

从上述返回结果中获取job_id,并使用以下代码进行结果查询。

from ai_service_python_sdk.client.api.ai_service_job_api import AiServiceJobApi

ai_service_job_api = AiServiceJobApi(client)
# 结果查询
result = ai_service_job_api.get_async_job(<YOUR-JOB-ID>)
# 打印返回结果
print(result)

其中:<YOUR-JOB-ID>需要替换为请求服务时返回的job_id

返回结果示例如下:

  • 任务执行中的返回结果示例如下:

    {'code': 'OK',
     'data': {'job': {'Result': '',
                      'app_id': 'YOUR_APPID',
                      'create_time': '2023-10-18T14:32:42.619+08:00',
                      'id': 1134206,
                      'message': 'video downloading',
                      'state': 1}},
     'message': 'success',
     'request_id': '49b0c9c2-06be-4f30-9b9f-f04baecf4577'}
  • 任务执行完成后的返回结果示例如下:

    {
    'code': 'OK',
    'data': {'job': 
                {'Result': 
                            '{"classification_result":[{"class":"旅游","score":0.67}],
                            "duration":15.16,
                            "embedding_result":"0.915,0.882,0.943,0.978,1.027,1.181,1.066,1.029,0.866,0.716,0.628,1.203,0.689,0.533,0.734,1.038,0.98,0.613,0.96,0.88,0.586,0.702,1.515,0.697,0.987,0.699,1.179,4.274,0.757,0.89,0.805,0.901",
                            "tag_result":[{"score":0.56,"tag":"有字幕"},{"score":0.456,"tag":"航拍"},{"score":0.453,"tag":"西藏"},{"score":0.437,"tag":"交通工具"},{"score":0.429,"tag":"机械"}],
                            "video_height":918,
                            "video_width":552}',
                            'app_id': '202211140827340****',
                            'create_time': '2023-10-18T14:32:42.619+08:00',
                            'id': 113****,
                            'message': 'success',
                            'model_id': 0,
                            'request_id': '',
                            'state': 2,
                            'type': 'Video'
                }
            },
    'message': 'success',
    'request_id': '139a40ad-fdf6-45de-b760-161c52ff3f3c'
    }

返回字段说明如下:

返回字段

类型

参数说明

request_id

STRING

请求流水号。

code

STRING

请求状态码。

message

STRING

请求状态具体信息,可能值为:

  • success

  • Invalid Input - video data error - load video failed

  • Invalid Input - json format error - json parse runtime exception

data

Dict

模型返回内容。内部字段说明,详情请参见data内部字段说明

data内部字段说明

data['job']内部字段

类型

字段说明

id

INT

任务ID,即job_id。

app_id

STRING

用户的AppId。

state

INT

任务状态码,可能值为:

  • 0:任务初始化。

  • 1:任务执行中。

  • 2:任务完成。

  • 3:任务失败。

message

STRING

任务执行信息,可能值为:

  • success

  • video downloading

create_time

STRING

任务创建的时间。

Result

STRING

模型返回结果,内部字段说明,请参见Result内部字段说明

Result内部字段说明

Result内部字段

类型

字段说明

classification_result

List

分类结果,按score降序排列。长度由

classification_top_k决定,每个元素为Dict格式。

仅当output_classification为True时存在该字段。

tag_result

List

标签结果,按score降序排列。长度由tag_top_k决定,每个元素为Dict格式。

仅当output_tag为True时存在该字段。

score

FLOAT

标签概率,精度到小数点后3位。

class

STRING

类别名。

tag

STRING

标签名。

embedding_result

STRING

32维多模态特征,使用半角逗号(,)分隔。

video_height

INT

视频像素高度。当video_url传入空字符串时,该值为空字符串。

video_width

INT

视频像素宽度。当video_url传入空字符串时,该值为空字符串。

duration

FLOAT

视频时长。当video_url传入空字符串时,该值为空字符串。

视频质量评分

提供短视频质量评估能力,返回[0,100]的浮点质量分。支持以下两种请求方式:

  • 单次请求接口,请求代码示例如下。

    from ai_service_python_sdk.client.api.ai_service_video_api import AiServiceVideoApi
    
    video_url = 'https://your_video_url.mp4'
    ai_service_api = AiServiceVideoApi(client)
    # 定制模型名称。
    model_name = ''
    # 视频标题。
    video_title = ''
    # 模型返回配置。
    configure = {}
    # 请求服务。
    response = ai_service_api.video_qa(video_url, model_name, video_title, configure)
    # 请求流水号。
    request_id = response.request_id
    # 请求状态。
    code = response.code
    # 请求状态具体信息。
    message = response.message
    # 请求返回内容。
    data = response.data
    # job id。
    job_id = response.data['job_id']
    # 打印返回结果。
    print(response)

    参数说明如下。

    参数

    类型

    是否必选

    描述

    video_url

    STRING

    视频URL,建议视频大小不大于100 MB,分辨率不低于320 * 240。

    video_title

    STRING

    视频标题,该模型不会用到标题,所以传入空字符串即可。

    model_name

    STRING

    默认输入空字符串,表示调用通用模型。

    如果通用模型不能满足您的业务需求,您可以联系您的商务经理,为您提供定制模型。传入定制模型名称,即可调用定制的模型结果。

    configure

    Dict

    模型返回配置,该模型服务输入空字典即可。

    返回结果示例如下。

    {'code': 'OK',
     'data': {'job_id': 10**},
     'message': 'success',
     'request_id': '228235a6-db4f-466a-b20b-a4453f81****'}

    从上述返回结果中获取job_id,并使用以下代码进行结果查询。

    from ai_service_python_sdk.client.api.ai_service_job_api import AiServiceJobApi
    
    ai_service_job_api = AiServiceJobApi(client)
    # 结果查询。
    result = ai_service_job_api.get_async_job(<YOUR-JOB-ID>)
    # 打印返回结果。
    print(result)

    其中:<YOUR-JOB-ID>:需要替换为请求服务时返回的job_id,INT类型。

    • 任务执行中时,返回结果示例如下。

      {'code': 'OK',
       'data': {'job': {'Result': '',
                        'app_id': '202209070402410****',
                        'create_time': '2022-09-07T14:03:33.8+08:00',
                        'id': 1012,
                        'message': 'video downloading',
                        'state': 1}},
       'message': 'success',
       'request_id': '5259ec57-e55c-4772-b01e-3deafd74****'}
    • 任务执行完成后,返回结果示例如下。

      {'code': 'OK',
       'data': {'job': {'Result': '{"avg_fps":30,"duration":14,"height":1920,"single_img":0.74072265625,"video_score":20.57750291278764,"width":1080}',
                        'app_id': '202209290847310****',
                        'create_time': '2022-10-12T10:51:30.015+08:00',
                        'id': 1012,
                        'message': 'success',
                        'state': 2}},
       'message': 'success',
       'request_id': '0b4f658f-cd96-4606-8d81-d2fe0a6d****'}

    返回字段说明如下。

    参数

    类型

    描述

    request_id

    STRING

    请求流水号,STRING类型。

    code

    STRING

    请求状态码,STRING类型。

    message

    STRING

    请求状态具体信息,STRING类型。返回示例如下:

    • success

    • Invalid Input - video data error - load video failed

    • Invalid Input - json format error - json parse runtime exception

    更多请求状态,详情请参见返回错误码说明

    data

    Dict

    模型返回内容,Dict类型。具体返回参数说明,详情请参见data内部字段

    表 4. data内部字段

    参数

    描述

    id

    任务ID,即job_id,INT类型。

    app_id

    您的AppId,STRING类型。

    state

    任务状态码,INT类型。取值如下:

    • 0:任务初始化。

    • 1:任务执行中。

    • 2:任务完成。

    • 3:任务失败。

    message

    任务执行信息,STRING类型。取值如下:

    • success

    • video downloading

    create_time

    任务创建时间,STRING类型。

    Result

    模型返回结果,STRING类型。具体返回参数说明,详情请参见Result内部字段

    表 5. Result内部字段

    参数

    描述

    video_score

    质量分,FLOAT类型,取值范围为[0,100]。

    avg_fps

    视频的平均帧率,INT类型。

    duration

    视频时长,单位:秒,INT类型。

    single_img

    视频里图像间的差异度,FLOAT类型。取值范围为[0,1]。值越小表示图像间的差异越小,越接近静态图生成的视频。

    height

    视频图像的高,INT类型。

    width

    视频图像的宽,INT类型。

  • 批量请求接口,请求代码示例如下。

    from ai_service_python_sdk.client.api.ai_service_video_api import AiServiceVideoApi
    from ai_service_python_sdk.client.models.batch_video_request_videos import BatchVideoRequestVideos
    
    ai_service_api = AiServiceVideoApi(client)
    
    # 构建批量请求(视频URL + 视频标题)。
    videos = [
        BatchVideoRequestVideos('https://your_video_1_url.mp4', ''),
        BatchVideoRequestVideos('https://your_video_2_url.mp4', '')
        ]
    # 定制模型名称。
    model_name = ''
    # 模型返回配置。
    configure = {}
    # 请求服务。
    response = ai_service_api.batch_video_qa(videos, model_name, configure)
    # 请求流水号。
    request_id = response.request_id
    # 请求状态。
    code = response.code
    # 请求状态具体信息。
    message = response.message
    # 请求返回内容。
    data = response.data
    # batch id。
    batch_id = response.data['batch_id']
    # 打印返回结果。
    print(response)

    返回结果示例如下。

    {'code': 'OK',
     'data': {'batch_id': 14},
     'message': 'success',
     'request_id': '6d5ef1b5-c01f-4e63-9eec-150ddde9****'}

    从上述返回结果中获取batch_id,并使用以下代码进行结果查询。

    from ai_service_python_sdk.client.api.ai_service_job_api import AiServiceJobApi
    
    ai_service_job_api = AiServiceJobApi(client)
    # 结果查询。
    result = ai_service_job_api.get_batch_job_with_id(<YOUR-BATCH-ID>)
    # 打印返回结果。
    print(result)

    其中:<YOUR-BATCH-ID>:需要替换为请求服务时返回的batch_id,INT类型。

    查询结果示例如下。

    {'code': 'OK',
     'data': {'jobs': [{'Result': '{"avg_fps":30,"duration":14.633333333333333,"height":1280,"single_img":0.486328125,"video_score":55.3773279862801,"width":720}',
                        'app_id': '202209290847310****',
                        'batch_id': 14,
                        'create_time': '2022-10-26T19:44:47.501+08:00',
                        'id': 44**,
                        'message': 'success',
                        'object': 'https://your_video_1_url.mp4',
                        'state': 2},
                       {'Result': '{"avg_fps":30,"duration":18.2,"height":568,"single_img":0.5791015625,"video_score":67.21071975649835,"width":320}',
                        'app_id': '202209290847310****',
                        'batch_id': 14,
                        'create_time': '2022-10-26T19:44:47.501+08:00',
                        'id': 4484,
                        'message': 'success',
                        'object': 'https://your_video_2_url.mp4',
                        'state': 2}]},
     'message': 'success',
     'request_id': 'e99697ff-7d42-4c0a-a0a0-c6a0c0ba****'}

    批量请求返回的data['jobs']为数组形式,具体字段说明如下。

    参数

    描述

    id

    批量任务中的单条数据ID,INT类型。

    batch_id

    批量任务ID,INT类型。

    app_id

    您的AppId,STRING类型。

    state

    任务状态码,INT类型,取值如下:

    • 0:任务初始化。

    • 1:任务执行中。

    • 2:任务完成。

    • 3:任务失败。

    message

    任务执行信息,STRING类型。取值如下:

    • success

    • video downloading

    create_time

    任务创建时间,STRING类型。

    object

    请求视频的URL,STRING类型。

    Result

    模型返回结果,STRING类型。

    说明

    与单次请求接口返回的Result内部字段相同。

视频分类打标

提供短视频分类打标能力,返回短视频类别和概率较高的Top K个标签及对应概率,也支持输出视频的高维特征。支持以下两种请求方式:

  • 单次请求接口,请求代码示例如下。

    from ai_service_python_sdk.client.api.ai_service_video_api import AiServiceVideoApi
    
    video_url = 'https://your_video_url.mp4'
    ai_service_api = AiServiceVideoApi(client)
    # 定制模型名称。
    model_name = ''
    # 视频标题。
    video_title = 'your_video_title'
    # 模型返回配置。
    configure = {
        'output_classification': True,
        'classification_top_k': 1,
        'output_tag': True,
        'tag_top_k': 5,
        'output_embedding': True
        }
    # 请求服务。
    response = ai_service_api.classify_label_video(video_url, video_title, model_name, configure)
    # 请求流水号。
    request_id = response.request_id
    # 请求状态。
    code = response.code
    # 请求状态具体信息。
    message = response.message
    # 请求返回内容。
    data = response.data
    # job id。
    job_id = response.data['job_id']
    # 打印返回结果。
    print(response)

    参数说明如下。

    参数

    类型

    是否必选

    描述

    video_url

    STRING

    视频URL,建议视频大小不大于100 MB,分辨率不低于320 * 240。

    video_title

    STRING

    视频标题,如果没有标题,可以传入空字符串。

    model_name

    STRING

    默认输入空字符串,表示调用通用模型。

    如果通用模型不能满足您的业务需求,您可以联系阿里云机器学习支持团队,为您提供定制模型。传入定制模型名称,即可调用定制的模型结果。

    configure

    Dict

    模型返回配置,默认输入None。具体参数配置,详情请参见configure内部参数

    说明

    configureNone时,configure内部参数取默认值。

    表 6. configure内部参数

    参数

    类型

    是否必选

    描述

    output_classification

    BOOL

    是否输出视频分类结果,取值如下:

    • True(默认值)

    • False

    classification_top_k

    INT

    输出TopK的分类结果,取值范围为:[1,10],默认为1。

    output_tag

    BOOL

    是否输出视频标签结果,取值如下:

    • True(默认值)

    • False

    tag_top_k

    INT

    输出TopK的标签结果,取值范围为:[1,10],默认为5。

    output_embedding

    BOOL

    是否输出64维的视频embedding,取值如下:

    • True(默认值)

    • False

    返回结果示例如下。

    {'code': 'OK',
     'data': {'job_id': 5},
     'message': 'success',
     'request_id': '4f6caecb-e3d6-4997-89fe-26ac7536****'}

    从上述返回结果中获取job_id,并使用以下代码进行结果查询。

    from ai_service_python_sdk.client.api.ai_service_job_api import AiServiceJobApi
    
    ai_service_job_api = AiServiceJobApi(client)
    # 结果查询。
    result = ai_service_job_api.get_async_job(<YOUR-JOB-ID>)
    # 打印返回结果。
    print(result)

    其中:<YOUR-JOB-ID>:需要替换为请求服务时返回的job_id,INT类型。

    • 任务执行中时,返回结果示例如下。

      {'code': 'OK',
       'data': {'job': {'Result': '',
                        'app_id': '202209070402410****',
                        'create_time': '2022-09-07T14:03:33.8+08:00',
                        'id': 5,
                        'message': 'video downloading',
                        'state': 1}},
       'message': 'success',
       'request_id': '5259ec57-e55c-4772-b01e-3deafd74****'}
      
    • 任务执行完成后,返回结果示例如下。

      {'code': 'OK',
       'data': {'job': {'Result':
          '{"classification_result":[
              {"class":"三农","score":0.997}
              ],
          "duration":14.633333333333333,
          "embedding_result":"-0.162,0.483,0.881,0.686,0.319,-1.569,0.266,0.227,-1.352,1.157,-0.784,-1.016,-0.987,-1.214,-0.493,-1.182,0.85,1.473,-1.27,-3.391,3.394,-0.471,-0.434,0.256,2.146,0.787,0.348,1.67,0.229,-0.878,0.299,0.392,-2.161,-0.756,-3.438,-0.158,0.713,-5.812,-1.248,0.253,-1.111,-0.165,2.644,-2.368,-1.636,-0.533,0.468,1.2,-1.431,-1.151,-1.276,-1.954,1.167,-0.938,-0.111,-2.636,-1.248,4.662,1.892,5.485,-1.137,1.589,-1.935,1.018",
          "tag_result":[
              {"score":0.728,"tag":"盆栽"},
              {"score":0.576,"tag":"植物"},
              {"score":0.539,"tag":"种植技术"},
              {"score":0.466,"tag":"农业技术"},
              {"score":0.458,"tag":"种植"}
              ],
          "video_height":1280,
          "video_width":720}\n',
        'app_id': '202209070402410****',
        'create_time': '2022-09-07T14:03:33.8+08:00',
        'id': 5,
        'message': 'success',
        'state': 2}},
       'message': 'success',
       'request_id': '9283066a-f414-40fd-8fd3-0f77c1ef****'}

    返回字段说明如下。

    参数

    描述

    request_id

    请求流水号,STRING类型。

    code

    请求状态码,STRING类型。

    message

    请求状态具体信息,STRING类型。返回示例如下:

    • success

    • Invalid Input - video data error - load video failed

    • Invalid Input - json format error - json parse runtime exception

    更多请求状态,详情请参见返回错误码说明

    data

    模型返回内容,Dict类型。具体返回字段说明,详情请参见data['job']内部字段

    表 7. data['job']内部字段

    参数

    描述

    id

    任务ID,即job_id,INT类型。

    app_id

    您的AppId,STRING类型。

    state

    任务状态码,INT类型,取值如下:

    • 0:任务初始化。

    • 1:任务执行中。

    • 2:任务完成。

    • 3:任务失败。

    message

    任务执行信息,STRING类型。取值如下:

    • success

    • video downloading

    create_time

    任务创建时间,STRING类型。

    Result

    模型返回结果,STRING类型。具体返回字段说明,详情请参见Result内部字段

    表 8. Result内部字段

    参数

    描述

    classification_result

    分类结果,LIST类型,按score(概率)降序排列。

    列长度由classification_top_k决定。

    仅当output_classificationTrue时,存在该字段。

    tag_result

    标签结果,按score(概率)降序排列。

    列长度由tag_top_k决定。

    仅当output_tagTrue时,存在该字段。

    score

    标签概率,FLOAT类型,精度精确到小数点后三位。

    class

    类别名,STRING类型。

    tag

    标签名,STRING类型。

    embedding_result

    64维视频特征,半角逗号(,)分隔,STRING类型。

    仅当output_embedding为True时,存在该字段。

    video_height

    视频像素高度,INT类型。

    video_width

    视频像素宽度,INT类型。

    duration

    视频时长,FLOAT类型。

  • 批量请求接口,请求代码示例如下

    from ai_service_python_sdk.client.api.ai_service_video_api import AiServiceVideoApi
    from ai_service_python_sdk.client.models.batch_video_request_videos import BatchVideoRequestVideos
    
    ai_service_api = AiServiceVideoApi(client)
    
    # 模型返回配置。
    configure = {
        'output_classification': True,
        'classification_top_k': 1,
        'output_tag': True,
        'tag_top_k': 5,
        'output_embedding': True
        }
    # 构建批量请求(视频URL + 视频标题)。
    videos = [
        BatchVideoRequestVideos('https://your_video_1_url.mp4', 'your_video_title_1'),
        BatchVideoRequestVideos('https://your_video_2_url.mp4', 'your_video_title_2')
        ]
    # 定制模型名称。
    model_name = ''
    # 请求服务。
    response = ai_service_api.batch_classify_label_video(videos, model_name, configure)
    # 请求流水号。
    request_id = response.request_id
    # 请求状态。
    code = response.code
    # 请求状态具体信息。
    message = response.message
    # 请求返回内容。
    data = response.data
    # batch id
    batch_id = response.data['batch_id']
    # 打印返回结果。
    print(response)

    返回结果示例如下。

    {'code': 'OK',
     'data': {'batch_id': 1},
     'message': 'success',
     'request_id': 'c59eb912-9df4-4afe-8129-23f7b6dc****'}

    从上述返回结果中获取batch_id,并使用以下代码进行结果查询。

    from ai_service_python_sdk.client.api.ai_service_job_api import AiServiceJobApi
    
    ai_service_job_api = AiServiceJobApi(client)
    # 结果查询。
    result = ai_service_job_api.get_batch_job_with_id(<YOUR-BATCH-ID>)
    # 打印返回结果。
    print(result)

    其中:<YOUR-BATCH-ID>:需要替换为请求服务时返回的batch_id,INT类型。

    查询结果示例如下。

    {'code': 'OK',
     'data': {'jobs': [{'Result': '{"classification_result":[{"class":"生活","score":0.998}],"duration":14.633333333333333,"embedding_result":"0.998,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.002","tag_result":[{"score":0.917,"tag":"盆栽"},{"score":0.777,"tag":"植物"},{"score":0.693,"tag":"园艺"},{"score":0.58,"tag":"幸福树"},{"score":0.509,"tag":"有字幕"}],"video_height":1280,"video_width":720}',
                        'app_id': '202209290847310****',
                        'batch_id': 13,
                        'create_time': '2022-10-26T18:13:20.928+08:00',
                        'id': 4090,
                        'message': 'success',
                        'object': 'https://your_video_1_url.mp4',
                        'state': 2},
                       {'Result': '{"classification_result":[{"class":"体育","score":0.998}],"duration":18.2,"embedding_result":"0.0,0.0,0.0,0.998,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.001,0.0,0.0,0.0,0.0,0.001,0.0,0.0,0.0,0.0","tag_result":[{"score":0.981,"tag":"全运会"},{"score":0.901,"tag":"乒乓球"},{"score":0.798,"tag":"运动"},{"score":0.583,"tag":"有字幕"},{"score":0.498,"tag":"乒乓球比赛"}],"video_height":568,"video_width":320}',
                        'app_id': '202209290847310****',
                        'batch_id': 13,
                        'create_time': '2022-10-26T18:13:20.928+08:00',
                        'id': 4091,
                        'message': 'success',
                        'object': 'https://your_video_2_url.mp4',
                        'state': 2}]},
     'message': 'success',
     'request_id': '73e4b48e-42b8-4347-9cb4-7a49c1f8****'}

    批量请求返回的data['jobs']为数组形式,具体字段说明如下。

    参数

    描述

    id

    批量任务中的单条数据ID,INT类型。

    batch_id

    批量任务ID,INT类型。

    app_id

    您的AppId,STRING类型。

    state

    任务状态码,INT类型,取值如下:

    • 0:任务初始化。

    • 1:任务执行中。

    • 2:任务完成。

    • 3:任务失败。

    message

    任务执行信息,STRING类型。取值如下:

    • success

    • video downloading

    create_time

    任务创建时间,STRING类型。

    object

    请求视频的URL,STRING类型。

    Result

    模型返回结果,STRING类型。

    说明

    与单次请求接口返回的Result内部字段相同。

返回错误码说明

使用Python SDK发送服务请求,返回的错误码及说明如下。

图像分析服务

请求服务错误。

HTTP状态码

code

message

说明

400

PARAMETER_ERROR

image is empty

请求图片为空。

note found appid

AppId填写错误。

Unmarshal type error: expected=string, got=number, field=image, offset=42, internal=json: cannot unmarshal number into Go struct field ImageRequest.image of type string

image参数类型错误。

401

PARAMETER_ERROR

sign error

TOKEN填写错误。

404

PARAMETER_ERROR

model not found

对应模型服务未部署。

422

SEVER_ERROR

以具体报错信息为准。

模型服务报错,具体原因,请参见message内容。

视频分析服务

  • 请求服务错误

    HTTP状态码

    code

    message

    说明

    400

    PARAMETER_ERROR

    not found appid

    AppId填写错误。

    401

    PARAMETER_ERROR

    sign error

    TOKEN填写错误。

    404

    PARAMETER_ERROR

    model not found

    对应模型服务未部署。

  • 结果查询错误

    state

    message

    说明

    3

    failed to download video, err=fetch resource failed\tcode = 404

    视频URL下载失败。

    3

    以具体报错信息为准。

    模型服务报错,具体原因见message内容。