Multimodal-Embedding API详情

多模态向量模型将文本、图像或视频转换成统一的1024维浮点数向量,适用于视频分类、图像分类、图文检索等。

核心能力

  • 跨模态检索:实现以文搜图、以图搜视频、以图搜图等跨模态的语义搜索。

  • 语义相似度计算:在统一的向量空间中,衡量不同模态内容之间的语义相似性。

  • 内容分类与聚类:基于内容的语义向量进行智能分组、打标和聚类分析。

关键特性:所有模态(文本、图片、视频)生成的向量都位于同一语义空间,可直接通过计算余弦相似度等方法进行跨模态匹配与比较。关于模型选型和应用方法的更多介绍,参考文本与多模态向量化
模型介绍、选型建议和使用方法请参考文本与多模态向量化

模型概览

模型名称

向量维度

文本长度限制

图片/视频大小限制

单价(每千输入Token)

tongyi-embedding-vision-plus

1,152

1,024 Token

图片大小: ≤3MB, 数量≤8
视频: ≤10MB

0.0005

tongyi-embedding-vision-flash

768

1,024 Token

图片大小: ≤3MB, 数量≤8
视频: ≤10MB

图片/视频:0.0002

文本:0.0005

multimodal-embedding-v1

1,024

512 Token

图片大小: ≤3MB, 数量1
视频: ≤10MB

免费试用,无Token额度限制。

通用多模态向量API使用过程中存在以下输入类型与格式限制

输入类型

语种/格式限制

文本

中/英文

图片

JPG、PNG、BMP,支持以Base64格式或URL形式输入。

多图片

视频

MP4、MPEG、MPG、WEBM、AVI、FLV、MKV、MOV

接口支持单段文字、单张图片或单个视频文件,允许不同类型单文件组合(如文字+图片)。每次调用仅限一种组合形式,且文件需符合表中长度/大小要求。

前提条件

您需要已获取API Key配置API Key到环境变量。如果通过SDK调用,还需要安装DashScope SDK

HTTP调用

POST https://dashscope.aliyuncs.com/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding

请求

多模态向量

curl --silent --location --request POST 'https://dashscope.aliyuncs.com/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "tongyi-embedding-vision-plus",
    "input": {
        "contents": [ 
            {"text": "多模态向量模型"},
            {"image": "https://img.alicdn.com/imgextra/i3/O1CN01rdstgY1uiZWt8gqSL_!!6000000006071-0-tps-1970-356.jpg"},
            {"video": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250107/lbcemt/new+video.mp4"},
            {"multi_images": [
                "https://img.alicdn.com/imgextra/i2/O1CN019eO00F1HDdlU4Syj5_!!6000000000724-2-tps-2476-1158.png",
                "https://img.alicdn.com/imgextra/i2/O1CN01dSYhpw1nSoamp31CD_!!6000000005089-2-tps-1765-1639.png"
                ]
              }
        ]
    }
}'

请求头(Headers)

Content-Type string (必选)

请求内容类型。可设置为application/json 或者text/event-stream(开启 SSE 响应)。

Content-Type string (必选)

请求内容类型。此参数必须设置为application/json

Authorization string(必选)

请求身份认证。接口使用阿里云百炼API-Key进行身份认证。示例值:Bearer sk-xxxx。

请求体(Request Body)

model string(必选)

模型名称。设置为模型概览中的模型名称。

input object (必选)

输入内容。

属性

contents array(必选)

待处理的内容列表。每个元素是一个字典或者字符串,用于指定内容的类型和值。格式为{"模态类型": "输入字符串或图像、视频url"}。支持text, image, videomulti_images四种模态类型。

  • 文本:keytext。value为字符串形式。也可不通过dict直接传入字符串。

  • 图片:keyimage。value可以是公开可访问的URL,或Base64编码的Data URI。Base64格式为 data:image/{format};base64,{data},其中 {format} 是图片格式(如 jpeg, png),{data}Base64编码字符串。

  • 多图片:仅tongyi-embedding-vision-plustongyi-embedding-vision-flash模型支持此类型。keymulti_images,value是多图序列列表,每条为一个图片,格式要求如上方所示,图片数量最多为8张。

  • 视频:keyvideo,value必须是公开可访问的URL。

parameters object (可选)

属性

top_n int(可选)

返回排序后的top_n个文档。如果指定的值大于文档总数,将返回全部文档。未指定时默认返回全部文档。

return_documents bool(可选)

是否在排序结果中返回文档原文。默认值false,以减少网络传输开销。

响应

成功响应

{
    "output": {
        "embeddings": [
            {
                "index": 0,
                "embedding": [
                    -0.026611328125,
                    -0.016571044921875,
                    -0.02227783203125,
                    ...
                ],
                "type": "text"
            },
            {
                "index": 1,
                "embedding": [
                    0.051544189453125,
                    0.007717132568359375,
                    0.026611328125,
                    ...
                ],
                "type": "image"
            },
            {
                "index": 2,
                "embedding": [
                    -0.0217437744140625,
                    -0.016448974609375,
                    0.040679931640625,
                    ...
                ],
                "type": "video"
            }
        ]
    },
    "usage": {
        "input_tokens": 10,
        "image_tokens": 896
    },
    "request_id": "1fff9502-a6c5-9472-9ee1-73930fdd04c5"
}

异常响应

{
    "code":"InvalidApiKey",
    "message":"Invalid API-key provided.",
    "request_id":"fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1"
}

output object

任务输出信息。

属性

embeddings array

向量结果列表,每个对象对应输入列表中的一个元素。

属性

index int

结果在输入列表中的索引。

embedding array

生成的1024维向量。

type string

结果对应的输入类型(text/image/video/multi_images)。

request_id string

请求唯一标识。可用于请求明细溯源和问题排查。

code string

请求失败的错误码。请求成功时不会返回此参数,详情请参见错误信息

message string

请求失败的详细信息。请求成功时不会返回此参数,详情请参见错误信息

usage object

输出信息统计。

属性

input_tokens int

本次请求输入内容的 Token 数目。

image_tokens int

本次请求输入的图片或视频的Token数量。系统会对输入视频进行抽帧处理,帧数上限受系统配置控制,随后基于处理结果计算 Token。

image_count int

本次请求输入的图片数量。

duration int

本次请求输入的视频时长(秒)。

SDK使用

当前版本的 SDK 调用与原生 HTTP 调用的请求体结构不一致。SDK 的input参数对应了HTTP中的input.contents。

代码示例

生成图片Embedding示例

使用图片URL

import dashscope
import json
from http import HTTPStatus
# 实际使用中请将url地址替换为您的图片url地址
image = "https://dashscope.oss-cn-beijing.aliyuncs.com/images/256_1.png"
input = [{'image': image}]
# 调用模型接口
resp = dashscope.MultiModalEmbedding.call(
    model="tongyi-embedding-vision-plus",
    input=input
)

if resp.status_code == HTTPStatus.OK:
    result = {
        "status_code": resp.status_code,
        "request_id": getattr(resp, "request_id", ""),
        "code": getattr(resp, "code", ""),
        "message": getattr(resp, "message", ""),
        "output": resp.output,
        "usage": resp.usage
    }
    print(json.dumps(result, ensure_ascii=False, indent=4))

使用本地图片

您可以参考以下示例代码,将本地图片转换为Base64格式后调用multimodal-embedding-v1模型进行向量化处理。

import dashscope
import base64
import json
from http import HTTPStatus
# 读取图片并转换为Base64,实际使用中请将xxx.png替换为您的图片文件名或路径
image_path = "xxx.png"
with open(image_path, "rb") as image_file:
    # 读取文件并转换为Base64
    base64_image = base64.b64encode(image_file.read()).decode('utf-8')
# 设置图像格式
image_format = "png"  # 根据实际情况修改,比如jpg、bmp 等
image_data = f"data:image/{image_format};base64,{base64_image}"
# 输入数据
input = [{'image': image_data}]

# 调用模型接口
resp = dashscope.MultiModalEmbedding.call(
    model="tongyi-embedding-vision-plus",
    input=input
)
if resp.status_code == HTTPStatus.OK:
    result = {
        "status_code": resp.status_code,
        "request_id": getattr(resp, "request_id", ""),
        "code": getattr(resp, "code", ""),
        "message": getattr(resp, "message", ""),
        "output": resp.output,
        "usage": resp.usage
    }
    print(json.dumps(result, ensure_ascii=False, indent=4))

生成视频Embedding示例

多模态向量化模型目前仅支持以URL形式输入视频文件,暂不支持直接传入本地视频。
import dashscope
import json
from http import HTTPStatus
# 实际使用中请将url地址替换为您的视频url地址
video = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250107/lbcemt/new+video.mp4"
input = [{'video': video}]
# 调用模型接口
resp = dashscope.MultiModalEmbedding.call(
    model="tongyi-embedding-vision-plus",
    input=input
)

if resp.status_code == HTTPStatus.OK:
    result = {
        "status_code": resp.status_code,
        "request_id": getattr(resp, "request_id", ""),
        "code": getattr(resp, "code", ""),
        "message": getattr(resp, "message", ""),
        "output": resp.output,
        "usage": resp.usage
    }
    print(json.dumps(result, ensure_ascii=False, indent=4))

生成文本Embedding示例

import dashscope
import json
from http import HTTPStatus

text = "通用多模态表征模型示例"
input = [{'text': text}]
# 调用模型接口
resp = dashscope.MultiModalEmbedding.call(
    model="tongyi-embedding-vision-plus",
    input=input
)

if resp.status_code == HTTPStatus.OK:
    result = {
        "status_code": resp.status_code,
        "request_id": getattr(resp, "request_id", ""),
        "code": getattr(resp, "code", ""),
        "message": getattr(resp, "message", ""),
        "output": resp.output,
        "usage": resp.usage
    }
    print(json.dumps(result, ensure_ascii=False, indent=4))

输出示例

{
    "status_code": 200,
    "request_id": "b5623e99-ea0c-9509-9b25-20bcc99d03e9",
    "code": "",
    "message": "",
    "output": {
        "embeddings": [
            {
                "index": 0,
                "embedding": [
                    -0.020782470703125,
                    -0.01399993896484375,
                    -0.0229949951171875,
                    ...
                ],
                "type": "text"
            }
        ]
    },
    "usage": {
        "input_tokens": 12,
        "image_tokens": 0
    }
}

错误码

如果模型调用失败并返回报错信息,请参见错误信息进行解决。