多媒体分析：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

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

from ai_service_python_sdk.client.api_client import ApiClient
client = ApiClient('<HOST>', '<YOUR-APPID>', '<YOUR-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)

参数说明如下。

返回结果示例如下。

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

返回字段说明如下。

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

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)

参数说明如下。

返回结果如下。

{'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'}

返回字段说明如下。

提供图像多标签打标能力，支持输出概率较高的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)

参数说明如下。

返回结果示例如下。

{'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'}

返回字段说明如下。

提供短视频质量评估能力，返回[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内部参数。 说明 当configure为None时，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_classification为True时，存在该字段。
  tag_result	标签结果，按score（概率）降序排列。 列长度由tag_top_k决定。 仅当output_tag为True时，存在该字段。
  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内部字段相同。

请求服务错误。