DashScope 多模态向量 - 千问AI平台

POST

/services/embeddings/multimodal-embedding/multimodal-embedding

curl --location --request POST \
  'https://maas.qianwenaiapi.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": "Multimodal embedding model"},
            {"image": "https://example.com/image.jpg"},
            {"video": "https://example.com/video.mp4"}
        ]
    }
}'

{
  "output": {
    "embeddings": [
      {
        "index": 0,
        "embedding": [
          0
        ],
        "type": "text"
      }
    ]
  },
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 0
    },
    "output_tokens": 0,
    "total_tokens": 0,
    "image_tokens": 0
  },
  "request_id": "1fff9502-a6c5-9472-9ee1-73930fdd04c5"
}

将文本、图像和视频转换为统一语义空间中的数值向量，用于跨模态检索、相似度搜索和内容分类。

开始前：获取 API Key，将其设置为环境变量，如需使用 SDK 请先安装 DashScope SDK。

请求地址

HTTP：POST https://maas.qianwenaiapi.com/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding
SDK base_http_api_url：https://maas.qianwenaiapi.com/api/v1

模型概览

模型	支持模态	向量维度	单张图片大小
qwen3-vl-embedding	文本、图像、视频	2560（默认）、2048、1536、1024、768、512、256	10 MB
qwen2.5-vl-embedding	文本、图像、视频	2048、1024（默认）、768、512	5 MB
tongyi-embedding-vision-plus-2026-03-06	文本、图像、视频、多图	1152（默认）、1024、512、256、128、64	建议 5 MB，最大 10 MB
tongyi-embedding-vision-flash-2026-03-06	文本、图像、视频、多图	768（默认）、512、256、128、64	建议 5 MB，最大 10 MB
tongyi-embedding-vision-plus	文本、图像、视频、多图	1152	3 MB
tongyi-embedding-vision-flash	文本、图像、视频、多图	768	3 MB

使用说明

图像输入：公网 URL 或 Base64 数据 URI（data:image/{format};base64,{data}）。
多图输入：使用 multi_images 字段，值为图像 URL 列表，最多 8 张。
视频输入：必须为公网 URL。通过 parameters 中的 fps 参数控制采样帧率（取值范围 [0, 1]，默认 1.0）。

错误码

本 API 常见的错误码及排查方向如下。完整错误码请参见通用错误码。

错误码	HTTP 状态码	触发条件	排查建议
`InvalidApiKey`	401	API Key 无效或已过期，返回 `Invalid API-key provided.`	确认 `Authorization` 请求头为 `Bearer sk-xxx` 格式，且使用的是当前账号下有效的 API Key。
`BadRequest.EmptyModel`	400	请求中缺少 `model` 字段，返回 `Required parameter model missing from request.`	在请求体中补充 `model` 字段，取值使用本文模型列表中的模型名称。
`InvalidParameter`	400	`model` 取值不存在，返回 `Model not exist.`	核对 `model` 拼写，确认使用了本文模型列表中的模型名称。
`InvalidParameter`	400	`input.contents` 缺失或为空数组，返回 `input can not be empty: input.contents` 或 `contents input can not be empty: input.contents`	确认 `input.contents` 存在且为非空数组，数组中每个元素包含有效的 `text`、`image` 或 `video` 键。
`InvalidParameter`	400	`dimension` 取值不在所选模型支持的向量维度范围内。	按本文模型列表中该模型支持的向量维度取值；`multimodal-embedding-v1` 不支持 `dimension` 参数，固定为 1024 维。
`InternalError.Algo`	500	请求体结构不完整或 `input.contents` 元素格式异常，导致服务端处理失败。	检查请求体结构，确认 `input` 及 `input.contents` 字段存在且元素格式符合本文请求参数说明；结构无误仍持续报错时，携带 `request_id` 联系技术支持。

鉴权

string

header

必填

千问AI平台 API Key。详见获取 API Key。

请求体

application/json

enum<string>

必填

多模态向量嵌入的模型名称。

可选值：qwen3-vl-embedding,qwen2.5-vl-embedding,tongyi-embedding-vision-plus,tongyi-embedding-vision-flash,tongyi-embedding-vision-plus-2026-03-06,tongyi-embedding-vision-flash-2026-03-06,multimodal-embedding-v1

示例:tongyi-embedding-vision-plus

object

必填

包含内容项的输入数据。

显示子属性

object[]

必填

内容项列表，每项为包含一个或多个模态键（text、image、video、multi_images）的对象。生成独立向量时每个对象只使用一种模态；生成融合向量时将多种模态组合在同一对象中。

显示子属性

string

要嵌入的文本内容。

string

图像 URL（公开的 HTTP/HTTPS 链接）或 Base64 数据 URI（data:image/{format};base64,{data}）。

string

视频 URL（必须为公开链接）。

string[]

用于多图嵌入的图像 URL 列表，最多 8 张图像，仅 tongyi-embedding-vision-plus 和 tongyi-embedding-vision-flash 支持。

取值范围：items <= 8

object

多模态向量嵌入的参数。

显示子属性

enum<string>

默认值"dense"

输出格式，目前仅支持 dense。

可选值：dense

integer

输出向量维度，支持的值因模型而异，详见模型概览表中的默认值与可选项。

number

默认值1

视频帧采样率，范围 [0, 1]，默认值：1.0。

取值范围：0 <= x <= 1

string

自定义任务指令，建议使用英文，通常可使检索任务效果提升 1-5%。

boolean

默认值false

是否生成融合向量。仅 qwen3-vl-embedding 模型支持。设置为 true 时将 contents 中的所有多模态内容融合为 1 个向量；默认为 false，各模态独立生成向量。

enum<integer>

默认值1

输入分辨率档位（0/1/2/3），对应单图 token 为 127/402/578/1026，默认值 1。仅 tongyi-embedding-vision-plus-2026-03-06 和 tongyi-embedding-vision-flash-2026-03-06 支持。

可选值：0,1,2,3

integer

默认值8

视频最大采样帧数上限，最大不超过 64，默认值 8。仅 tongyi-embedding-vision-plus-2026-03-06 和 tongyi-embedding-vision-flash-2026-03-06 支持。

取值范围：x <= 64

响应

200-application/json

object

显示子属性

object[]

向量嵌入结果列表。

显示子属性

integer

在输入内容列表中的位置索引。

number[]

浮点数向量。

enum<string>

本条嵌入结果的内容类型。

可选值：text,image,video

object

Token 用量统计。不同模型返回的字段存在差异：tongyi-embedding-vision-* 系列返回 input_tokens（含文本和图片 Token 总和）、input_tokens_details、output_tokens、total_tokens；其他模型返回的字段可能不同，详见各字段说明。

显示子属性

integer

本次请求输入内容的 Token 数目。对于 tongyi-embedding-vision-* 系列模型，该值包含文本和图片/视频 Token 的总和。

object

输入 Token 的详细分类信息。仅 tongyi-embedding-vision-* 系列模型返回此字段。

显示子属性

integer

输入内容中图片或视频等视觉部分消耗的 Token 数量，不包含文本（文本部分见 text_tokens）。图片消耗的 Token 数量与输入图片的分辨率有关，分辨率越高消耗的 Token 越多；若输入为视频，系统会先对视频抽帧，再基于抽帧结果计算 Token。

integer

输入内容中文本部分消耗的 Token 数量（不包含图片或视频等视觉部分）。

integer

本次请求输出的 Token 数目。仅 tongyi-embedding-vision-* 系列模型返回此字段。

integer

输入与输出的 Token 总数。

integer

本次请求输入的图片或视频等视觉部分消耗的 Token 数量（不包含文本）。图片消耗的 Token 数量与输入图片的分辨率有关；系统会对输入视频进行抽帧处理，帧数上限受系统配置控制，随后基于处理结果计算 Token。仅 qwen3-vl-embedding、qwen2.5-vl-embedding 和 multimodal-embedding-v1 返回此字段（作为顶层字段），tongyi-embedding-vision-* 系列模型的图片 Token 包含在 input_tokens_details.image_tokens 中。

string

唯一请求标识符。

示例:1fff9502-a6c5-9472-9ee1-73930fdd04c5

​请求地址

​模型概览

​使用说明

​错误码

鉴权

请求体

响应

请求地址

模型概览

使用说明

错误码